@tbox.cn/app-agent-sdk-server 0.1.0 → 0.1.2

package/dist/server/index.d.ts

@@ -153,11 +153,13 @@ type ContentPart = ImagePart | TextPart;
 declare function buildUserContent(text: string, mediaItems?: SendMessageMediaItem[], fileUrlPrefix?: string): string | ContentPart[];
 /**
  * 轮级注入块组（composeTurnUserContent 输入）。
- * 块语义见 platform-instructions 注入块协议节（四类块清单）。
+ * 块语义见 platform-instructions 注入块协议节（五类块清单）。
  */
 interface TurnReminderBlocks {
     /** card-decision 决策提醒块（modelEnabled 轮恒注入） */
     cardDecision?: string;
+    /** runtime-context 服务端可信运行时间块（配置后 modelEnabled 轮恒注入） */
+    runtimeContext?: string;
     /** pre-tool 预执行数据块（每 done 工具一个，按完成序） */
     preToolBlocks?: string[];
     /** memory 背景数据块（recall 命中轮） */
@@ -167,7 +169,7 @@ interface TurnReminderBlocks {
 }
 /**
  * 轮级 user 内容统一组装（W3，2026-09-01；顺序契约唯一真源）：
- * `[card-decision → preTool₁..n → memory → skill → userText]`。
+ * `[card-decision → runtime-context → preTool₁..n → memory → skill → userText]`。
  * 分组逻辑：协议指令 → 本轮数据族（前景 preTool + 背景 memory 相邻）→ 域规程（紧邻正文，
  * 注意力就近）→ 正文。chat() 与 submitForm 单点共用；与 buildInjectedUserContent 字节级同构
  * （仅传 skillBlock 时产物恒等——测试钉死）。
@@ -554,7 +556,7 @@ declare function withRecallCache(store: MemoryStore, opts?: RecallCacheOptions):
  * trace-transform → recall → logger → trace-exporter → trace-transform）。
  *
  * 块协议：`<system-reminder …>…</system-reminder>`（skill / preTool / memory /
- * card-decision 四类注入块统一围栏，属性不限——见 platform-instructions）。
+ * card-decision / runtime-context 五类注入块统一围栏，属性不限——见 platform-instructions）。
  */
 /**
  * 剥离完整 `<system-reminder …>` 块（任意属性——skill/preTool/memory 等注入块）：
@@ -1124,6 +1126,29 @@ interface EngineStepController {
 }
 type EngineStepControlFactory = (input: EngineStepControlInput) => EngineStepController | Promise<EngineStepController>;
 
+interface RuntimeContextOptions {
+    readonly timeZone: string;
+    readonly now?: () => number;
+}
+interface ResolvedRuntimeContextOptions {
+    readonly timeZone: string;
+    readonly now: () => number;
+}
+interface RuntimeTemporalContext {
+    readonly v: 1;
+    readonly asOf: string;
+    readonly timeZone: string;
+}
+interface RuntimeTemporalContextSnapshot {
+    readonly startedAt: number;
+    readonly context: RuntimeTemporalContext;
+    readonly reminder: string;
+}
+/** Validate once at engine construction and retain the canonical IANA identifier. */
+declare function resolveRuntimeContextOptions(options: RuntimeContextOptions): ResolvedRuntimeContextOptions;
+/** Build one temporal snapshot for a model run. The clock is sampled exactly once. */
+declare function createRuntimeTemporalContext(options: ResolvedRuntimeContextOptions): RuntimeTemporalContextSnapshot;
+
 interface ChatEngineOptions {
     instructions: string;
     model: any;
@@ -1132,6 +1157,8 @@ interface ChatEngineOptions {
     cardRegistry: Record<string, CardMeta>;
     /** Optional run-local, domain-neutral model/tool control. Not used by deterministic or form paths. */
     stepControl?: EngineStepControlFactory;
+    /** 服务端可信运行时间上下文；仅模型路径按 run 注入，不进入前端事件或 saveMessage。 */
+    runtimeContext?: RuntimeContextOptions;
     /** trace exporter（默认使用 SDK 内置单例） */
     traceExporter?: TboxTraceExporter;
     /** 文件 URL 前缀（content-builder 用） */
@@ -1739,6 +1766,8 @@ interface BuildEngineOptions extends SdkRuntimeOptions {
      */
     memoryInstructions?: string;
     model: unknown;
+    /** 服务端可信运行时间上下文（构造期校验时区；每个 model run 独立采样） */
+    runtimeContext?: ChatEngineOptions['runtimeContext'];
     stepControl?: ChatEngineOptions['stepControl'];
     /** 模型名（日志用） */
     modelName?: string;
@@ -2279,4 +2308,4 @@ interface SampleShapeReport {
  */
 declare function findSampleShapeViolations(meta: CardMeta): SampleShapeReport;
 
-export { type AnyTool, BROAD_ROUTING_TERMS, BUILTIN_HYGIENE_NAMES, type BootstrapMemoryKbOptions, type BootstrapMemoryKbResult, type BuildEngineOptions, CARDS_SPEC, CARD_DECISION_HOLD_LIMIT, CARD_DECISION_TAG, CARD_EMISSION_HINT_ACTIONS, CARD_EMISSION_HINT_BASE, CARD_EMISSION_HINT_KEYWORD, type CardDecisionPlan, type CardDecisionStripper, type CardPersistenceBackend, type CardPool, type CardPoolOptions, type ChatEngine, type ChatEngineOptions, type ContentPart, type ContentTagHygiene, type ConversationRouterDeps, ConversationService, DECISION_HOLD_LIMIT, DEFAULT_INSTRUCTIONS, DEFAULT_KNOWLEDGE_MEMORY_CAPABILITIES, DEFAULT_LIST_TTL_MS, DEFAULT_LLM_PROVIDER_CONFIG_PATH, DEFAULT_MAX_CARDS_PER_TURN, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_PRE_TOOLS_PER_RUN, DEFAULT_MEMORY_MAX_CHARS_PER_RECORD, DEFAULT_MEMORY_RECALL_TIMEOUT_MS, DEFAULT_MEMORY_TOP_K, DEFAULT_MEMORY_VALIDATE_TIMEOUT_MS, DEFAULT_PRE_TOOL_TIMEOUT_MS, DEFAULT_SKILL_MODE, DROP_BODY_SOFT_LIMIT, EARLY_EXECUTION_MARKER, type EngineModelStepInput, type EngineRunEndInput, type EngineRunInput, type EngineStepControlFactory, type EngineStepControlInput, type EngineStepController, type EngineStepResultInput, type EngineStepToolChoice, type EngineToolCallInput, type EngineToolResultInput, FORM_SUBMIT_TOOL_ID, FileCardPersistenceBackend, HYGIENE_TAG_NORMALIZE, type HygieneTagFamily, INTERNAL_TOOL, type InstallTboxDevDeps, type IntentRoute, KB_SCOPE_GLOBAL, KNOWLEDGE_DEFAULT_BASE_URL, KnowledgeBootstrapError, type KnowledgeMemoryStoreOptions, KnowledgeOpenapiError, type KnowledgeOpenapiTransportOptions, type KnowledgeTransport, type LoadedAgentPromptConfig, type LoadedChatConfig, type LoadedPluginTools, MEMORY_IMPORTANCE_BASE, MEMORY_KB_INDEX_COLUMNS, MEMORY_KB_SCHEMA, MEMORY_KB_SEED_CSV, MEMORY_LIST_DEFAULT_LIMIT, MEMORY_LIST_MAX_LIMIT, MEMORY_MAX_PER_USER, type MemoryEngineOptions, type MemoryFilterColumn, type MemoryGuardDeps, type MemoryGuardEnv, type MemoryPromptCaps, type MemoryRouterDeps, type MemoryStoreEnv, MemoryStoreUnsupportedError, type MemoryToolDeps, MemoryUnavailableError, type MemoryValidateMode, type MemoryValidationOutcome, MessageEmbeddedBackend, type ModelProviderOptions, PRE_TOOL_HISTORY_LIMIT, type ParallelToolCallsControl, type PlatformApiRouterDeps, type PluginIntegrationOptions, type PoolEntry, type PreFilterTerm, type PreToolExecContext, PreToolTimeoutError, PreviewActionError, type QuickCommand, type RecallCacheOptions, type RecallCacheState, type ResolvedTagSpecs, type SampleShapeBlindSpot, type SampleShapeReport, type SampleShapeViolation, type SdkRuntimeOptions, type SdkToolRuntime, type SegmentHit, type SkillInjectionDecision, type SkillMode, type SortTerm, type StoredMemoryRecord, type StreamTagEngine, DEFAULT_FILE_URL_PREFIX as TBOX_FILE_URL_PREFIX, THINK_SPECS, TOOL_CALL_TEXT_SPECS, TOOL_CARDS_FIELD, TOOL_CARD_DESCRIPTOR_SCHEMA, type TagBodyPolicy, type TagEngineFinish, type TagHit, type TagSeal, type TagSource, type TagSpec, type TagTrack, TboxTraceExporter, type ThinkingControl, type ToolCardDescriptor, type ToolCardSpec, type ToolExecContextLike, type ToolRunMetadata, type TurnReminderBlocks, applySkillReminder, bootstrapMemoryKnowledgeBase, buildCardDecisionReminder, buildInjectedUserContent, buildMemoryRecallToolCallEvents, buildMemoryReminder, buildMessageInputs, buildPlatformInstructions, buildPreToolCallEndEvents, buildPreToolCallStartEvents, buildPreToolDirectives, buildRecapUserContent, buildSkillRecapReminder, buildSkillReminder, buildSkillToolCallEvents, buildUserContent, captureToolCards, clampMaxCards, clampMemoryMaxChars, clampMemoryTopK, coerceStringifiedFields, composeTurnUserContent, createCardDecisionStripper, createCardPool, createCardTool, createChatEngine, createConversationRouter, createEngineFromContext, createGatedMemoryStore, createInMemoryMemoryStore, createIntentDispatcher, createKnowledgeMemoryStore, createKnowledgeOpenapiTransport, createMemoryRouter, createMemoryTools, createModelProvider, createPlatformApiRouter, createPluginIntegration, createSdkToolRuntime, createStreamTagEngine, createToolExecContext, createTtsProxy, createWsServer, decideCards, decideSkillInjection, definePreTool, envelopeTag, executePreTool, extractImageUrls, findSampleShapeViolations, formSubmitTool, generateMemoryId, getLastRecallCacheState, getToolRequestContext, getToolRunMetadata, getTtsClient, hardenToolsForLlm, hashContent, healthRouter, hygieneXmlTag, installTboxDev, internalTool, loadAgentPromptConfig, loadChatConfig, loadLocalSkills, loadModuleSkills, matchIntent, memoryStoreCapabilities, mergePreTools, mergeSkills, normalizePreTools, omitInternal, pickFallbackCard, projectHistory, recallMemories, requireToolRequestContext, resetTtsClient, resolveEarlyToolExecution, resolveMaxSteps, resolveMemoryEngineOptions, resolveMemoryRecallTimeout, resolveMemoryStore, resolveMemoryStoreGuarded, resolveMemoryValidateMode, resolveMemoryValidateTimeout, resolvePreToolTimeout, resolveSkillMode, resolveTagSpecs, resolveToolDebug, restoreCardSnapshot, sanitizeLlmToolInput, scanInjectedSkills, scopeToKey, selectPreTools, selectSkill, stableStringify, stripSystemReminderBlocks, router as tboxSessionRouter, tboxTraceExporter, toCardSnapshot, toMastraSkill, toWsChatConfig, tokenizeTagBody, toolCardScope, validateMemoryKnowledgeBase, withCardEmissionHint, withDeadline, withEarlyExecution, withLlmInputSanitize, withRecallCache, wrapToolsForCardCapture, xmlTag, xmlTagDecision };
+export { type AnyTool, BROAD_ROUTING_TERMS, BUILTIN_HYGIENE_NAMES, type BootstrapMemoryKbOptions, type BootstrapMemoryKbResult, type BuildEngineOptions, CARDS_SPEC, CARD_DECISION_HOLD_LIMIT, CARD_DECISION_TAG, CARD_EMISSION_HINT_ACTIONS, CARD_EMISSION_HINT_BASE, CARD_EMISSION_HINT_KEYWORD, type CardDecisionPlan, type CardDecisionStripper, type CardPersistenceBackend, type CardPool, type CardPoolOptions, type ChatEngine, type ChatEngineOptions, type ContentPart, type ContentTagHygiene, type ConversationRouterDeps, ConversationService, DECISION_HOLD_LIMIT, DEFAULT_INSTRUCTIONS, DEFAULT_KNOWLEDGE_MEMORY_CAPABILITIES, DEFAULT_LIST_TTL_MS, DEFAULT_LLM_PROVIDER_CONFIG_PATH, DEFAULT_MAX_CARDS_PER_TURN, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_PRE_TOOLS_PER_RUN, DEFAULT_MEMORY_MAX_CHARS_PER_RECORD, DEFAULT_MEMORY_RECALL_TIMEOUT_MS, DEFAULT_MEMORY_TOP_K, DEFAULT_MEMORY_VALIDATE_TIMEOUT_MS, DEFAULT_PRE_TOOL_TIMEOUT_MS, DEFAULT_SKILL_MODE, DROP_BODY_SOFT_LIMIT, EARLY_EXECUTION_MARKER, type EngineModelStepInput, type EngineRunEndInput, type EngineRunInput, type EngineStepControlFactory, type EngineStepControlInput, type EngineStepController, type EngineStepResultInput, type EngineStepToolChoice, type EngineToolCallInput, type EngineToolResultInput, FORM_SUBMIT_TOOL_ID, FileCardPersistenceBackend, HYGIENE_TAG_NORMALIZE, type HygieneTagFamily, INTERNAL_TOOL, type InstallTboxDevDeps, type IntentRoute, KB_SCOPE_GLOBAL, KNOWLEDGE_DEFAULT_BASE_URL, KnowledgeBootstrapError, type KnowledgeMemoryStoreOptions, KnowledgeOpenapiError, type KnowledgeOpenapiTransportOptions, type KnowledgeTransport, type LoadedAgentPromptConfig, type LoadedChatConfig, type LoadedPluginTools, MEMORY_IMPORTANCE_BASE, MEMORY_KB_INDEX_COLUMNS, MEMORY_KB_SCHEMA, MEMORY_KB_SEED_CSV, MEMORY_LIST_DEFAULT_LIMIT, MEMORY_LIST_MAX_LIMIT, MEMORY_MAX_PER_USER, type MemoryEngineOptions, type MemoryFilterColumn, type MemoryGuardDeps, type MemoryGuardEnv, type MemoryPromptCaps, type MemoryRouterDeps, type MemoryStoreEnv, MemoryStoreUnsupportedError, type MemoryToolDeps, MemoryUnavailableError, type MemoryValidateMode, type MemoryValidationOutcome, MessageEmbeddedBackend, type ModelProviderOptions, PRE_TOOL_HISTORY_LIMIT, type ParallelToolCallsControl, type PlatformApiRouterDeps, type PluginIntegrationOptions, type PoolEntry, type PreFilterTerm, type PreToolExecContext, PreToolTimeoutError, PreviewActionError, type QuickCommand, type RecallCacheOptions, type RecallCacheState, type ResolvedRuntimeContextOptions, type ResolvedTagSpecs, type RuntimeContextOptions, type RuntimeTemporalContext, type RuntimeTemporalContextSnapshot, type SampleShapeBlindSpot, type SampleShapeReport, type SampleShapeViolation, type SdkRuntimeOptions, type SdkToolRuntime, type SegmentHit, type SkillInjectionDecision, type SkillMode, type SortTerm, type StoredMemoryRecord, type StreamTagEngine, DEFAULT_FILE_URL_PREFIX as TBOX_FILE_URL_PREFIX, THINK_SPECS, TOOL_CALL_TEXT_SPECS, TOOL_CARDS_FIELD, TOOL_CARD_DESCRIPTOR_SCHEMA, type TagBodyPolicy, type TagEngineFinish, type TagHit, type TagSeal, type TagSource, type TagSpec, type TagTrack, TboxTraceExporter, type ThinkingControl, type ToolCardDescriptor, type ToolCardSpec, type ToolExecContextLike, type ToolRunMetadata, type TurnReminderBlocks, applySkillReminder, bootstrapMemoryKnowledgeBase, buildCardDecisionReminder, buildInjectedUserContent, buildMemoryRecallToolCallEvents, buildMemoryReminder, buildMessageInputs, buildPlatformInstructions, buildPreToolCallEndEvents, buildPreToolCallStartEvents, buildPreToolDirectives, buildRecapUserContent, buildSkillRecapReminder, buildSkillReminder, buildSkillToolCallEvents, buildUserContent, captureToolCards, clampMaxCards, clampMemoryMaxChars, clampMemoryTopK, coerceStringifiedFields, composeTurnUserContent, createCardDecisionStripper, createCardPool, createCardTool, createChatEngine, createConversationRouter, createEngineFromContext, createGatedMemoryStore, createInMemoryMemoryStore, createIntentDispatcher, createKnowledgeMemoryStore, createKnowledgeOpenapiTransport, createMemoryRouter, createMemoryTools, createModelProvider, createPlatformApiRouter, createPluginIntegration, createRuntimeTemporalContext, createSdkToolRuntime, createStreamTagEngine, createToolExecContext, createTtsProxy, createWsServer, decideCards, decideSkillInjection, definePreTool, envelopeTag, executePreTool, extractImageUrls, findSampleShapeViolations, formSubmitTool, generateMemoryId, getLastRecallCacheState, getToolRequestContext, getToolRunMetadata, getTtsClient, hardenToolsForLlm, hashContent, healthRouter, hygieneXmlTag, installTboxDev, internalTool, loadAgentPromptConfig, loadChatConfig, loadLocalSkills, loadModuleSkills, matchIntent, memoryStoreCapabilities, mergePreTools, mergeSkills, normalizePreTools, omitInternal, pickFallbackCard, projectHistory, recallMemories, requireToolRequestContext, resetTtsClient, resolveEarlyToolExecution, resolveMaxSteps, resolveMemoryEngineOptions, resolveMemoryRecallTimeout, resolveMemoryStore, resolveMemoryStoreGuarded, resolveMemoryValidateMode, resolveMemoryValidateTimeout, resolvePreToolTimeout, resolveRuntimeContextOptions, resolveSkillMode, resolveTagSpecs, resolveToolDebug, restoreCardSnapshot, sanitizeLlmToolInput, scanInjectedSkills, scopeToKey, selectPreTools, selectSkill, stableStringify, stripSystemReminderBlocks, router as tboxSessionRouter, tboxTraceExporter, toCardSnapshot, toMastraSkill, toWsChatConfig, tokenizeTagBody, toolCardScope, validateMemoryKnowledgeBase, withCardEmissionHint, withDeadline, withEarlyExecution, withLlmInputSanitize, withRecallCache, wrapToolsForCardCapture, xmlTag, xmlTagDecision };