@dudousxd/nestjs-agent-core 0.26.0 → 0.27.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/index.cjs +679 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +208 -2
- package/dist/index.d.ts +208 -2
- package/dist/index.js +678 -3
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -2773,7 +2773,14 @@ declare class ToolRegistry {
|
|
|
2773
2773
|
*/
|
|
2774
2774
|
invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
|
|
2775
2775
|
}
|
|
2776
|
-
/**
|
|
2776
|
+
/**
|
|
2777
|
+
* Default gate: a tool that names `roles` is callable by an actor holding one of them; a tool that
|
|
2778
|
+
* names none falls back to `defaultRoles`, and an empty list — the default — restricts nobody. So
|
|
2779
|
+
* out of the box every tool is callable by whoever the `ActorResolver` resolved (an anonymous
|
|
2780
|
+
* visitor included, when no resolver is configured); restrict with `@AiTool({ roles })` per tool,
|
|
2781
|
+
* `AgentModule.forRoot({ defaultRoles })` module-wide, or a `rolesPolicy` of your own. `action`
|
|
2782
|
+
* tools still park on approval either way.
|
|
2783
|
+
*/
|
|
2777
2784
|
declare class DefaultRolesPolicy implements RolesPolicy {
|
|
2778
2785
|
private readonly defaultRoles;
|
|
2779
2786
|
constructor(defaultRoles?: string[]);
|
|
@@ -3479,4 +3486,203 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
|
|
|
3479
3486
|
*/
|
|
3480
3487
|
declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
|
|
3481
3488
|
|
|
3482
|
-
|
|
3489
|
+
/** A recorded usage row exposed to the governance read-model (input/output split + thread/day). */
|
|
3490
|
+
interface GovernanceUsageRow {
|
|
3491
|
+
actorRef: string;
|
|
3492
|
+
threadId: string;
|
|
3493
|
+
modelId: string;
|
|
3494
|
+
inputTokens: number;
|
|
3495
|
+
outputTokens: number;
|
|
3496
|
+
/** Subset of `inputTokens` written to the prompt cache this turn; undefined when not reported. */
|
|
3497
|
+
cacheWriteTokens?: number;
|
|
3498
|
+
/** Subset of `inputTokens` served from the prompt cache this turn; undefined when not reported. */
|
|
3499
|
+
cacheReadTokens?: number;
|
|
3500
|
+
/** Provider-reported actual cost for the turn, when known; undefined → estimate from pricing. */
|
|
3501
|
+
costUsd?: number;
|
|
3502
|
+
day: string;
|
|
3503
|
+
createdAt: string;
|
|
3504
|
+
}
|
|
3505
|
+
/** A recorded tool call exposed to the governance read-model (thread resolved, with timestamp). */
|
|
3506
|
+
interface GovernanceToolCallRow {
|
|
3507
|
+
toolCallId: string;
|
|
3508
|
+
toolName: string;
|
|
3509
|
+
toolType: 'read' | 'action';
|
|
3510
|
+
status: ToolCallStatus;
|
|
3511
|
+
threadId: string;
|
|
3512
|
+
/** The message that requested the call — the thread drill-down groups by it. */
|
|
3513
|
+
messageId: string;
|
|
3514
|
+
/** Wall-clock milliseconds the tool took to run; undefined when it never recorded one. */
|
|
3515
|
+
executionMs?: number;
|
|
3516
|
+
/** The failure text for a `failed` call; undefined otherwise. */
|
|
3517
|
+
error?: string;
|
|
3518
|
+
createdAt: string;
|
|
3519
|
+
/** The run this call belongs to; undefined when the caller didn't supply one. */
|
|
3520
|
+
runId?: string;
|
|
3521
|
+
}
|
|
3522
|
+
/** A stored message exposed to the governance read-model (the thread drill-down's transcript). */
|
|
3523
|
+
interface GovernanceMessageRow {
|
|
3524
|
+
messageId: string;
|
|
3525
|
+
threadId: string;
|
|
3526
|
+
role: string;
|
|
3527
|
+
content: string;
|
|
3528
|
+
agentName?: string;
|
|
3529
|
+
createdAt: string;
|
|
3530
|
+
}
|
|
3531
|
+
/** A tool call awaiting a HITL decision, joined to its thread + message for the approvals inbox. */
|
|
3532
|
+
interface GovernancePendingApprovalRow {
|
|
3533
|
+
toolCallId: string;
|
|
3534
|
+
toolName: string;
|
|
3535
|
+
input: unknown;
|
|
3536
|
+
threadId: string;
|
|
3537
|
+
threadTitle: string;
|
|
3538
|
+
actorRef: string;
|
|
3539
|
+
agentName?: string;
|
|
3540
|
+
requestedAt: string;
|
|
3541
|
+
/** The run this call belongs to; undefined when the caller didn't supply one. */
|
|
3542
|
+
runId?: string;
|
|
3543
|
+
}
|
|
3544
|
+
/** Thread metadata exposed to the governance read-model (title/actor/count/last activity). */
|
|
3545
|
+
interface GovernanceThreadRow {
|
|
3546
|
+
threadId: string;
|
|
3547
|
+
title: string;
|
|
3548
|
+
actorRef: string;
|
|
3549
|
+
messageCount: number;
|
|
3550
|
+
updatedAt: string;
|
|
3551
|
+
}
|
|
3552
|
+
/** A recorded run outcome exposed to the governance read-model (reliability surfaces). */
|
|
3553
|
+
interface GovernanceRunRow {
|
|
3554
|
+
runId: string;
|
|
3555
|
+
threadId: string;
|
|
3556
|
+
actorRef: string;
|
|
3557
|
+
agentName?: string;
|
|
3558
|
+
status: 'running' | 'completed' | 'failed' | 'cancelled';
|
|
3559
|
+
durationMs?: number;
|
|
3560
|
+
errorCode?: string;
|
|
3561
|
+
errorMessage?: string;
|
|
3562
|
+
retries: number;
|
|
3563
|
+
startedAt: string;
|
|
3564
|
+
settledAt?: string;
|
|
3565
|
+
promptHash?: string;
|
|
3566
|
+
/**
|
|
3567
|
+
* The run that delegated this one; undefined for a turn nobody delegated. The edge exists in the
|
|
3568
|
+
* durable journal too, but a reader of run rows has only this — and a DETACHED child outlives its
|
|
3569
|
+
* parent's turn, so nothing in the transcript pairs them either.
|
|
3570
|
+
*/
|
|
3571
|
+
parentRunId?: string;
|
|
3572
|
+
}
|
|
3573
|
+
/** A fully in-memory `AgentStore` for tests and the offline demo. */
|
|
3574
|
+
declare class InMemoryAgentStore implements AgentStore {
|
|
3575
|
+
private readonly threads;
|
|
3576
|
+
private readonly toolCalls;
|
|
3577
|
+
private readonly usage;
|
|
3578
|
+
private readonly runs;
|
|
3579
|
+
private now;
|
|
3580
|
+
createThread(input: CreateThreadInput): Promise<ThreadSummary>;
|
|
3581
|
+
getThread(threadId: string): Promise<ThreadDetail | null>;
|
|
3582
|
+
/** A message with the approval record of every call on it that was put to a person. */
|
|
3583
|
+
private withApprovals;
|
|
3584
|
+
rememberedApprovals(threadId: string): Promise<string[]>;
|
|
3585
|
+
toolCallInput(toolCallId: string): Promise<unknown>;
|
|
3586
|
+
toolCallApproval(toolCallId: string): Promise<ToolCallApprovalState | null>;
|
|
3587
|
+
listThreads(actorRef: string, limit?: number): Promise<ThreadSummary[]>;
|
|
3588
|
+
softDeleteThread(threadId: string): Promise<void>;
|
|
3589
|
+
forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
|
|
3590
|
+
ownerOfThread(threadId: string): Promise<string | null>;
|
|
3591
|
+
ownerOfToolCall(toolCallId: string): Promise<string | null>;
|
|
3592
|
+
runForToolCall(toolCallId: string): Promise<string | null>;
|
|
3593
|
+
ownerOfActiveStream(runId: string): Promise<string | null>;
|
|
3594
|
+
setTitle(threadId: string, title: string): Promise<void>;
|
|
3595
|
+
updateThread(threadId: string, patch: UpdateThreadInput): Promise<void>;
|
|
3596
|
+
activeRunForThread(threadId: string): Promise<string | null>;
|
|
3597
|
+
/**
|
|
3598
|
+
* The thread's default agent, projected. A map lookup here, but the SQL adapters answer this with
|
|
3599
|
+
* a one-column read instead of materializing the whole transcript — so the caller that only needs
|
|
3600
|
+
* this scalar has a method to ask for it.
|
|
3601
|
+
*/
|
|
3602
|
+
defaultAgentForThread(threadId: string): Promise<string | null>;
|
|
3603
|
+
/** The thread's pinned model, projected like {@link defaultAgentForThread}. */
|
|
3604
|
+
modelForThread(threadId: string): Promise<string | null>;
|
|
3605
|
+
/**
|
|
3606
|
+
* Persist the start of a run (turn). Replay-safe: called under a durable localStep.
|
|
3607
|
+
*
|
|
3608
|
+
* Takes the SPI's own {@link RecordRunStartInput} rather than a hand-copied shape: a field added
|
|
3609
|
+
* to the input is otherwise accepted and dropped, silently, by every adapter that re-declares it.
|
|
3610
|
+
*/
|
|
3611
|
+
recordRunStart(run: RecordRunStartInput): Promise<void>;
|
|
3612
|
+
/** Settle a run's outcome. A no-op when the run is unknown (mirrors `setTitle`/`updateThread`). */
|
|
3613
|
+
recordRunEnd(end: {
|
|
3614
|
+
runId: string;
|
|
3615
|
+
status: 'completed' | 'failed' | 'cancelled';
|
|
3616
|
+
durationMs?: number;
|
|
3617
|
+
errorCode?: string;
|
|
3618
|
+
errorMessage?: string;
|
|
3619
|
+
}): Promise<void>;
|
|
3620
|
+
/** Bump the run's llm-step retry counter. */
|
|
3621
|
+
bumpRunRetries(runId: string): Promise<void>;
|
|
3622
|
+
promoteThread(threadId: string): Promise<void>;
|
|
3623
|
+
setActiveStream(threadId: string, runId: string | null): Promise<void>;
|
|
3624
|
+
appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
|
|
3625
|
+
setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
|
|
3626
|
+
setMessageUi(messageId: string, ui: AgentUiComponent[]): Promise<void>;
|
|
3627
|
+
threadOfMessage(messageId: string): Promise<string | null>;
|
|
3628
|
+
setMessageFeedback(messageId: string, feedback: MessageFeedback | null): Promise<void>;
|
|
3629
|
+
truncateFrom(threadId: string, messageId: string): Promise<void>;
|
|
3630
|
+
/**
|
|
3631
|
+
* Of `mediaIds`, the ones a surviving message in one of this actor's threads still carries.
|
|
3632
|
+
* Re-derived from the messages each call, so a media whose message was truncated away reads as
|
|
3633
|
+
* unreferenced again.
|
|
3634
|
+
*/
|
|
3635
|
+
referencedMediaIds(actorRef: string, mediaIds: readonly string[]): Promise<string[]>;
|
|
3636
|
+
recordToolCall(input: RecordToolCallInput): Promise<void>;
|
|
3637
|
+
updateToolCall(input: UpdateToolCallInput): Promise<void>;
|
|
3638
|
+
recordUsage(input: RecordUsageInput): Promise<void>;
|
|
3639
|
+
quotaToday(actorRef: string, day: string): Promise<{
|
|
3640
|
+
usedTokens: number;
|
|
3641
|
+
costUsd: number;
|
|
3642
|
+
}>;
|
|
3643
|
+
usageBetween(actorRef: string, fromDay: string, toDay: string): Promise<{
|
|
3644
|
+
usedTokens: number;
|
|
3645
|
+
costUsd: number;
|
|
3646
|
+
}>;
|
|
3647
|
+
/** Test helper: read the recorded usage rows (modelId + token totals). */
|
|
3648
|
+
usageRows(): {
|
|
3649
|
+
actorRef: string;
|
|
3650
|
+
tokens: number;
|
|
3651
|
+
modelId: string;
|
|
3652
|
+
}[];
|
|
3653
|
+
/** Governance read-model feed: recorded usage rows with the input/output split + thread/day. */
|
|
3654
|
+
governanceUsage(): GovernanceUsageRow[];
|
|
3655
|
+
/** Governance read-model feed: recorded tool calls with the resolved thread + timestamp. */
|
|
3656
|
+
governanceToolCalls(): GovernanceToolCallRow[];
|
|
3657
|
+
/** Governance read-model feed: every stored message, thread-resolved, for the thread drill-down. */
|
|
3658
|
+
governanceMessages(): GovernanceMessageRow[];
|
|
3659
|
+
/**
|
|
3660
|
+
* Governance read-model feed: tool calls sitting `pending_approval`, joined to their thread
|
|
3661
|
+
* (title/actorRef) and the message that requested them (`agentName`, when the message has one).
|
|
3662
|
+
*/
|
|
3663
|
+
governancePendingApprovals(): GovernancePendingApprovalRow[];
|
|
3664
|
+
/** Governance read-model feed: thread metadata (title/actor/message count/last activity). */
|
|
3665
|
+
governanceThreads(): GovernanceThreadRow[];
|
|
3666
|
+
/** Governance read-model feed: recorded run outcomes (the reliability surfaces). */
|
|
3667
|
+
governanceRuns(): GovernanceRunRow[];
|
|
3668
|
+
private threadIdForMessage;
|
|
3669
|
+
/** Test helper: read the recorded tool-call rows. */
|
|
3670
|
+
toolCallRows(): {
|
|
3671
|
+
toolCallId: string;
|
|
3672
|
+
toolName: string;
|
|
3673
|
+
toolType: 'read' | 'action';
|
|
3674
|
+
status: ToolCallStatus;
|
|
3675
|
+
input?: unknown;
|
|
3676
|
+
output?: unknown;
|
|
3677
|
+
error?: string;
|
|
3678
|
+
runId?: string;
|
|
3679
|
+
executedByRef?: string;
|
|
3680
|
+
approver?: string;
|
|
3681
|
+
expiresAt?: string;
|
|
3682
|
+
remember?: boolean;
|
|
3683
|
+
decidedVia?: string;
|
|
3684
|
+
}[];
|
|
3685
|
+
private toSummary;
|
|
3686
|
+
}
|
|
3687
|
+
|
|
3688
|
+
export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
|
package/dist/index.d.ts
CHANGED
|
@@ -2773,7 +2773,14 @@ declare class ToolRegistry {
|
|
|
2773
2773
|
*/
|
|
2774
2774
|
invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
|
|
2775
2775
|
}
|
|
2776
|
-
/**
|
|
2776
|
+
/**
|
|
2777
|
+
* Default gate: a tool that names `roles` is callable by an actor holding one of them; a tool that
|
|
2778
|
+
* names none falls back to `defaultRoles`, and an empty list — the default — restricts nobody. So
|
|
2779
|
+
* out of the box every tool is callable by whoever the `ActorResolver` resolved (an anonymous
|
|
2780
|
+
* visitor included, when no resolver is configured); restrict with `@AiTool({ roles })` per tool,
|
|
2781
|
+
* `AgentModule.forRoot({ defaultRoles })` module-wide, or a `rolesPolicy` of your own. `action`
|
|
2782
|
+
* tools still park on approval either way.
|
|
2783
|
+
*/
|
|
2777
2784
|
declare class DefaultRolesPolicy implements RolesPolicy {
|
|
2778
2785
|
private readonly defaultRoles;
|
|
2779
2786
|
constructor(defaultRoles?: string[]);
|
|
@@ -3479,4 +3486,203 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
|
|
|
3479
3486
|
*/
|
|
3480
3487
|
declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
|
|
3481
3488
|
|
|
3482
|
-
|
|
3489
|
+
/** A recorded usage row exposed to the governance read-model (input/output split + thread/day). */
|
|
3490
|
+
interface GovernanceUsageRow {
|
|
3491
|
+
actorRef: string;
|
|
3492
|
+
threadId: string;
|
|
3493
|
+
modelId: string;
|
|
3494
|
+
inputTokens: number;
|
|
3495
|
+
outputTokens: number;
|
|
3496
|
+
/** Subset of `inputTokens` written to the prompt cache this turn; undefined when not reported. */
|
|
3497
|
+
cacheWriteTokens?: number;
|
|
3498
|
+
/** Subset of `inputTokens` served from the prompt cache this turn; undefined when not reported. */
|
|
3499
|
+
cacheReadTokens?: number;
|
|
3500
|
+
/** Provider-reported actual cost for the turn, when known; undefined → estimate from pricing. */
|
|
3501
|
+
costUsd?: number;
|
|
3502
|
+
day: string;
|
|
3503
|
+
createdAt: string;
|
|
3504
|
+
}
|
|
3505
|
+
/** A recorded tool call exposed to the governance read-model (thread resolved, with timestamp). */
|
|
3506
|
+
interface GovernanceToolCallRow {
|
|
3507
|
+
toolCallId: string;
|
|
3508
|
+
toolName: string;
|
|
3509
|
+
toolType: 'read' | 'action';
|
|
3510
|
+
status: ToolCallStatus;
|
|
3511
|
+
threadId: string;
|
|
3512
|
+
/** The message that requested the call — the thread drill-down groups by it. */
|
|
3513
|
+
messageId: string;
|
|
3514
|
+
/** Wall-clock milliseconds the tool took to run; undefined when it never recorded one. */
|
|
3515
|
+
executionMs?: number;
|
|
3516
|
+
/** The failure text for a `failed` call; undefined otherwise. */
|
|
3517
|
+
error?: string;
|
|
3518
|
+
createdAt: string;
|
|
3519
|
+
/** The run this call belongs to; undefined when the caller didn't supply one. */
|
|
3520
|
+
runId?: string;
|
|
3521
|
+
}
|
|
3522
|
+
/** A stored message exposed to the governance read-model (the thread drill-down's transcript). */
|
|
3523
|
+
interface GovernanceMessageRow {
|
|
3524
|
+
messageId: string;
|
|
3525
|
+
threadId: string;
|
|
3526
|
+
role: string;
|
|
3527
|
+
content: string;
|
|
3528
|
+
agentName?: string;
|
|
3529
|
+
createdAt: string;
|
|
3530
|
+
}
|
|
3531
|
+
/** A tool call awaiting a HITL decision, joined to its thread + message for the approvals inbox. */
|
|
3532
|
+
interface GovernancePendingApprovalRow {
|
|
3533
|
+
toolCallId: string;
|
|
3534
|
+
toolName: string;
|
|
3535
|
+
input: unknown;
|
|
3536
|
+
threadId: string;
|
|
3537
|
+
threadTitle: string;
|
|
3538
|
+
actorRef: string;
|
|
3539
|
+
agentName?: string;
|
|
3540
|
+
requestedAt: string;
|
|
3541
|
+
/** The run this call belongs to; undefined when the caller didn't supply one. */
|
|
3542
|
+
runId?: string;
|
|
3543
|
+
}
|
|
3544
|
+
/** Thread metadata exposed to the governance read-model (title/actor/count/last activity). */
|
|
3545
|
+
interface GovernanceThreadRow {
|
|
3546
|
+
threadId: string;
|
|
3547
|
+
title: string;
|
|
3548
|
+
actorRef: string;
|
|
3549
|
+
messageCount: number;
|
|
3550
|
+
updatedAt: string;
|
|
3551
|
+
}
|
|
3552
|
+
/** A recorded run outcome exposed to the governance read-model (reliability surfaces). */
|
|
3553
|
+
interface GovernanceRunRow {
|
|
3554
|
+
runId: string;
|
|
3555
|
+
threadId: string;
|
|
3556
|
+
actorRef: string;
|
|
3557
|
+
agentName?: string;
|
|
3558
|
+
status: 'running' | 'completed' | 'failed' | 'cancelled';
|
|
3559
|
+
durationMs?: number;
|
|
3560
|
+
errorCode?: string;
|
|
3561
|
+
errorMessage?: string;
|
|
3562
|
+
retries: number;
|
|
3563
|
+
startedAt: string;
|
|
3564
|
+
settledAt?: string;
|
|
3565
|
+
promptHash?: string;
|
|
3566
|
+
/**
|
|
3567
|
+
* The run that delegated this one; undefined for a turn nobody delegated. The edge exists in the
|
|
3568
|
+
* durable journal too, but a reader of run rows has only this — and a DETACHED child outlives its
|
|
3569
|
+
* parent's turn, so nothing in the transcript pairs them either.
|
|
3570
|
+
*/
|
|
3571
|
+
parentRunId?: string;
|
|
3572
|
+
}
|
|
3573
|
+
/** A fully in-memory `AgentStore` for tests and the offline demo. */
|
|
3574
|
+
declare class InMemoryAgentStore implements AgentStore {
|
|
3575
|
+
private readonly threads;
|
|
3576
|
+
private readonly toolCalls;
|
|
3577
|
+
private readonly usage;
|
|
3578
|
+
private readonly runs;
|
|
3579
|
+
private now;
|
|
3580
|
+
createThread(input: CreateThreadInput): Promise<ThreadSummary>;
|
|
3581
|
+
getThread(threadId: string): Promise<ThreadDetail | null>;
|
|
3582
|
+
/** A message with the approval record of every call on it that was put to a person. */
|
|
3583
|
+
private withApprovals;
|
|
3584
|
+
rememberedApprovals(threadId: string): Promise<string[]>;
|
|
3585
|
+
toolCallInput(toolCallId: string): Promise<unknown>;
|
|
3586
|
+
toolCallApproval(toolCallId: string): Promise<ToolCallApprovalState | null>;
|
|
3587
|
+
listThreads(actorRef: string, limit?: number): Promise<ThreadSummary[]>;
|
|
3588
|
+
softDeleteThread(threadId: string): Promise<void>;
|
|
3589
|
+
forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
|
|
3590
|
+
ownerOfThread(threadId: string): Promise<string | null>;
|
|
3591
|
+
ownerOfToolCall(toolCallId: string): Promise<string | null>;
|
|
3592
|
+
runForToolCall(toolCallId: string): Promise<string | null>;
|
|
3593
|
+
ownerOfActiveStream(runId: string): Promise<string | null>;
|
|
3594
|
+
setTitle(threadId: string, title: string): Promise<void>;
|
|
3595
|
+
updateThread(threadId: string, patch: UpdateThreadInput): Promise<void>;
|
|
3596
|
+
activeRunForThread(threadId: string): Promise<string | null>;
|
|
3597
|
+
/**
|
|
3598
|
+
* The thread's default agent, projected. A map lookup here, but the SQL adapters answer this with
|
|
3599
|
+
* a one-column read instead of materializing the whole transcript — so the caller that only needs
|
|
3600
|
+
* this scalar has a method to ask for it.
|
|
3601
|
+
*/
|
|
3602
|
+
defaultAgentForThread(threadId: string): Promise<string | null>;
|
|
3603
|
+
/** The thread's pinned model, projected like {@link defaultAgentForThread}. */
|
|
3604
|
+
modelForThread(threadId: string): Promise<string | null>;
|
|
3605
|
+
/**
|
|
3606
|
+
* Persist the start of a run (turn). Replay-safe: called under a durable localStep.
|
|
3607
|
+
*
|
|
3608
|
+
* Takes the SPI's own {@link RecordRunStartInput} rather than a hand-copied shape: a field added
|
|
3609
|
+
* to the input is otherwise accepted and dropped, silently, by every adapter that re-declares it.
|
|
3610
|
+
*/
|
|
3611
|
+
recordRunStart(run: RecordRunStartInput): Promise<void>;
|
|
3612
|
+
/** Settle a run's outcome. A no-op when the run is unknown (mirrors `setTitle`/`updateThread`). */
|
|
3613
|
+
recordRunEnd(end: {
|
|
3614
|
+
runId: string;
|
|
3615
|
+
status: 'completed' | 'failed' | 'cancelled';
|
|
3616
|
+
durationMs?: number;
|
|
3617
|
+
errorCode?: string;
|
|
3618
|
+
errorMessage?: string;
|
|
3619
|
+
}): Promise<void>;
|
|
3620
|
+
/** Bump the run's llm-step retry counter. */
|
|
3621
|
+
bumpRunRetries(runId: string): Promise<void>;
|
|
3622
|
+
promoteThread(threadId: string): Promise<void>;
|
|
3623
|
+
setActiveStream(threadId: string, runId: string | null): Promise<void>;
|
|
3624
|
+
appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
|
|
3625
|
+
setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
|
|
3626
|
+
setMessageUi(messageId: string, ui: AgentUiComponent[]): Promise<void>;
|
|
3627
|
+
threadOfMessage(messageId: string): Promise<string | null>;
|
|
3628
|
+
setMessageFeedback(messageId: string, feedback: MessageFeedback | null): Promise<void>;
|
|
3629
|
+
truncateFrom(threadId: string, messageId: string): Promise<void>;
|
|
3630
|
+
/**
|
|
3631
|
+
* Of `mediaIds`, the ones a surviving message in one of this actor's threads still carries.
|
|
3632
|
+
* Re-derived from the messages each call, so a media whose message was truncated away reads as
|
|
3633
|
+
* unreferenced again.
|
|
3634
|
+
*/
|
|
3635
|
+
referencedMediaIds(actorRef: string, mediaIds: readonly string[]): Promise<string[]>;
|
|
3636
|
+
recordToolCall(input: RecordToolCallInput): Promise<void>;
|
|
3637
|
+
updateToolCall(input: UpdateToolCallInput): Promise<void>;
|
|
3638
|
+
recordUsage(input: RecordUsageInput): Promise<void>;
|
|
3639
|
+
quotaToday(actorRef: string, day: string): Promise<{
|
|
3640
|
+
usedTokens: number;
|
|
3641
|
+
costUsd: number;
|
|
3642
|
+
}>;
|
|
3643
|
+
usageBetween(actorRef: string, fromDay: string, toDay: string): Promise<{
|
|
3644
|
+
usedTokens: number;
|
|
3645
|
+
costUsd: number;
|
|
3646
|
+
}>;
|
|
3647
|
+
/** Test helper: read the recorded usage rows (modelId + token totals). */
|
|
3648
|
+
usageRows(): {
|
|
3649
|
+
actorRef: string;
|
|
3650
|
+
tokens: number;
|
|
3651
|
+
modelId: string;
|
|
3652
|
+
}[];
|
|
3653
|
+
/** Governance read-model feed: recorded usage rows with the input/output split + thread/day. */
|
|
3654
|
+
governanceUsage(): GovernanceUsageRow[];
|
|
3655
|
+
/** Governance read-model feed: recorded tool calls with the resolved thread + timestamp. */
|
|
3656
|
+
governanceToolCalls(): GovernanceToolCallRow[];
|
|
3657
|
+
/** Governance read-model feed: every stored message, thread-resolved, for the thread drill-down. */
|
|
3658
|
+
governanceMessages(): GovernanceMessageRow[];
|
|
3659
|
+
/**
|
|
3660
|
+
* Governance read-model feed: tool calls sitting `pending_approval`, joined to their thread
|
|
3661
|
+
* (title/actorRef) and the message that requested them (`agentName`, when the message has one).
|
|
3662
|
+
*/
|
|
3663
|
+
governancePendingApprovals(): GovernancePendingApprovalRow[];
|
|
3664
|
+
/** Governance read-model feed: thread metadata (title/actor/message count/last activity). */
|
|
3665
|
+
governanceThreads(): GovernanceThreadRow[];
|
|
3666
|
+
/** Governance read-model feed: recorded run outcomes (the reliability surfaces). */
|
|
3667
|
+
governanceRuns(): GovernanceRunRow[];
|
|
3668
|
+
private threadIdForMessage;
|
|
3669
|
+
/** Test helper: read the recorded tool-call rows. */
|
|
3670
|
+
toolCallRows(): {
|
|
3671
|
+
toolCallId: string;
|
|
3672
|
+
toolName: string;
|
|
3673
|
+
toolType: 'read' | 'action';
|
|
3674
|
+
status: ToolCallStatus;
|
|
3675
|
+
input?: unknown;
|
|
3676
|
+
output?: unknown;
|
|
3677
|
+
error?: string;
|
|
3678
|
+
runId?: string;
|
|
3679
|
+
executedByRef?: string;
|
|
3680
|
+
approver?: string;
|
|
3681
|
+
expiresAt?: string;
|
|
3682
|
+
remember?: boolean;
|
|
3683
|
+
decidedVia?: string;
|
|
3684
|
+
}[];
|
|
3685
|
+
private toSummary;
|
|
3686
|
+
}
|
|
3687
|
+
|
|
3688
|
+
export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
|