@modelprofile.com/flexharness-agent 12.1.3 → 12.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist_ts_agent/classes.sessionengine.js +17 -2
- package/dist_ts_agent/index.d.ts +2 -1
- package/dist_ts_agent/index.js +2 -1
- package/dist_ts_agent/plugins.d.ts +3 -3
- package/dist_ts_agent/plugins.js +3 -3
- package/dist_ts_agent/smartagent.attachments.d.ts +11 -0
- package/dist_ts_agent/smartagent.attachments.js +65 -0
- package/dist_ts_agent/smartagent.interfaces.d.ts +36 -0
- package/dist_ts_agent/smartagent.interfaces.js +1 -1
- package/package.json +2 -2
- package/readme.md +26 -0
- package/ts_agent/classes.sessionengine.ts +18 -1
- package/ts_agent/index.ts +4 -0
- package/ts_agent/plugins.ts +10 -2
- package/ts_agent/readme.md +26 -0
- package/ts_agent/smartagent.attachments.ts +79 -0
- package/ts_agent/smartagent.interfaces.ts +39 -0
package/dist_ts_agent/index.d.ts
CHANGED
|
@@ -9,11 +9,12 @@ export { ToolRegistry } from './smartagent.classes.toolregistry.js';
|
|
|
9
9
|
export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
|
|
10
10
|
export type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
|
|
11
11
|
export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
|
|
12
|
+
export { assertAttachmentResolver, createAttachmentDownload } from './smartagent.attachments.js';
|
|
12
13
|
export { endModelStreamAtAbort, MODEL_ABORT_GRACE_MS } from './smartagent.modelabort.js';
|
|
13
14
|
export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
|
|
14
15
|
export { AgentGenerationLeaseCleanupError, ContextOverflowError, } from './smartagent.interfaces.js';
|
|
15
16
|
export { AGENT_TOOL_RESULT_FILE_MAX_BYTES, AgentEventStoreConflictError, applyAgentEventChange, assertAgentEventChange, InMemoryAgentEventStore, validateAgentEventArchive, validateAgentEventSnapshot, } from './smartagent.persistence.js';
|
|
16
|
-
export type { IAgentCacheOptions, ISmartAiCacheDispatch, IAgentContextOverflowInvocationOptions, IAgentContextBuildOptions, IAgentContextCompactionOptions, IAgentCompactOptions, IAgentEventRetentionOptions, IAgentBeginGenerationOptions, IAgentFinalizeGenerationOptions, IAgentGenerateOptions, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentGenerationPreparationContext, IAgentRunOptions, IAgentRunResult, IAgentSession, IAgentSessionAbortOptions, IAgentSessionChange, IAgentSessionOptions, IAgentScheduleGenerateOptions, IAgentToolCallRecord, IAgentToolCallStartEvent, IAgentToolCallUpdateEvent, IAgentUsage, ProviderOptions, TAgentCacheRetention, TAgentCacheSetting, TAgentPrompt, TAgentContextBuilder, TAgentContextCompactor, TAgentGenerationPrepare, TAgentModelCallUnreportedReason, TAgentModelCallUsage, TAgentModelCallUsageEvent, TAgentModelCallUsageReporter, TAgentModelCallUsageSource, TAgentObservedModelCallUsage, TAgentSessionChangeListener, TAgentToolCallClassifier, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from './smartagent.interfaces.js';
|
|
17
|
+
export type { IAgentAttachmentRequest, IAgentAttachmentResolver, IAgentCacheOptions, IAgentResolvedAttachment, ISmartAiCacheDispatch, IAgentContextOverflowInvocationOptions, IAgentContextBuildOptions, IAgentContextCompactionOptions, IAgentCompactOptions, IAgentEventRetentionOptions, IAgentBeginGenerationOptions, IAgentFinalizeGenerationOptions, IAgentGenerateOptions, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentGenerationPreparationContext, IAgentRunOptions, IAgentRunResult, IAgentSession, IAgentSessionAbortOptions, IAgentSessionChange, IAgentSessionOptions, IAgentScheduleGenerateOptions, IAgentToolCallRecord, IAgentToolCallStartEvent, IAgentToolCallUpdateEvent, IAgentUsage, ProviderOptions, TAgentCacheRetention, TAgentCacheSetting, TAgentPrompt, TAgentContextBuilder, TAgentContextCompactor, TAgentGenerationPrepare, TAgentModelCallUnreportedReason, TAgentModelCallUsage, TAgentModelCallUsageEvent, TAgentModelCallUsageReporter, TAgentModelCallUsageSource, TAgentObservedModelCallUsage, TAgentSessionChangeListener, TAgentToolCallClassifier, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from './smartagent.interfaces.js';
|
|
17
18
|
export type { IAgentEventArchive, IAgentEventChange, IAgentEventSnapshot, IAgentEventStore, } from './smartagent.persistence.js';
|
|
18
19
|
export type { IAgentEventBase, IAgentRuntimeEventPayload, IArchivedAgentGenerationTransaction, IAssistantMessageEvent, IContextCompactionEvent, IGenerationBegunEvent, IGenerationExecutionCompletedEvent, IGenerationExecutionStartedEvent, IGenerationOutcomeEvent, IModelMessageEvent, IModelMessagesToEventsOptions, IModelMessageEventIdentityCoordinates, IRuntimeEvent, ISystemMessageEvent, IToolCallEvent, IToolExecutionIntentEvent, IToolExecutionReconciliationEvent, IToolResultEvent, IUserMessageEvent, TAgentAssistantMessage, TAgentConversationEvent, TAgentControlEvent, TAgentEvent, TAgentEventInput, TAgentSystemMessage, TAgentGenerationOutcome, TAgentToolCallPart, TAgentToolMessage, TAgentToolResultOutput, TAgentToolResultPart, TAgentUserMessage, TModelMessageEmittedEventKind, TModelMessageEventIdentityFactory, TToolExecutionReconciliation, } from './smartagent.events.js';
|
|
19
20
|
export type { IAgentGenerationTransaction, TAgentGenerationTransactionState, } from './smartagent.transactions.js';
|
package/dist_ts_agent/index.js
CHANGED
|
@@ -7,6 +7,7 @@ export { AgentPendingInputQueue, AgentPendingInputRejectedError, } from './smart
|
|
|
7
7
|
export { ToolRegistry } from './smartagent.classes.toolregistry.js';
|
|
8
8
|
export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
|
|
9
9
|
export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
|
|
10
|
+
export { assertAttachmentResolver, createAttachmentDownload } from './smartagent.attachments.js';
|
|
10
11
|
export { endModelStreamAtAbort, MODEL_ABORT_GRACE_MS } from './smartagent.modelabort.js';
|
|
11
12
|
export { AgentGenerationLeaseCleanupError, ContextOverflowError, } from './smartagent.interfaces.js';
|
|
12
13
|
export { AGENT_TOOL_RESULT_FILE_MAX_BYTES, AgentEventStoreConflictError, applyAgentEventChange, assertAgentEventChange, InMemoryAgentEventStore, validateAgentEventArchive, validateAgentEventSnapshot, } from './smartagent.persistence.js';
|
|
@@ -15,4 +16,4 @@ export * from './tool.persistence.js';
|
|
|
15
16
|
export * from './tool.adapter.js';
|
|
16
17
|
export { tool, jsonSchema, stepCountIs, z } from './plugins.js';
|
|
17
18
|
export { FileAgentEventStore } from './persistence.file.js';
|
|
18
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
19
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMsMEJBQTBCLEVBQzFCLHlCQUF5QixHQUMxQixNQUFNLDhCQUE4QixDQUFDO0FBQ3RDLE9BQU8sRUFDTCxnQkFBZ0IsRUFDaEIsa0JBQWtCLEVBQ2xCLDBCQUEwQixHQUMzQixNQUFNLHdCQUF3QixDQUFDO0FBQ2hDLE9BQU8sRUFDTCxzQkFBc0IsRUFDdEIsOEJBQThCLEdBQy9CLE1BQU0sOEJBQThCLENBQUM7QUFNdEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBRXZFLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ3BFLE9BQU8sRUFBRSx3QkFBd0IsRUFBRSx3QkFBd0IsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ2pHLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxvQkFBb0IsRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBRXpGLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyw0QkFBNEIsRUFDNUIscUJBQXFCLEVBQ3JCLHNCQUFzQixFQUN0Qix1QkFBdUIsRUFDdkIseUJBQXlCLEVBQ3pCLDBCQUEwQixHQUMzQixNQUFNLDZCQUE2QixDQUFDO0FBK0ZyQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxPQUFPLEVBQUUsSUFBSSxFQUFFLFVBQVUsRUFBRSxXQUFXLEVBQUUsQ0FBQyxFQUFFLE1BQU0sY0FBYyxDQUFDO0FBRWhFLE9BQU8sRUFBRSxtQkFBbUIsRUFBb0MsTUFBTSx1QkFBdUIsQ0FBQyJ9
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { asSchema, streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
|
|
2
|
-
export { asSchema, streamText, generateText, stepCountIs, wrapLanguageModel };
|
|
3
|
-
export type { AssistantModelMessage, LanguageModelUsage, ModelMessage, StepResult, SystemModelMessage, ToolSet, ToolModelMessage, ToolExecutionOptions, StreamTextResult, UserModelMessage, } from 'ai';
|
|
1
|
+
import { asSchema, createDownload, streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
|
|
2
|
+
export { asSchema, createDownload, streamText, generateText, stepCountIs, wrapLanguageModel };
|
|
3
|
+
export type { AssistantModelMessage, Experimental_DownloadFunction, LanguageModelUsage, ModelMessage, StepResult, SystemModelMessage, ToolSet, ToolModelMessage, ToolExecutionOptions, StreamTextResult, UserModelMessage, } from 'ai';
|
|
4
4
|
import { applySmartAiCacheProviderOptions, bindSmartAiCachePolicyObserver, createModelLimitInfo, createSmartAiCachingMiddleware, deriveSmartAiPromptCacheKey, getSmartAiCacheProviderOptions, getSmartAiCacheWaitMs, observeSmartAiCacheDispatch, isModelLimitError, isModelLimitInfo, jsonSchema, ModelLimitError, openAiRoutesPromptCacheAutomatically, readRetryAfterMs, resolveSmartAiCacheProvider, tool } from '@modelprofile.com/flexharness-models';
|
|
5
5
|
export { applySmartAiCacheProviderOptions, bindSmartAiCachePolicyObserver, createModelLimitInfo, createSmartAiCachingMiddleware, deriveSmartAiPromptCacheKey, getSmartAiCacheProviderOptions, getSmartAiCacheWaitMs, observeSmartAiCacheDispatch, isModelLimitError, isModelLimitInfo, ModelLimitError, openAiRoutesPromptCacheAutomatically, readRetryAfterMs, resolveSmartAiCacheProvider, tool, jsonSchema, };
|
|
6
6
|
export type { ISmartAiCacheOptions, ISmartAiCacheDispatch, ISmartAiPromptCacheTool, TSmartAiLanguageModel, TSmartAiCacheRetention, TSmartAiCacheSetting, TSmartAiProviderOptions as ProviderOptions, } from '@modelprofile.com/flexharness-models';
|
package/dist_ts_agent/plugins.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
// ai-sdk core
|
|
2
|
-
import { asSchema, streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
|
|
3
|
-
export { asSchema, streamText, generateText, stepCountIs, wrapLanguageModel };
|
|
2
|
+
import { asSchema, createDownload, streamText, generateText, stepCountIs, wrapLanguageModel, } from 'ai';
|
|
3
|
+
export { asSchema, createDownload, streamText, generateText, stepCountIs, wrapLanguageModel };
|
|
4
4
|
// model contracts and AI SDK
|
|
5
5
|
import { applySmartAiCacheProviderOptions, bindSmartAiCachePolicyObserver, createModelLimitInfo, createSmartAiCachingMiddleware, deriveSmartAiPromptCacheKey, getSmartAiCacheProviderOptions, getSmartAiCacheWaitMs, observeSmartAiCacheDispatch, isModelLimitError, isModelLimitInfo, jsonSchema, ModelLimitError, openAiRoutesPromptCacheAutomatically, readRetryAfterMs, resolveSmartAiCacheProvider, tool, } from '@modelprofile.com/flexharness-models';
|
|
6
6
|
export { applySmartAiCacheProviderOptions, bindSmartAiCachePolicyObserver, createModelLimitInfo, createSmartAiCachingMiddleware, deriveSmartAiPromptCacheKey, getSmartAiCacheProviderOptions, getSmartAiCacheWaitMs, observeSmartAiCacheDispatch, isModelLimitError, isModelLimitInfo, ModelLimitError, openAiRoutesPromptCacheAutomatically, readRetryAfterMs, resolveSmartAiCacheProvider, tool, jsonSchema, };
|
|
7
7
|
// zod
|
|
8
8
|
import { z } from 'zod';
|
|
9
9
|
export { z };
|
|
10
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
10
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYztBQUNkLE9BQU8sRUFDTCxRQUFRLEVBQ1IsY0FBYyxFQUNkLFVBQVUsRUFDVixZQUFZLEVBQ1osV0FBVyxFQUNYLGlCQUFpQixHQUNsQixNQUFNLElBQUksQ0FBQztBQUVaLE9BQU8sRUFBRSxRQUFRLEVBQUUsY0FBYyxFQUFFLFVBQVUsRUFBRSxZQUFZLEVBQUUsV0FBVyxFQUFFLGlCQUFpQixFQUFFLENBQUM7QUFnQjlGLDZCQUE2QjtBQUM3QixPQUFPLEVBQ0wsZ0NBQWdDLEVBQ2hDLDhCQUE4QixFQUM5QixvQkFBb0IsRUFDcEIsOEJBQThCLEVBQzlCLDJCQUEyQixFQUMzQiw4QkFBOEIsRUFDOUIscUJBQXFCLEVBQ3JCLDJCQUEyQixFQUMzQixpQkFBaUIsRUFDakIsZ0JBQWdCLEVBQ2hCLFVBQVUsRUFDVixlQUFlLEVBQ2Ysb0NBQW9DLEVBQ3BDLGdCQUFnQixFQUNoQiwyQkFBMkIsRUFDM0IsSUFBSSxHQUNMLE1BQU0sc0NBQXNDLENBQUM7QUFFOUMsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyw4QkFBOEIsRUFDOUIsb0JBQW9CLEVBQ3BCLDhCQUE4QixFQUM5QiwyQkFBMkIsRUFDM0IsOEJBQThCLEVBQzlCLHFCQUFxQixFQUNyQiwyQkFBMkIsRUFDM0IsaUJBQWlCLEVBQ2pCLGdCQUFnQixFQUNoQixlQUFlLEVBQ2Ysb0NBQW9DLEVBQ3BDLGdCQUFnQixFQUNoQiwyQkFBMkIsRUFDM0IsSUFBSSxFQUNKLFVBQVUsR0FDWCxDQUFDO0FBa0JGLE1BQU07QUFDTixPQUFPLEVBQUUsQ0FBQyxFQUFFLE1BQU0sS0FBSyxDQUFDO0FBRXhCLE9BQU8sRUFBRSxDQUFDLEVBQUUsQ0FBQyJ9
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import * as plugins from './plugins.js';
|
|
2
|
+
import type { IAgentAttachmentResolver } from './smartagent.interfaces.js';
|
|
3
|
+
/** Throws a `TypeError` unless `resolver` is a usable attachment resolver. */
|
|
4
|
+
export declare function assertAttachmentResolver(resolver: IAgentAttachmentResolver): void;
|
|
5
|
+
/**
|
|
6
|
+
* The AI SDK download function of one model call. URLs of the resolver's schemes are read through
|
|
7
|
+
* the resolver, once per URL however many steps send them; every other URL keeps the AI SDK's
|
|
8
|
+
* default handling: passed through when the model reads it, downloaded otherwise.
|
|
9
|
+
* Returns `undefined` without a resolver, which leaves the AI SDK's default in place.
|
|
10
|
+
*/
|
|
11
|
+
export declare function createAttachmentDownload(resolver: IAgentAttachmentResolver | undefined, abortSignal?: AbortSignal): plugins.Experimental_DownloadFunction | undefined;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import * as plugins from './plugins.js';
|
|
2
|
+
const ATTACHMENT_SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*$/;
|
|
3
|
+
/** Schemes the AI SDK and the providers already give a meaning. */
|
|
4
|
+
const RESERVED_ATTACHMENT_SCHEMES = new Set(['data', 'file', 'http', 'https']);
|
|
5
|
+
/** Throws a `TypeError` unless `resolver` is a usable attachment resolver. */
|
|
6
|
+
export function assertAttachmentResolver(resolver) {
|
|
7
|
+
if (typeof resolver !== 'object' || resolver === null) {
|
|
8
|
+
throw new TypeError('attachmentResolver must be an object.');
|
|
9
|
+
}
|
|
10
|
+
if (typeof resolver.resolve !== 'function') {
|
|
11
|
+
throw new TypeError('attachmentResolver.resolve must be a function.');
|
|
12
|
+
}
|
|
13
|
+
if (!Array.isArray(resolver.schemes) || resolver.schemes.length === 0) {
|
|
14
|
+
throw new TypeError('attachmentResolver.schemes must name at least one scheme.');
|
|
15
|
+
}
|
|
16
|
+
for (const scheme of resolver.schemes) {
|
|
17
|
+
if (typeof scheme !== 'string' || !ATTACHMENT_SCHEME_PATTERN.test(scheme)) {
|
|
18
|
+
throw new TypeError(`attachmentResolver scheme ${JSON.stringify(scheme)} must be a lowercase URL scheme without the colon.`);
|
|
19
|
+
}
|
|
20
|
+
if (RESERVED_ATTACHMENT_SCHEMES.has(scheme)) {
|
|
21
|
+
throw new TypeError(`attachmentResolver cannot claim the ${scheme} scheme.`);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* The AI SDK download function of one model call. URLs of the resolver's schemes are read through
|
|
27
|
+
* the resolver, once per URL however many steps send them; every other URL keeps the AI SDK's
|
|
28
|
+
* default handling: passed through when the model reads it, downloaded otherwise.
|
|
29
|
+
* Returns `undefined` without a resolver, which leaves the AI SDK's default in place.
|
|
30
|
+
*/
|
|
31
|
+
export function createAttachmentDownload(resolver, abortSignal) {
|
|
32
|
+
if (!resolver)
|
|
33
|
+
return undefined;
|
|
34
|
+
const protocols = new Set(resolver.schemes.map((scheme) => `${scheme}:`));
|
|
35
|
+
const resolved = new Map();
|
|
36
|
+
const download = plugins.createDownload();
|
|
37
|
+
const resolve = (url) => {
|
|
38
|
+
let attachment = resolved.get(url.href);
|
|
39
|
+
if (!attachment) {
|
|
40
|
+
attachment = resolver.resolve({ url, abortSignal }).then((result) => checkResolvedAttachment(url, result));
|
|
41
|
+
resolved.set(url.href, attachment);
|
|
42
|
+
// A failed read is not kept: the next step that sends the URL asks again.
|
|
43
|
+
attachment.catch(() => {
|
|
44
|
+
if (resolved.get(url.href) === attachment)
|
|
45
|
+
resolved.delete(url.href);
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
return attachment;
|
|
49
|
+
};
|
|
50
|
+
return (requests) => Promise.all(requests.map(async ({ url, isUrlSupportedByModel }) => {
|
|
51
|
+
if (protocols.has(url.protocol))
|
|
52
|
+
return await resolve(url);
|
|
53
|
+
return isUrlSupportedByModel ? null : await download({ url, abortSignal });
|
|
54
|
+
}));
|
|
55
|
+
}
|
|
56
|
+
function checkResolvedAttachment(url, result) {
|
|
57
|
+
if (!(result?.data instanceof Uint8Array)) {
|
|
58
|
+
throw new TypeError(`The attachment resolver returned no bytes for ${url.href}.`);
|
|
59
|
+
}
|
|
60
|
+
if (typeof result.mediaType !== 'string' || result.mediaType.trim() === '') {
|
|
61
|
+
throw new TypeError(`The attachment resolver returned no media type for ${url.href}.`);
|
|
62
|
+
}
|
|
63
|
+
return { data: result.data, mediaType: result.mediaType };
|
|
64
|
+
}
|
|
65
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5hdHRhY2htZW50cy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3NtYXJ0YWdlbnQuYXR0YWNobWVudHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFNeEMsTUFBTSx5QkFBeUIsR0FBRyxxQkFBcUIsQ0FBQztBQUN4RCxtRUFBbUU7QUFDbkUsTUFBTSwyQkFBMkIsR0FBRyxJQUFJLEdBQUcsQ0FBQyxDQUFDLE1BQU0sRUFBRSxNQUFNLEVBQUUsTUFBTSxFQUFFLE9BQU8sQ0FBQyxDQUFDLENBQUM7QUFFL0UsOEVBQThFO0FBQzlFLE1BQU0sVUFBVSx3QkFBd0IsQ0FBQyxRQUFrQztJQUN6RSxJQUFJLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSxRQUFRLEtBQUssSUFBSSxFQUFFLENBQUM7UUFDdEQsTUFBTSxJQUFJLFNBQVMsQ0FBQyx1Q0FBdUMsQ0FBQyxDQUFDO0lBQy9ELENBQUM7SUFDRCxJQUFJLE9BQU8sUUFBUSxDQUFDLE9BQU8sS0FBSyxVQUFVLEVBQUUsQ0FBQztRQUMzQyxNQUFNLElBQUksU0FBUyxDQUFDLGdEQUFnRCxDQUFDLENBQUM7SUFDeEUsQ0FBQztJQUNELElBQUksQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQUMsSUFBSSxRQUFRLENBQUMsT0FBTyxDQUFDLE1BQU0sS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUN0RSxNQUFNLElBQUksU0FBUyxDQUFDLDJEQUEyRCxDQUFDLENBQUM7SUFDbkYsQ0FBQztJQUNELEtBQUssTUFBTSxNQUFNLElBQUksUUFBUSxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQ3RDLElBQUksT0FBTyxNQUFNLEtBQUssUUFBUSxJQUFJLENBQUMseUJBQXlCLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxFQUFFLENBQUM7WUFDMUUsTUFBTSxJQUFJLFNBQVMsQ0FDakIs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
|
|
@@ -106,8 +106,34 @@ export type TAgentModelCallUsageSource = {
|
|
|
106
106
|
* whose context overflow caused it; it is absent for `compact()` and event retention.
|
|
107
107
|
*/
|
|
108
108
|
export type TAgentModelCallUsageEvent = TAgentObservedModelCallUsage & TAgentModelCallUsageSource;
|
|
109
|
+
/** What an attachment resolver is asked for: the attachment a prompt names by `url`. */
|
|
110
|
+
export interface IAgentAttachmentRequest {
|
|
111
|
+
url: URL;
|
|
112
|
+
abortSignal?: AbortSignal;
|
|
113
|
+
}
|
|
114
|
+
/** The content of an attachment, as the model call sends it to the provider. */
|
|
115
|
+
export interface IAgentResolvedAttachment {
|
|
116
|
+
data: Uint8Array;
|
|
117
|
+
mediaType: string;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Reads the attachments that prompts name by a URL of the host's own scheme, such as
|
|
121
|
+
* `exampleattachment:3f2a`, instead of carrying their content: the history keeps the URL, and
|
|
122
|
+
* each model call that sends the attachment reads its content here.
|
|
123
|
+
*/
|
|
124
|
+
export interface IAgentAttachmentResolver {
|
|
125
|
+
/** The URL schemes it reads, without the colon, in lowercase: `exampleattachment`. */
|
|
126
|
+
schemes: readonly string[];
|
|
127
|
+
/**
|
|
128
|
+
* Returns the attachment's content. A model call reads each attachment once, however many steps
|
|
129
|
+
* send it. Throw when it cannot be read: the model call fails with the error.
|
|
130
|
+
*/
|
|
131
|
+
resolve(request: IAgentAttachmentRequest): Promise<IAgentResolvedAttachment>;
|
|
132
|
+
}
|
|
109
133
|
export interface IAgentContextOverflowInvocationOptions {
|
|
110
134
|
abortSignal?: AbortSignal;
|
|
135
|
+
/** The session's attachment resolver. Send the handler's model calls with it. */
|
|
136
|
+
attachmentResolver?: IAgentAttachmentResolver;
|
|
111
137
|
/**
|
|
112
138
|
* Reports the usage of each model call the handler makes, into the session's `onUsage` as
|
|
113
139
|
* `source: 'compaction'`. The session always supplies it. Report every call before the returned
|
|
@@ -140,6 +166,11 @@ export interface IAgentContextCompactionOptions {
|
|
|
140
166
|
* none: its summary needs the room they take.
|
|
141
167
|
*/
|
|
142
168
|
tools?: ToolSet;
|
|
169
|
+
/**
|
|
170
|
+
* The session's attachment resolver. Send the compaction's model call with it, so the
|
|
171
|
+
* attachments the history names reach the provider.
|
|
172
|
+
*/
|
|
173
|
+
attachmentResolver?: IAgentAttachmentResolver;
|
|
143
174
|
/**
|
|
144
175
|
* Reports the usage of each model call the compactor makes, into the session's `onUsage` as
|
|
145
176
|
* `source: 'compaction'`. The session always supplies it. Report every call before the returned
|
|
@@ -179,6 +210,11 @@ export interface IAgentSessionOptions {
|
|
|
179
210
|
isReadOnlyToolCall?: TAgentToolCallClassifier;
|
|
180
211
|
/** Provider-specific AI SDK request options passed through to streamText() */
|
|
181
212
|
providerOptions?: ProviderOptions;
|
|
213
|
+
/**
|
|
214
|
+
* Reads the attachments that prompts name by a URL of one of its schemes. Without it, such a URL
|
|
215
|
+
* is downloaded like any other the model cannot read itself.
|
|
216
|
+
*/
|
|
217
|
+
attachmentResolver?: IAgentAttachmentResolver;
|
|
182
218
|
/** Stable session id used as provider prompt-cache affinity key where supported. */
|
|
183
219
|
sessionId?: string;
|
|
184
220
|
/** Optional event store. Each commit is saved to it as a change to the stored log. */
|
|
@@ -21,4 +21,4 @@ export class ContextOverflowError extends Error {
|
|
|
21
21
|
this.name = 'ContextOverflowError';
|
|
22
22
|
}
|
|
23
23
|
}
|
|
24
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
24
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQW1hQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUFzS0QsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=
|
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"author": "Task Venture Capital GmbH",
|
|
3
3
|
"license": "MIT",
|
|
4
4
|
"name": "@modelprofile.com/flexharness-agent",
|
|
5
|
-
"version": "12.
|
|
5
|
+
"version": "12.4.0",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"description": "Standalone event-driven agent runtime with generation transactions, context and tool execution contracts.",
|
|
8
8
|
"main": "./dist_ts_agent/index.js",
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
}
|
|
19
19
|
},
|
|
20
20
|
"dependencies": {
|
|
21
|
-
"@modelprofile.com/flexharness-models": "12.
|
|
21
|
+
"@modelprofile.com/flexharness-models": "12.4.0",
|
|
22
22
|
"ai": "^7.0.111",
|
|
23
23
|
"zod": "^4.6.5",
|
|
24
24
|
"@noble/hashes": "^2.4.0",
|
package/readme.md
CHANGED
|
@@ -335,6 +335,32 @@ Commits queued before a save starts share one durable change containing them all
|
|
|
335
335
|
|
|
336
336
|
A tool's `toModelOutput` result is stored with its tool-result event and replayed to the model on later steps and turns. Content outputs may carry AI SDK v7 `file` parts, such as a rendered image: `{ type: 'content', value: [{ type: 'text', text }, { type: 'file', mediaType: 'image/png', data: { type: 'data', data: base64 } }] }`. The `data` union persists as `{ type: 'data', data }` with canonical base64 of at most `AGENT_TOOL_RESULT_FILE_MAX_BYTES` (20 MiB) decoded, `{ type: 'url', url }` with an absolute URL string, `{ type: 'reference', reference }` with provider file IDs, or `{ type: 'text', text }`. `mediaType` is a full IANA media type or its top-level segment. Binary data (`Uint8Array`, `Buffer`) and data URLs are not persistable; return base64. The schema validators reject any other shape, so a store that validates refuses the save.
|
|
337
337
|
|
|
338
|
+
### Send files the application keeps
|
|
339
|
+
|
|
340
|
+
A user message may name a file by a URL of the application's own scheme instead of carrying its bytes, so the history stays small and a large upload never travels through the event store. `attachmentResolver` reads such URLs for each model call that sends them:
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
const session = await AgentSession.create({
|
|
344
|
+
...setup,
|
|
345
|
+
sessionId,
|
|
346
|
+
eventStore,
|
|
347
|
+
attachmentResolver: {
|
|
348
|
+
schemes: ['exampleattachment'],
|
|
349
|
+
async resolve({ url, abortSignal }) {
|
|
350
|
+
const upload = await uploads.read(url.pathname, abortSignal);
|
|
351
|
+
return { data: upload.bytes, mediaType: upload.mediaType };
|
|
352
|
+
},
|
|
353
|
+
},
|
|
354
|
+
});
|
|
355
|
+
await session.pushUserMessage([
|
|
356
|
+
{ type: 'text', text: 'Book this receipt.' },
|
|
357
|
+
{ type: 'file', data: 'exampleattachment:3f2a', mediaType: 'application/pdf' },
|
|
358
|
+
]);
|
|
359
|
+
await session.generate();
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
The steps of one generation read each URL once; a read that fails fails the step, and the next step asks again. Every other URL keeps the AI SDK's handling: sent as a URL to a model that reads it, downloaded otherwise. Schemes are lowercase, without the colon, and cannot be `data`, `file`, `http` or `https`; `AgentSession` refuses a malformed resolver with a `TypeError`. `contextCompactor` and `onContextOverflow` receive the resolver in their options, and `compactMessages()` reads the history's files through it when the options are passed through. `createAttachmentDownload(resolver, abortSignal)` returns the AI SDK `experimental_download` function the session uses, for a host that calls `streamText` itself.
|
|
363
|
+
|
|
338
364
|
`InMemoryAgentEventStore` is useful for tests and sessions that only need process-local storage. The Node root also exports the explicit `FileAgentEventStore` adapter. Neither storage selection nor a durable backend is implicit.
|
|
339
365
|
|
|
340
366
|
### Bound model context and active events
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import * as plugins from './plugins.js';
|
|
2
2
|
import type { IAgentRuntimePlatform, TAgentSessionOwnership } from './runtime.interfaces.js';
|
|
3
|
+
import { assertAttachmentResolver, createAttachmentDownload } from './smartagent.attachments.js';
|
|
3
4
|
import { buildModelMessages } from './smartagent.context.js';
|
|
4
5
|
import {
|
|
5
6
|
createAgentEvent,
|
|
@@ -426,6 +427,7 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
426
427
|
if (typeof options.contextCompactionBytes === 'number' && !options.contextCompactor) {
|
|
427
428
|
throw new Error('contextCompactionBytes requires a contextCompactor.');
|
|
428
429
|
}
|
|
430
|
+
if (options.attachmentResolver !== undefined) assertAttachmentResolver(options.attachmentResolver);
|
|
429
431
|
const changeListenerTimeoutMs = options.changeListenerTimeoutMs ?? 30_000;
|
|
430
432
|
if (!Number.isSafeInteger(changeListenerTimeoutMs) || changeListenerTimeoutMs <= 0) {
|
|
431
433
|
throw new Error('changeListenerTimeoutMs must be a positive integer.');
|
|
@@ -1351,6 +1353,9 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1351
1353
|
abortSignal,
|
|
1352
1354
|
reason,
|
|
1353
1355
|
reportUsage,
|
|
1356
|
+
...(this.options.attachmentResolver
|
|
1357
|
+
? { attachmentResolver: this.options.attachmentResolver }
|
|
1358
|
+
: {}),
|
|
1354
1359
|
...(servedCall?.system === undefined ? {} : { system: servedCall.system }),
|
|
1355
1360
|
...(servedCall?.providerOptions === undefined
|
|
1356
1361
|
? {}
|
|
@@ -1361,7 +1366,13 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1361
1366
|
)
|
|
1362
1367
|
: reason === 'context-overflow' && this.options.onContextOverflow
|
|
1363
1368
|
? await this.invokeGenerationCallback(
|
|
1364
|
-
() => this.options.onContextOverflow!(messages, {
|
|
1369
|
+
() => this.options.onContextOverflow!(messages, {
|
|
1370
|
+
abortSignal,
|
|
1371
|
+
reportUsage,
|
|
1372
|
+
...(this.options.attachmentResolver
|
|
1373
|
+
? { attachmentResolver: this.options.attachmentResolver }
|
|
1374
|
+
: {}),
|
|
1375
|
+
}),
|
|
1365
1376
|
)
|
|
1366
1377
|
: undefined;
|
|
1367
1378
|
if (!replacementMessages) {
|
|
@@ -2069,6 +2080,11 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2069
2080
|
options.abort,
|
|
2070
2081
|
options.stop,
|
|
2071
2082
|
]);
|
|
2083
|
+
// One per generation: its steps and retries read each attachment once.
|
|
2084
|
+
const attachmentDownload = createAttachmentDownload(
|
|
2085
|
+
this.options.attachmentResolver,
|
|
2086
|
+
combinedAbort.signal,
|
|
2087
|
+
);
|
|
2072
2088
|
|
|
2073
2089
|
let lease: IAgentGenerationLease | undefined;
|
|
2074
2090
|
let leaseCleanupOwnership: IGenerationLeaseCleanupOwnership | undefined;
|
|
@@ -2352,6 +2368,7 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2352
2368
|
stopWhen: [plugins.stepCountIs(remainingSteps), () => streamError !== undefined],
|
|
2353
2369
|
maxRetries: 0,
|
|
2354
2370
|
abortSignal: combinedAbort.signal,
|
|
2371
|
+
...(attachmentDownload ? { experimental_download: attachmentDownload } : {}),
|
|
2355
2372
|
prepareStep: async () => {
|
|
2356
2373
|
await applyPendingInput();
|
|
2357
2374
|
if (!automaticCompactionChecked && this.options.contextCompactor
|
package/ts_agent/index.ts
CHANGED
|
@@ -27,6 +27,7 @@ export { ToolRegistry } from './smartagent.classes.toolregistry.js';
|
|
|
27
27
|
export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
|
|
28
28
|
export type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
|
|
29
29
|
export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
|
|
30
|
+
export { assertAttachmentResolver, createAttachmentDownload } from './smartagent.attachments.js';
|
|
30
31
|
export { endModelStreamAtAbort, MODEL_ABORT_GRACE_MS } from './smartagent.modelabort.js';
|
|
31
32
|
export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
|
|
32
33
|
export {
|
|
@@ -43,7 +44,10 @@ export {
|
|
|
43
44
|
validateAgentEventSnapshot,
|
|
44
45
|
} from './smartagent.persistence.js';
|
|
45
46
|
export type {
|
|
47
|
+
IAgentAttachmentRequest,
|
|
48
|
+
IAgentAttachmentResolver,
|
|
46
49
|
IAgentCacheOptions,
|
|
50
|
+
IAgentResolvedAttachment,
|
|
47
51
|
ISmartAiCacheDispatch,
|
|
48
52
|
IAgentContextOverflowInvocationOptions,
|
|
49
53
|
IAgentContextBuildOptions,
|
package/ts_agent/plugins.ts
CHANGED
|
@@ -1,10 +1,18 @@
|
|
|
1
1
|
// ai-sdk core
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
asSchema,
|
|
4
|
+
createDownload,
|
|
5
|
+
streamText,
|
|
6
|
+
generateText,
|
|
7
|
+
stepCountIs,
|
|
8
|
+
wrapLanguageModel,
|
|
9
|
+
} from 'ai';
|
|
3
10
|
|
|
4
|
-
export { asSchema, streamText, generateText, stepCountIs, wrapLanguageModel };
|
|
11
|
+
export { asSchema, createDownload, streamText, generateText, stepCountIs, wrapLanguageModel };
|
|
5
12
|
|
|
6
13
|
export type {
|
|
7
14
|
AssistantModelMessage,
|
|
15
|
+
Experimental_DownloadFunction,
|
|
8
16
|
LanguageModelUsage,
|
|
9
17
|
ModelMessage,
|
|
10
18
|
StepResult,
|
package/ts_agent/readme.md
CHANGED
|
@@ -335,6 +335,32 @@ Commits queued before a save starts share one durable change containing them all
|
|
|
335
335
|
|
|
336
336
|
A tool's `toModelOutput` result is stored with its tool-result event and replayed to the model on later steps and turns. Content outputs may carry AI SDK v7 `file` parts, such as a rendered image: `{ type: 'content', value: [{ type: 'text', text }, { type: 'file', mediaType: 'image/png', data: { type: 'data', data: base64 } }] }`. The `data` union persists as `{ type: 'data', data }` with canonical base64 of at most `AGENT_TOOL_RESULT_FILE_MAX_BYTES` (20 MiB) decoded, `{ type: 'url', url }` with an absolute URL string, `{ type: 'reference', reference }` with provider file IDs, or `{ type: 'text', text }`. `mediaType` is a full IANA media type or its top-level segment. Binary data (`Uint8Array`, `Buffer`) and data URLs are not persistable; return base64. The schema validators reject any other shape, so a store that validates refuses the save.
|
|
337
337
|
|
|
338
|
+
### Send files the application keeps
|
|
339
|
+
|
|
340
|
+
A user message may name a file by a URL of the application's own scheme instead of carrying its bytes, so the history stays small and a large upload never travels through the event store. `attachmentResolver` reads such URLs for each model call that sends them:
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
const session = await AgentSession.create({
|
|
344
|
+
...setup,
|
|
345
|
+
sessionId,
|
|
346
|
+
eventStore,
|
|
347
|
+
attachmentResolver: {
|
|
348
|
+
schemes: ['exampleattachment'],
|
|
349
|
+
async resolve({ url, abortSignal }) {
|
|
350
|
+
const upload = await uploads.read(url.pathname, abortSignal);
|
|
351
|
+
return { data: upload.bytes, mediaType: upload.mediaType };
|
|
352
|
+
},
|
|
353
|
+
},
|
|
354
|
+
});
|
|
355
|
+
await session.pushUserMessage([
|
|
356
|
+
{ type: 'text', text: 'Book this receipt.' },
|
|
357
|
+
{ type: 'file', data: 'exampleattachment:3f2a', mediaType: 'application/pdf' },
|
|
358
|
+
]);
|
|
359
|
+
await session.generate();
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
The steps of one generation read each URL once; a read that fails fails the step, and the next step asks again. Every other URL keeps the AI SDK's handling: sent as a URL to a model that reads it, downloaded otherwise. Schemes are lowercase, without the colon, and cannot be `data`, `file`, `http` or `https`; `AgentSession` refuses a malformed resolver with a `TypeError`. `contextCompactor` and `onContextOverflow` receive the resolver in their options, and `compactMessages()` reads the history's files through it when the options are passed through. `createAttachmentDownload(resolver, abortSignal)` returns the AI SDK `experimental_download` function the session uses, for a host that calls `streamText` itself.
|
|
363
|
+
|
|
338
364
|
`InMemoryAgentEventStore` is useful for tests and sessions that only need process-local storage. The Node root also exports the explicit `FileAgentEventStore` adapter. Neither storage selection nor a durable backend is implicit.
|
|
339
365
|
|
|
340
366
|
### Bound model context and active events
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import * as plugins from './plugins.js';
|
|
2
|
+
import type {
|
|
3
|
+
IAgentAttachmentResolver,
|
|
4
|
+
IAgentResolvedAttachment,
|
|
5
|
+
} from './smartagent.interfaces.js';
|
|
6
|
+
|
|
7
|
+
const ATTACHMENT_SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*$/;
|
|
8
|
+
/** Schemes the AI SDK and the providers already give a meaning. */
|
|
9
|
+
const RESERVED_ATTACHMENT_SCHEMES = new Set(['data', 'file', 'http', 'https']);
|
|
10
|
+
|
|
11
|
+
/** Throws a `TypeError` unless `resolver` is a usable attachment resolver. */
|
|
12
|
+
export function assertAttachmentResolver(resolver: IAgentAttachmentResolver): void {
|
|
13
|
+
if (typeof resolver !== 'object' || resolver === null) {
|
|
14
|
+
throw new TypeError('attachmentResolver must be an object.');
|
|
15
|
+
}
|
|
16
|
+
if (typeof resolver.resolve !== 'function') {
|
|
17
|
+
throw new TypeError('attachmentResolver.resolve must be a function.');
|
|
18
|
+
}
|
|
19
|
+
if (!Array.isArray(resolver.schemes) || resolver.schemes.length === 0) {
|
|
20
|
+
throw new TypeError('attachmentResolver.schemes must name at least one scheme.');
|
|
21
|
+
}
|
|
22
|
+
for (const scheme of resolver.schemes) {
|
|
23
|
+
if (typeof scheme !== 'string' || !ATTACHMENT_SCHEME_PATTERN.test(scheme)) {
|
|
24
|
+
throw new TypeError(
|
|
25
|
+
`attachmentResolver scheme ${JSON.stringify(scheme)} must be a lowercase URL scheme without the colon.`,
|
|
26
|
+
);
|
|
27
|
+
}
|
|
28
|
+
if (RESERVED_ATTACHMENT_SCHEMES.has(scheme)) {
|
|
29
|
+
throw new TypeError(`attachmentResolver cannot claim the ${scheme} scheme.`);
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* The AI SDK download function of one model call. URLs of the resolver's schemes are read through
|
|
36
|
+
* the resolver, once per URL however many steps send them; every other URL keeps the AI SDK's
|
|
37
|
+
* default handling: passed through when the model reads it, downloaded otherwise.
|
|
38
|
+
* Returns `undefined` without a resolver, which leaves the AI SDK's default in place.
|
|
39
|
+
*/
|
|
40
|
+
export function createAttachmentDownload(
|
|
41
|
+
resolver: IAgentAttachmentResolver | undefined,
|
|
42
|
+
abortSignal?: AbortSignal,
|
|
43
|
+
): plugins.Experimental_DownloadFunction | undefined {
|
|
44
|
+
if (!resolver) return undefined;
|
|
45
|
+
const protocols = new Set(resolver.schemes.map((scheme) => `${scheme}:`));
|
|
46
|
+
const resolved = new Map<string, Promise<IAgentResolvedAttachment>>();
|
|
47
|
+
const download = plugins.createDownload();
|
|
48
|
+
const resolve = (url: URL): Promise<IAgentResolvedAttachment> => {
|
|
49
|
+
let attachment = resolved.get(url.href);
|
|
50
|
+
if (!attachment) {
|
|
51
|
+
attachment = resolver.resolve({ url, abortSignal }).then((result) =>
|
|
52
|
+
checkResolvedAttachment(url, result),
|
|
53
|
+
);
|
|
54
|
+
resolved.set(url.href, attachment);
|
|
55
|
+
// A failed read is not kept: the next step that sends the URL asks again.
|
|
56
|
+
attachment.catch(() => {
|
|
57
|
+
if (resolved.get(url.href) === attachment) resolved.delete(url.href);
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
return attachment;
|
|
61
|
+
};
|
|
62
|
+
return (requests) =>
|
|
63
|
+
Promise.all(
|
|
64
|
+
requests.map(async ({ url, isUrlSupportedByModel }) => {
|
|
65
|
+
if (protocols.has(url.protocol)) return await resolve(url);
|
|
66
|
+
return isUrlSupportedByModel ? null : await download({ url, abortSignal });
|
|
67
|
+
}),
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function checkResolvedAttachment(url: URL, result: IAgentResolvedAttachment): IAgentResolvedAttachment {
|
|
72
|
+
if (!(result?.data instanceof Uint8Array)) {
|
|
73
|
+
throw new TypeError(`The attachment resolver returned no bytes for ${url.href}.`);
|
|
74
|
+
}
|
|
75
|
+
if (typeof result.mediaType !== 'string' || result.mediaType.trim() === '') {
|
|
76
|
+
throw new TypeError(`The attachment resolver returned no media type for ${url.href}.`);
|
|
77
|
+
}
|
|
78
|
+
return { data: result.data, mediaType: result.mediaType };
|
|
79
|
+
}
|
|
@@ -132,8 +132,37 @@ export type TAgentModelCallUsageSource =
|
|
|
132
132
|
*/
|
|
133
133
|
export type TAgentModelCallUsageEvent = TAgentObservedModelCallUsage & TAgentModelCallUsageSource;
|
|
134
134
|
|
|
135
|
+
/** What an attachment resolver is asked for: the attachment a prompt names by `url`. */
|
|
136
|
+
export interface IAgentAttachmentRequest {
|
|
137
|
+
url: URL;
|
|
138
|
+
abortSignal?: AbortSignal;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** The content of an attachment, as the model call sends it to the provider. */
|
|
142
|
+
export interface IAgentResolvedAttachment {
|
|
143
|
+
data: Uint8Array;
|
|
144
|
+
mediaType: string;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Reads the attachments that prompts name by a URL of the host's own scheme, such as
|
|
149
|
+
* `exampleattachment:3f2a`, instead of carrying their content: the history keeps the URL, and
|
|
150
|
+
* each model call that sends the attachment reads its content here.
|
|
151
|
+
*/
|
|
152
|
+
export interface IAgentAttachmentResolver {
|
|
153
|
+
/** The URL schemes it reads, without the colon, in lowercase: `exampleattachment`. */
|
|
154
|
+
schemes: readonly string[];
|
|
155
|
+
/**
|
|
156
|
+
* Returns the attachment's content. A model call reads each attachment once, however many steps
|
|
157
|
+
* send it. Throw when it cannot be read: the model call fails with the error.
|
|
158
|
+
*/
|
|
159
|
+
resolve(request: IAgentAttachmentRequest): Promise<IAgentResolvedAttachment>;
|
|
160
|
+
}
|
|
161
|
+
|
|
135
162
|
export interface IAgentContextOverflowInvocationOptions {
|
|
136
163
|
abortSignal?: AbortSignal;
|
|
164
|
+
/** The session's attachment resolver. Send the handler's model calls with it. */
|
|
165
|
+
attachmentResolver?: IAgentAttachmentResolver;
|
|
137
166
|
/**
|
|
138
167
|
* Reports the usage of each model call the handler makes, into the session's `onUsage` as
|
|
139
168
|
* `source: 'compaction'`. The session always supplies it. Report every call before the returned
|
|
@@ -171,6 +200,11 @@ export interface IAgentContextCompactionOptions {
|
|
|
171
200
|
* none: its summary needs the room they take.
|
|
172
201
|
*/
|
|
173
202
|
tools?: ToolSet;
|
|
203
|
+
/**
|
|
204
|
+
* The session's attachment resolver. Send the compaction's model call with it, so the
|
|
205
|
+
* attachments the history names reach the provider.
|
|
206
|
+
*/
|
|
207
|
+
attachmentResolver?: IAgentAttachmentResolver;
|
|
174
208
|
/**
|
|
175
209
|
* Reports the usage of each model call the compactor makes, into the session's `onUsage` as
|
|
176
210
|
* `source: 'compaction'`. The session always supplies it. Report every call before the returned
|
|
@@ -219,6 +253,11 @@ export interface IAgentSessionOptions {
|
|
|
219
253
|
isReadOnlyToolCall?: TAgentToolCallClassifier;
|
|
220
254
|
/** Provider-specific AI SDK request options passed through to streamText() */
|
|
221
255
|
providerOptions?: ProviderOptions;
|
|
256
|
+
/**
|
|
257
|
+
* Reads the attachments that prompts name by a URL of one of its schemes. Without it, such a URL
|
|
258
|
+
* is downloaded like any other the model cannot read itself.
|
|
259
|
+
*/
|
|
260
|
+
attachmentResolver?: IAgentAttachmentResolver;
|
|
222
261
|
/** Stable session id used as provider prompt-cache affinity key where supported. */
|
|
223
262
|
sessionId?: string;
|
|
224
263
|
/** Optional event store. Each commit is saved to it as a change to the stored log. */
|