@adonis-agora/agent 0.30.2 → 0.33.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/CHANGELOG.md +866 -0
- package/dist/assets/spa/assets/{index-Cfi3g3b2.js → index-3Q2m5_Ax.js} +1 -1
- package/dist/assets/spa/index.html +1 -1
- package/dist/providers/agent_provider.d.ts.map +1 -1
- package/dist/providers/agent_provider.js +157 -9
- package/dist/providers/agent_provider.js.map +1 -1
- package/dist/src/agent-deps-factory.d.ts +16 -2
- package/dist/src/agent-deps-factory.d.ts.map +1 -1
- package/dist/src/agent-deps-factory.js +8 -0
- package/dist/src/agent-deps-factory.js.map +1 -1
- package/dist/src/agent-deps.d.ts +21 -1
- package/dist/src/agent-deps.d.ts.map +1 -1
- package/dist/src/agent-deps.js.map +1 -1
- package/dist/src/agent-loop.d.ts +226 -9
- package/dist/src/agent-loop.d.ts.map +1 -1
- package/dist/src/agent-loop.js +1311 -208
- package/dist/src/agent-loop.js.map +1 -1
- package/dist/src/agent-service.d.ts +27 -0
- package/dist/src/agent-service.d.ts.map +1 -1
- package/dist/src/agent-service.js +29 -0
- package/dist/src/agent-service.js.map +1 -1
- package/dist/src/ai-sdk/ai-sdk-model.d.ts.map +1 -1
- package/dist/src/ai-sdk/ai-sdk-model.js +21 -1
- package/dist/src/ai-sdk/ai-sdk-model.js.map +1 -1
- package/dist/src/client/sse.d.ts +32 -2
- package/dist/src/client/sse.d.ts.map +1 -1
- package/dist/src/client/sse.js +45 -2
- package/dist/src/client/sse.js.map +1 -1
- package/dist/src/define_config.d.ts +41 -7
- package/dist/src/define_config.d.ts.map +1 -1
- package/dist/src/define_config.js.map +1 -1
- package/dist/src/durable/agent-run-workflow.d.ts +10 -11
- package/dist/src/durable/agent-run-workflow.d.ts.map +1 -1
- package/dist/src/durable/agent-run-workflow.js +49 -21
- package/dist/src/durable/agent-run-workflow.js.map +1 -1
- package/dist/src/durable/durable-agent-runner.d.ts +3 -2
- package/dist/src/durable/durable-agent-runner.d.ts.map +1 -1
- package/dist/src/durable/durable-agent-runner.js +2 -2
- package/dist/src/durable/durable-agent-runner.js.map +1 -1
- package/dist/src/elicitation.d.ts +207 -0
- package/dist/src/elicitation.d.ts.map +1 -0
- package/dist/src/elicitation.js +315 -0
- package/dist/src/elicitation.js.map +1 -0
- package/dist/src/evals/approval-prior.d.ts +58 -0
- package/dist/src/evals/approval-prior.d.ts.map +1 -0
- package/dist/src/evals/approval-prior.js +82 -0
- package/dist/src/evals/approval-prior.js.map +1 -0
- package/dist/src/evals/evaluate.d.ts +51 -0
- package/dist/src/evals/evaluate.d.ts.map +1 -0
- package/dist/src/evals/evaluate.js +76 -0
- package/dist/src/evals/evaluate.js.map +1 -0
- package/dist/src/evals/governance-sample-source.d.ts +23 -0
- package/dist/src/evals/governance-sample-source.d.ts.map +1 -0
- package/dist/src/evals/governance-sample-source.js +93 -0
- package/dist/src/evals/governance-sample-source.js.map +1 -0
- package/dist/src/evals/in-memory-score-store.d.ts +16 -0
- package/dist/src/evals/in-memory-score-store.d.ts.map +1 -0
- package/dist/src/evals/in-memory-score-store.js +57 -0
- package/dist/src/evals/in-memory-score-store.js.map +1 -0
- package/dist/src/evals/index.d.ts +15 -0
- package/dist/src/evals/index.d.ts.map +1 -0
- package/dist/src/evals/index.js +14 -0
- package/dist/src/evals/index.js.map +1 -0
- package/dist/src/evals/judge.d.ts +30 -0
- package/dist/src/evals/judge.d.ts.map +1 -0
- package/dist/src/evals/judge.js +53 -0
- package/dist/src/evals/judge.js.map +1 -0
- package/dist/src/evals/live-scoring.d.ts +42 -0
- package/dist/src/evals/live-scoring.d.ts.map +1 -0
- package/dist/src/evals/live-scoring.js +103 -0
- package/dist/src/evals/live-scoring.js.map +1 -0
- package/dist/src/evals/sample-source.d.ts +40 -0
- package/dist/src/evals/sample-source.d.ts.map +1 -0
- package/dist/src/evals/sample-source.js +33 -0
- package/dist/src/evals/sample-source.js.map +1 -0
- package/dist/src/evals/score-store.d.ts +54 -0
- package/dist/src/evals/score-store.d.ts.map +1 -0
- package/dist/src/evals/score-store.js +2 -0
- package/dist/src/evals/score-store.js.map +1 -0
- package/dist/src/evals/scorers/answer-relevancy.scorer.d.ts +28 -0
- package/dist/src/evals/scorers/answer-relevancy.scorer.d.ts.map +1 -0
- package/dist/src/evals/scorers/answer-relevancy.scorer.js +42 -0
- package/dist/src/evals/scorers/answer-relevancy.scorer.js.map +1 -0
- package/dist/src/evals/scorers/approval-outcome.scorer.d.ts +22 -0
- package/dist/src/evals/scorers/approval-outcome.scorer.d.ts.map +1 -0
- package/dist/src/evals/scorers/approval-outcome.scorer.js +60 -0
- package/dist/src/evals/scorers/approval-outcome.scorer.js.map +1 -0
- package/dist/src/evals/scorers/approval-risk.scorer.d.ts +28 -0
- package/dist/src/evals/scorers/approval-risk.scorer.d.ts.map +1 -0
- package/dist/src/evals/scorers/approval-risk.scorer.js +54 -0
- package/dist/src/evals/scorers/approval-risk.scorer.js.map +1 -0
- package/dist/src/evals/scorers/run-completion.scorer.d.ts +18 -0
- package/dist/src/evals/scorers/run-completion.scorer.d.ts.map +1 -0
- package/dist/src/evals/scorers/run-completion.scorer.js +55 -0
- package/dist/src/evals/scorers/run-completion.scorer.js.map +1 -0
- package/dist/src/evals/summarize.d.ts +44 -0
- package/dist/src/evals/summarize.d.ts.map +1 -0
- package/dist/src/evals/summarize.js +87 -0
- package/dist/src/evals/summarize.js.map +1 -0
- package/dist/src/evals/types.d.ts +81 -0
- package/dist/src/evals/types.d.ts.map +1 -0
- package/dist/src/evals/types.js +15 -0
- package/dist/src/evals/types.js.map +1 -0
- package/dist/src/history-window.d.ts +50 -11
- package/dist/src/history-window.d.ts.map +1 -1
- package/dist/src/history-window.js +84 -12
- package/dist/src/history-window.js.map +1 -1
- package/dist/src/index.d.ts +11 -3
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +10 -3
- package/dist/src/index.js.map +1 -1
- package/dist/src/mcp/server.d.ts +8 -0
- package/dist/src/mcp/server.d.ts.map +1 -1
- package/dist/src/mcp/server.js +27 -1
- package/dist/src/mcp/server.js.map +1 -1
- package/dist/src/mcp-client/importer.d.ts +75 -0
- package/dist/src/mcp-client/importer.d.ts.map +1 -0
- package/dist/src/mcp-client/importer.js +161 -0
- package/dist/src/mcp-client/importer.js.map +1 -0
- package/dist/src/mcp-client/index.d.ts +9 -0
- package/dist/src/mcp-client/index.d.ts.map +1 -0
- package/dist/src/mcp-client/index.js +8 -0
- package/dist/src/mcp-client/index.js.map +1 -0
- package/dist/src/mcp-client/options.d.ts +99 -0
- package/dist/src/mcp-client/options.d.ts.map +1 -0
- package/dist/src/mcp-client/options.js +2 -0
- package/dist/src/mcp-client/options.js.map +1 -0
- package/dist/src/mcp-client/tool-input.d.ts +39 -0
- package/dist/src/mcp-client/tool-input.d.ts.map +1 -0
- package/dist/src/mcp-client/tool-input.js +61 -0
- package/dist/src/mcp-client/tool-input.js.map +1 -0
- package/dist/src/mcp-client/tool-kind.d.ts +37 -0
- package/dist/src/mcp-client/tool-kind.d.ts.map +1 -0
- package/dist/src/mcp-client/tool-kind.js +20 -0
- package/dist/src/mcp-client/tool-kind.js.map +1 -0
- package/dist/src/mcp-client/tool-name.d.ts +22 -0
- package/dist/src/mcp-client/tool-name.d.ts.map +1 -0
- package/dist/src/mcp-client/tool-name.js +35 -0
- package/dist/src/mcp-client/tool-name.js.map +1 -0
- package/dist/src/mcp-client/tool-source.d.ts +75 -0
- package/dist/src/mcp-client/tool-source.d.ts.map +1 -0
- package/dist/src/mcp-client/tool-source.js +244 -0
- package/dist/src/mcp-client/tool-source.js.map +1 -0
- package/dist/src/mcp-client/transient.d.ts +28 -0
- package/dist/src/mcp-client/transient.d.ts.map +1 -0
- package/dist/src/mcp-client/transient.js +126 -0
- package/dist/src/mcp-client/transient.js.map +1 -0
- package/dist/src/mcp-client/unsafe-regex.d.ts +23 -0
- package/dist/src/mcp-client/unsafe-regex.d.ts.map +1 -0
- package/dist/src/mcp-client/unsafe-regex.js +194 -0
- package/dist/src/mcp-client/unsafe-regex.js.map +1 -0
- package/dist/src/memory.d.ts +448 -0
- package/dist/src/memory.d.ts.map +1 -0
- package/dist/src/memory.js +330 -0
- package/dist/src/memory.js.map +1 -0
- package/dist/src/pagination.d.ts +63 -0
- package/dist/src/pagination.d.ts.map +1 -0
- package/dist/src/pagination.js +16 -0
- package/dist/src/pagination.js.map +1 -0
- package/dist/src/processors.d.ts +134 -0
- package/dist/src/processors.d.ts.map +1 -0
- package/dist/src/processors.js +215 -0
- package/dist/src/processors.js.map +1 -0
- package/dist/src/rag/qdrant-store.d.ts +48 -6
- package/dist/src/rag/qdrant-store.d.ts.map +1 -1
- package/dist/src/rag/qdrant-store.js +77 -24
- package/dist/src/rag/qdrant-store.js.map +1 -1
- package/dist/src/replay-integrity.d.ts +17 -0
- package/dist/src/replay-integrity.d.ts.map +1 -0
- package/dist/src/replay-integrity.js +19 -0
- package/dist/src/replay-integrity.js.map +1 -0
- package/dist/src/runners/inline-agent-runner.d.ts +33 -7
- package/dist/src/runners/inline-agent-runner.d.ts.map +1 -1
- package/dist/src/runners/inline-agent-runner.js +113 -27
- package/dist/src/runners/inline-agent-runner.js.map +1 -1
- package/dist/src/skills.d.ts +291 -0
- package/dist/src/skills.d.ts.map +1 -0
- package/dist/src/skills.js +0 -0
- package/dist/src/skills.js.map +1 -0
- package/dist/src/spi/agent-runner.d.ts +20 -6
- package/dist/src/spi/agent-runner.d.ts.map +1 -1
- package/dist/src/spi/agent-store.d.ts +53 -0
- package/dist/src/spi/agent-store.d.ts.map +1 -1
- package/dist/src/spi/governance-queries.d.ts +33 -13
- package/dist/src/spi/governance-queries.d.ts.map +1 -1
- package/dist/src/spi/history-window.d.ts +64 -10
- package/dist/src/spi/history-window.d.ts.map +1 -1
- package/dist/src/spi/model-provider.d.ts +18 -0
- package/dist/src/spi/model-provider.d.ts.map +1 -1
- package/dist/src/spi/processors.d.ts +161 -0
- package/dist/src/spi/processors.d.ts.map +1 -0
- package/dist/src/spi/processors.js +57 -0
- package/dist/src/spi/processors.js.map +1 -0
- package/dist/src/spi/token-stream-sink.d.ts +43 -0
- package/dist/src/spi/token-stream-sink.d.ts.map +1 -1
- package/dist/src/spi/token-stream-sink.js +17 -1
- package/dist/src/spi/token-stream-sink.js.map +1 -1
- package/dist/src/sse.d.ts +5 -2
- package/dist/src/sse.d.ts.map +1 -1
- package/dist/src/sse.js +11 -2
- package/dist/src/sse.js.map +1 -1
- package/dist/src/stores/lucid-governance-queries.d.ts +5 -2
- package/dist/src/stores/lucid-governance-queries.d.ts.map +1 -1
- package/dist/src/stores/lucid-governance-queries.js +14 -5
- package/dist/src/stores/lucid-governance-queries.js.map +1 -1
- package/dist/src/stores/lucid-schema.d.ts.map +1 -1
- package/dist/src/stores/lucid-schema.js +15 -0
- package/dist/src/stores/lucid-schema.js.map +1 -1
- package/dist/src/stores/lucid.d.ts +11 -3
- package/dist/src/stores/lucid.d.ts.map +1 -1
- package/dist/src/stores/lucid.js +65 -0
- package/dist/src/stores/lucid.js.map +1 -1
- package/dist/src/structured-output.d.ts +57 -0
- package/dist/src/structured-output.d.ts.map +1 -0
- package/dist/src/structured-output.js +80 -0
- package/dist/src/structured-output.js.map +1 -0
- package/dist/src/telescope/agent-governance-providers.js +2 -2
- package/dist/src/telescope/agent-governance-providers.js.map +1 -1
- package/dist/src/testing/fake-model-provider.d.ts +8 -4
- package/dist/src/testing/fake-model-provider.d.ts.map +1 -1
- package/dist/src/testing/fake-model-provider.js +6 -9
- package/dist/src/testing/fake-model-provider.js.map +1 -1
- package/dist/src/testing/in-memory-governance-queries.d.ts.map +1 -1
- package/dist/src/testing/in-memory-governance-queries.js +8 -3
- package/dist/src/testing/in-memory-governance-queries.js.map +1 -1
- package/dist/src/testing/in-memory-store.d.ts +4 -3
- package/dist/src/testing/in-memory-store.d.ts.map +1 -1
- package/dist/src/testing/in-memory-store.js +13 -7
- package/dist/src/testing/in-memory-store.js.map +1 -1
- package/dist/src/testing/index.d.ts +1 -1
- package/dist/src/testing/index.d.ts.map +1 -1
- package/dist/src/testing/index.js.map +1 -1
- package/dist/src/tool-registry.d.ts +9 -0
- package/dist/src/tool-registry.d.ts.map +1 -1
- package/dist/src/tool-registry.js +11 -0
- package/dist/src/tool-registry.js.map +1 -1
- package/dist/src/types.d.ts +55 -2
- package/dist/src/types.d.ts.map +1 -1
- package/package.json +20 -10
- package/skills/agent-personas-agents/SKILL.md +16 -12
package/dist/src/agent-loop.d.ts
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
|
+
import type { StandardSchemaV1 } from '@standard-schema/spec';
|
|
2
|
+
import { type AgentIntake, type ElicitationRequest, type HumanReply } from './elicitation.js';
|
|
3
|
+
import { type MemoryConfig } from './memory.js';
|
|
4
|
+
import { type SkillsConfig } from './skills.js';
|
|
1
5
|
import type { AgentStore } from './spi/agent-store.js';
|
|
2
6
|
import type { HistoryWindow } from './spi/history-window.js';
|
|
3
7
|
import type { ModelProvider } from './spi/model-provider.js';
|
|
4
8
|
import { type AgentPricingStore } from './spi/pricing-store.js';
|
|
9
|
+
import { type InputProcessor, type OutputProcessor } from './spi/processors.js';
|
|
5
10
|
import type { QuotaStore } from './spi/quota-store.js';
|
|
6
11
|
import type { Retriever } from './spi/retriever.js';
|
|
7
12
|
import type { RolesPolicy } from './spi/roles-policy.js';
|
|
@@ -9,8 +14,8 @@ import type { SinkWriter } from './spi/token-stream-sink.js';
|
|
|
9
14
|
import type { AiToolCtx } from './spi/tool.js';
|
|
10
15
|
import { type ToolRegistry } from './tool-registry.js';
|
|
11
16
|
import { type ToolTransientRetrySetting } from './tool-retry.js';
|
|
12
|
-
import type { Actor, AgentRunInput, Decision, PromptBuilder, ToolCallRequest } from './types.js';
|
|
13
|
-
export interface AgentLoopDeps {
|
|
17
|
+
import type { Actor, AgentRunInput, Decision, PromptBuilder, ToolCallRequest, ToolDefinition } from './types.js';
|
|
18
|
+
export interface AgentLoopDeps<TOutput = unknown> {
|
|
14
19
|
model: ModelProvider;
|
|
15
20
|
store: AgentStore;
|
|
16
21
|
registry: ToolRegistry;
|
|
@@ -37,6 +42,19 @@ export interface AgentLoopDeps {
|
|
|
37
42
|
host?: unknown;
|
|
38
43
|
/** Agent-level tool allow-list (intersected with the persona's). Undefined → all tools. */
|
|
39
44
|
toolAllowList?: string[];
|
|
45
|
+
/**
|
|
46
|
+
* How many agent→agent delegations deep a chain may go. Defaults to {@link MAX_DELEGATION_DEPTH}.
|
|
47
|
+
*
|
|
48
|
+
* The backstop for a chain that is merely LONG; a chain going in circles is caught by
|
|
49
|
+
* {@link maxAgentAppearances} instead, and named as such.
|
|
50
|
+
*/
|
|
51
|
+
maxDelegationDepth?: number;
|
|
52
|
+
/**
|
|
53
|
+
* How many times one agent may appear on a single delegation chain. Defaults to
|
|
54
|
+
* {@link DEFAULT_MAX_AGENT_APPEARANCES}. It counts APPEARANCES, so 2 admits exactly one
|
|
55
|
+
* deliberate return to an earlier agent.
|
|
56
|
+
*/
|
|
57
|
+
maxAgentAppearances?: number;
|
|
40
58
|
/**
|
|
41
59
|
* Enables always-on ("inject") RAG: before the turn, retrieve passages for the user message and fold
|
|
42
60
|
* them into the system prompt. Its presence IS inject mode (a retriever wired as a `read` tool for
|
|
@@ -66,13 +84,138 @@ export interface AgentLoopDeps {
|
|
|
66
84
|
*/
|
|
67
85
|
toolTransientRetry?: ToolTransientRetrySetting;
|
|
68
86
|
/**
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
87
|
+
* Bounds how much of the persisted thread rides into the model call each turn. Undefined → the
|
|
88
|
+
* WHOLE thread, every message the store holds, which is unbounded: a long-lived thread eventually
|
|
89
|
+
* exceeds the provider's context limit, and pays for the full transcript on every turn until it
|
|
90
|
+
* does. Applied once per run. See {@link SlidingWindowHistory} for the built-in.
|
|
73
91
|
*/
|
|
74
92
|
historyWindow?: HistoryWindow;
|
|
93
|
+
/**
|
|
94
|
+
* Rewrites `{ system, messages }` before EVERY model call of the turn — masking identifiers,
|
|
95
|
+
* stamping a policy preamble, collapsing an oversized tool result. Every step, not once per run,
|
|
96
|
+
* because the transcript grows between steps. Adds one `process:input:<step>` checkpoint per step;
|
|
97
|
+
* empty/undefined adds none, so a deployment with no processors records byte-identical
|
|
98
|
+
* checkpoints.
|
|
99
|
+
*
|
|
100
|
+
* Not a second {@link HistoryWindow}: that owns WHICH messages ride into the turn (pure, outside
|
|
101
|
+
* any checkpoint), this owns what they SAY (may call a model, journaled). The loop's canonical
|
|
102
|
+
* `modelMessages` is untouched — a redaction is what leaves the process, never the thread's own
|
|
103
|
+
* memory of what was said.
|
|
104
|
+
*/
|
|
105
|
+
inputProcessors?: InputProcessor[];
|
|
106
|
+
/**
|
|
107
|
+
* Rules on each step's answer before anything downstream sees it, and may redact or refuse it.
|
|
108
|
+
* Adds one `process:output:<step>` checkpoint per step.
|
|
109
|
+
*
|
|
110
|
+
* **Registering any of these takes the turn's model call off the run's live sink**, because a gate
|
|
111
|
+
* that must read the answer cannot run after the answer has reached the reader. What that costs is
|
|
112
|
+
* proportional to what the chain declares: a chain whose every member declares
|
|
113
|
+
* {@link import('./spi/processors.js').OutputProcessor.incremental} keeps streaming a
|
|
114
|
+
* lookback-bounded prefix; one undeclared member holds the whole answer and releases it as a
|
|
115
|
+
* single `text` frame once the chain has passed.
|
|
116
|
+
*/
|
|
117
|
+
outputProcessors?: OutputProcessor[];
|
|
118
|
+
/**
|
|
119
|
+
* Constrain the turn's answer to a schema — any [Standard Schema](https://standardschema.dev) —
|
|
120
|
+
* returned validated as `object` on the loop's result and recorded on the assistant message as a
|
|
121
|
+
* synthetic auto-executed `structured_output` tool call, the same device inject-mode retrieval
|
|
122
|
+
* uses, so no store gains a column for it.
|
|
123
|
+
*
|
|
124
|
+
* HOW IT COMPOSES WITH TOOL CALLING: as a separate formatting pass, ALWAYS. The turn runs its
|
|
125
|
+
* model→tools iteration exactly as it would without a schema; once a step comes back with no tool
|
|
126
|
+
* calls, one extra non-streamed call (`structured:<step>:<attempt>`, `tools: []`, `outputSchema`
|
|
127
|
+
* set) restates that answer as the schema. Most providers cannot serve a response format and a
|
|
128
|
+
* tool set in one request, and skipping the pass for an agent that happens to have no tools would
|
|
129
|
+
* make the checkpoint sequence depend on a tool-registry lookup — the registry of whichever
|
|
130
|
+
* process is replaying — which is exactly how a run ends up asking for a position its history has
|
|
131
|
+
* no room for. So the pass is unconditional, and it costs one model call per turn, billed as its
|
|
132
|
+
* own `structured_output` usage row.
|
|
133
|
+
*/
|
|
134
|
+
outputSchema?: StandardSchemaV1<unknown, TOutput>;
|
|
135
|
+
/** Overrides the formatting pass's system prompt. Undefined → {@link DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION}. */
|
|
136
|
+
outputInstruction?: string;
|
|
137
|
+
/**
|
|
138
|
+
* How many extra model calls may try to fix an answer that failed `outputSchema`, each shown the
|
|
139
|
+
* previous attempt's validation issues. Undefined → 1; `0` → fail on the first invalid reply.
|
|
140
|
+
* Bounded because a model that cannot satisfy a schema usually cannot satisfy it on the fourth try
|
|
141
|
+
* either, and every attempt is billed.
|
|
142
|
+
*/
|
|
143
|
+
outputRepairAttempts?: number;
|
|
144
|
+
/**
|
|
145
|
+
* Show the formatting pass the turn's whole transcript instead of just the question and the
|
|
146
|
+
* answer. For an agent whose answer cannot be restated from its own words — one that reports on
|
|
147
|
+
* rows a tool returned and names only their total in the prose, say.
|
|
148
|
+
*
|
|
149
|
+
* OFF by default because the pass is a translation, and a translation needs the thing being
|
|
150
|
+
* translated. The transcript it would otherwise carry is the turn's entire prompt a second time,
|
|
151
|
+
* at no discount: the pass swaps the system block for the schema instruction, and the system block
|
|
152
|
+
* is the prompt cache's prefix, so nothing of the first call's cache survives into it.
|
|
153
|
+
*/
|
|
154
|
+
outputFromTranscript?: boolean;
|
|
155
|
+
/**
|
|
156
|
+
* A question set the agent puts to the user BEFORE it starts working — collecting the scope, as
|
|
157
|
+
* against `awaitApproval`, which sanctions work already proposed. The questions are AUTHORED, so
|
|
158
|
+
* the turn spends no model call producing them and a client knows the total ("Question 1 of 3")
|
|
159
|
+
* the moment the form appears.
|
|
160
|
+
*
|
|
161
|
+
* The turn parks on the answers exactly as it parks on an approval, and the request persists as
|
|
162
|
+
* the same tool-call row the model's `ask` writes — see {@link AgentLoopDeps.ask}. Undefined → no
|
|
163
|
+
* intake, and a turn's checkpoint sequence is byte-identical to one that never had the option.
|
|
164
|
+
*/
|
|
165
|
+
intake?: AgentIntake;
|
|
166
|
+
/**
|
|
167
|
+
* Offer the model the built-in `ask` tool, so it can put its own question set to the user when it
|
|
168
|
+
* judges the scope is missing — the same surface as {@link AgentLoopDeps.intake}, minus the "known
|
|
169
|
+
* in advance".
|
|
170
|
+
*
|
|
171
|
+
* `ask` is NOT a registered tool: it has no handler (the loop settles it against a human), and
|
|
172
|
+
* keeping it out of the `ToolRegistry` is what keeps its kind out of a process-local lookup. The
|
|
173
|
+
* loop appends its definition to the turn's tool list from THIS flag, which is module config and
|
|
174
|
+
* therefore uniform across a deployment. Undefined/false → the model never sees it.
|
|
175
|
+
*/
|
|
176
|
+
ask?: boolean;
|
|
177
|
+
/**
|
|
178
|
+
* Authored procedures the model can pull in mid-turn, scoped to the actor's own scope tokens — see
|
|
179
|
+
* `skills.ts`. Undefined → no catalog block, no `skill` tool, and a turn's checkpoint sequence is
|
|
180
|
+
* byte-identical to one that never had the option.
|
|
181
|
+
*
|
|
182
|
+
* WHAT IT COSTS THE PROMPT. Four things write the system block — the agent's own prompt, the
|
|
183
|
+
* persona's, injected retrieval, and this — and the catalog is the cheapest of them by
|
|
184
|
+
* construction: one line per skill, carrying a name, a scope and a description. A skill's BODY
|
|
185
|
+
* never enters the system block at all; it arrives as a tool result, on the transcript, where
|
|
186
|
+
* {@link AgentLoopDeps.historyWindow} already governs it. So a deployment with fifty skills pays
|
|
187
|
+
* for fifty lines and for whichever bodies a turn actually asked to read.
|
|
188
|
+
*/
|
|
189
|
+
skills?: SkillsConfig;
|
|
190
|
+
/**
|
|
191
|
+
* What the assistant has concluded about this actor and their organisation, carried into every
|
|
192
|
+
* turn against the same scope tokens skills use — see `memory.ts`. Undefined → no memory block, no
|
|
193
|
+
* `remember` tool, and a turn's checkpoint sequence is byte-identical to one that never had the
|
|
194
|
+
* option.
|
|
195
|
+
*
|
|
196
|
+
* WHY IT IS IN THE SYSTEM BLOCK AT ALL, when a skill's body deliberately is not. A body is read
|
|
197
|
+
* when the model decides a task needs it; a memory is worthless unless it is already in front of
|
|
198
|
+
* the model on the turn nobody thought to look for it. That is the whole capability, and it costs
|
|
199
|
+
* one line per memory, bounded by `maxMemories` here and by `maxFactChars` at write time.
|
|
200
|
+
*/
|
|
201
|
+
memory?: MemoryConfig;
|
|
75
202
|
}
|
|
203
|
+
/** One task's outcome under {@link AgentLoopHooks.parallel}, reported instead of thrown. */
|
|
204
|
+
export type SettledTask<T> = {
|
|
205
|
+
ok: true;
|
|
206
|
+
value: T;
|
|
207
|
+
} | {
|
|
208
|
+
ok: false;
|
|
209
|
+
error: unknown;
|
|
210
|
+
};
|
|
211
|
+
/**
|
|
212
|
+
* The {@link AgentLoopHooks.parallel} implementation for a runner whose checkpoint positions are
|
|
213
|
+
* handed out on the CALL — `@adonis-agora/durable`'s `ctx.localStep` is: it takes `pos.next()`
|
|
214
|
+
* before its first `await`. Every task is invoked here, synchronously and in list order, before any
|
|
215
|
+
* of them is awaited, which is what fixes the block of positions they occupy whatever order they
|
|
216
|
+
* then settle in. Nothing rejects: the caller decides what an individual failure means.
|
|
217
|
+
*/
|
|
218
|
+
export declare function settleAll<T>(tasks: readonly (() => Promise<T>)[]): Promise<SettledTask<T>[]>;
|
|
76
219
|
export interface AgentLoopHooks {
|
|
77
220
|
runId: string;
|
|
78
221
|
/**
|
|
@@ -84,6 +227,21 @@ export interface AgentLoopHooks {
|
|
|
84
227
|
openSink(): SinkWriter | Promise<SinkWriter>;
|
|
85
228
|
/** HITL gate for an action tool. Inline resolves a pending promise; durable awaits a signal. */
|
|
86
229
|
awaitApproval(call: ToolCallRequest, ctx: AiToolCtx): Promise<Decision>;
|
|
230
|
+
/**
|
|
231
|
+
* The wait an elicitation parks on. Both shipped runners map it to the SAME channel an approval
|
|
232
|
+
* uses — `tool:<runId>:<callId>` — so an answer and an approval reach a parked run by one path.
|
|
233
|
+
*
|
|
234
|
+
* Optional, and its absence changes no checkpoint: the loop falls back to `awaitApproval` and
|
|
235
|
+
* reads the decision as "the user confirmed the pre-picked answers" (approved) or "the user
|
|
236
|
+
* skipped" (rejected). That is the honest reduction of a yes/no channel, and it means a host that
|
|
237
|
+
* only ever implemented approval still runs an elicitation to completion instead of hanging.
|
|
238
|
+
*
|
|
239
|
+
* Declared as {@link HumanReply} rather than `ElicitationReply` because that is what the channel
|
|
240
|
+
* really carries: a question set is parked as a `pending_approval` action, so a `Decision` can
|
|
241
|
+
* arrive on this wait from the approvals inbox even where the host implements it. The loop reduces
|
|
242
|
+
* one to the other, so an implementer never has to.
|
|
243
|
+
*/
|
|
244
|
+
awaitAnswers?(request: ElicitationRequest, ctx: AiToolCtx): Promise<HumanReply>;
|
|
87
245
|
/**
|
|
88
246
|
* Run another named agent and return its answer. Provided only when the host wired multi-agent
|
|
89
247
|
* support (durable → child workflow, inline → nested loop). Exposed to tools as `ctx.runAgent`.
|
|
@@ -103,16 +261,75 @@ export interface AgentLoopHooks {
|
|
|
103
261
|
* runner; the inline runner has no such notion and leaves it unset.
|
|
104
262
|
*/
|
|
105
263
|
isControlFlowError?(error: unknown): boolean;
|
|
264
|
+
/**
|
|
265
|
+
* Run `tasks` concurrently, resolving once EVERY one has settled — one outcome per task, in INPUT
|
|
266
|
+
* order, never rejecting. Supplying it is a statement about the runner's checkpointing: each task
|
|
267
|
+
* MUST be invoked synchronously, in list order, before any is awaited, so a runner that hands out
|
|
268
|
+
* positions on the call assigns them in that order regardless of which task finishes first.
|
|
269
|
+
* {@link settleAll} is exactly that, and is what both bundled runners pass.
|
|
270
|
+
*
|
|
271
|
+
* Waiting for ALL of them is the other half of the contract. A durable runner unwinds a turn by
|
|
272
|
+
* THROWING, and a sibling abandoned part-way through its own step is a tool nobody ever runs.
|
|
273
|
+
*
|
|
274
|
+
* Absent → the loop runs a turn's tool calls one at a time, which is the honest answer for a
|
|
275
|
+
* runner whose positions are assigned anywhere other than the call.
|
|
276
|
+
*/
|
|
277
|
+
parallel?<T>(tasks: readonly (() => Promise<T>)[]): Promise<SettledTask<T>[]>;
|
|
278
|
+
/**
|
|
279
|
+
* Does this run take the loop shape guarded by `id`? A runner replaying against recorded
|
|
280
|
+
* checkpoints answers `false` for a run that started before the shape changed, so that run keeps
|
|
281
|
+
* replaying the shape its history holds (`@adonis-agora/durable`'s `ctx.patched`, which consumes a
|
|
282
|
+
* position for a new run and gives it back to an old one). Absent → `true`: a runner that records
|
|
283
|
+
* no positions has no older shape to preserve.
|
|
284
|
+
*/
|
|
285
|
+
patched?(id: string): Promise<boolean>;
|
|
106
286
|
}
|
|
107
287
|
export declare class QuotaExceededError extends Error {
|
|
108
288
|
constructor();
|
|
109
289
|
}
|
|
290
|
+
/**
|
|
291
|
+
* How many agent→agent delegations deep a chain may go when the host names no ceiling.
|
|
292
|
+
*
|
|
293
|
+
* A backstop for a chain that is merely LONG. The cycle it would otherwise stand in for is detected
|
|
294
|
+
* directly — see {@link DEFAULT_MAX_AGENT_APPEARANCES}.
|
|
295
|
+
*
|
|
296
|
+
* WHEN IT ACTUALLY BINDS. At one appearance per agent a chain cannot be longer than the number of
|
|
297
|
+
* registered agents, so a deployment with fewer agents than this number never reaches it: the cycle
|
|
298
|
+
* guard always fires first. It starts mattering with a larger fleet than the ceiling, or once a host
|
|
299
|
+
* raises {@link AgentLoopDeps.maxAgentAppearances}, which is what lets a chain revisit an agent and
|
|
300
|
+
* therefore grow past the fleet's size.
|
|
301
|
+
*/
|
|
302
|
+
export declare const MAX_DELEGATION_DEPTH = 5;
|
|
303
|
+
/**
|
|
304
|
+
* How many times one agent may appear on a single delegation chain, when the host names no other
|
|
305
|
+
* number. Once: a chain that reaches an agent it has already passed through is going in circles.
|
|
306
|
+
*
|
|
307
|
+
* Override with {@link AgentLoopDeps.maxAgentAppearances} — a supervisor that genuinely hands work
|
|
308
|
+
* back to an earlier agent needs a larger number, and it is the count of APPEARANCES, so 2 admits
|
|
309
|
+
* exactly one return.
|
|
310
|
+
*/
|
|
311
|
+
export declare const DEFAULT_MAX_AGENT_APPEARANCES = 1;
|
|
312
|
+
/**
|
|
313
|
+
* The turn's tool list plus the built-ins the module offers — `ask`, `skill`. Appended from CONFIG
|
|
314
|
+
* rather than the registry, because neither is ever registered: see {@link AgentLoopDeps.ask} and
|
|
315
|
+
* {@link AgentLoopDeps.skills}.
|
|
316
|
+
*/
|
|
317
|
+
export declare function withBuiltInTools(args: {
|
|
318
|
+
tools: ToolDefinition[];
|
|
319
|
+
ask: boolean | undefined;
|
|
320
|
+
skills: boolean;
|
|
321
|
+
memory: boolean;
|
|
322
|
+
}): ToolDefinition[];
|
|
323
|
+
/** What a turn answered with: the assistant text, plus the validated `outputSchema` value if any. */
|
|
324
|
+
export interface AgentLoopResult<TOutput = unknown> {
|
|
325
|
+
text: string;
|
|
326
|
+
/** Present only when {@link AgentLoopDeps.outputSchema} was set — the validated structured answer. */
|
|
327
|
+
object?: TOutput;
|
|
328
|
+
}
|
|
110
329
|
/**
|
|
111
330
|
* The provider-agnostic agent turn, reused by both the inline and durable runners.
|
|
112
331
|
* It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
|
|
113
332
|
* hooks that make the same loop body either in-process or a replay-safe durable workflow.
|
|
114
333
|
*/
|
|
115
|
-
export declare function runAgentLoop(deps: AgentLoopDeps
|
|
116
|
-
text: string;
|
|
117
|
-
}>;
|
|
334
|
+
export declare function runAgentLoop<TOutput = unknown>(deps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
|
|
118
335
|
//# sourceMappingURL=agent-loop.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../src/agent-loop.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../src/agent-loop.ts"],"names":[],"mappings":"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"}
|