@jangts/agent-core 0.3.6 → 0.5.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 +20 -0
- package/README.md +5 -5
- package/development/docs/README.en.md +2 -2
- package/development/docs/acceptance.en.md +2 -2
- package/development/docs/agent-development.en.md +1 -1
- package/development/docs/api/README.en.md +4 -2
- package/development/docs/api/README.md +2 -0
- package/development/docs/api/configuration-in-workflow.en.md +403 -0
- package/development/docs/api/configuration-in-workflow.md +403 -0
- package/development/docs/api/core.en.md +7 -7
- package/development/docs/api/core.md +6 -6
- package/development/docs/api/decorators.en.md +20 -0
- package/development/docs/api/decorators.md +20 -0
- package/development/docs/api/examples.en.md +1 -1
- package/development/docs/api/examples.md +1 -1
- package/development/docs/api/kits.en.md +22 -4
- package/development/docs/api/kits.md +22 -4
- package/development/docs/api/knowledge-answering.en.md +4 -1
- package/development/docs/api/knowledge-answering.md +4 -1
- package/development/docs/api/mock.en.md +2 -0
- package/development/docs/api/mock.md +2 -0
- package/development/docs/api/reference.en.md +508 -410
- package/development/docs/api/reference.md +508 -410
- package/development/docs/api/support.en.md +55 -9
- package/development/docs/api/support.md +53 -7
- package/development/docs/api/types.en.md +35 -1
- package/development/docs/api/types.md +43 -0
- package/development/docs/basic-usage.en.md +1 -1
- package/development/docs/basic-usage.md +1 -1
- package/development/docs/create-app.en.md +1 -1
- package/development/docs/examples/registration/associated.mjs +8 -0
- package/development/docs/examples/registration/independent.mjs +20 -0
- package/development/docs/examples/registration/protocol.mjs +48 -0
- package/development/docs/examples/registration/run.mjs +47 -0
- package/development/docs/examples/registration/tools.mjs +75 -0
- package/development/docs/examples/registration/workflow.mjs +109 -0
- package/development/docs/flows/knowledge-maintenance.en.md +1 -1
- package/development/docs/materials.en.md +1 -1
- package/development/docs/mechanisms.en.md +2 -2
- package/development/docs/mechanisms.md +1 -1
- package/development/docs/operations.en.md +1 -1
- package/development/docs/records.en.md +1 -1
- package/development/docs/registration.en.md +4 -4
- package/development/docs/registration.md +2 -2
- package/development/skills/agent-core-app/SKILL.md +4 -4
- package/development/skills/agent-core-app/templates/node-ts/README.md.tpl +1 -1
- package/development/skills/agent-core-app/templates/node-ts/src/catalog.ts.tpl +2 -2
- package/development/skills/agent-core-app/templates/node-ts/test/app.test.mjs.tpl +1 -1
- package/dist/cjs/capabilities/index.js +5 -12
- package/dist/cjs/capabilities/model.js +56 -12
- package/dist/cjs/capabilities/tool-conditions.js +65 -0
- package/dist/cjs/capabilities/tool-runtime.js +10 -3
- package/dist/cjs/context/audit.js +5 -8
- package/dist/cjs/context/index.js +3 -4
- package/dist/cjs/index.js +21 -17
- package/dist/cjs/kits/answering/tasks.js +5 -5
- package/dist/cjs/kits/domains/catalog.js +113 -0
- package/dist/cjs/kits/domains/index.js +20 -0
- package/dist/cjs/kits/{intents → domains}/registry.js +77 -31
- package/dist/cjs/kits/{intents → domains}/scopes.js +21 -21
- package/dist/cjs/kits/index.js +14 -13
- package/dist/cjs/kits/presentation/formats.js +110 -0
- package/dist/cjs/kits/presentation/index.js +10 -5
- package/dist/cjs/kits/reflection.js +2 -2
- package/dist/cjs/kits/text-blocks.js +101 -0
- package/dist/cjs/kits/tools.js +246 -158
- package/dist/cjs/model/index.js +2 -6
- package/dist/cjs/model/interactions/calls.js +61 -0
- package/dist/cjs/model/interactions/json-object.js +11 -11
- package/dist/cjs/model/interactions/native-functions.js +17 -23
- package/dist/cjs/model/message-diagnostics.js +13 -3
- package/dist/cjs/model/options.js +2 -0
- package/dist/cjs/model/preparation.js +39 -6
- package/dist/cjs/model/runner.js +14 -0
- package/dist/cjs/model/selection-transport.js +4 -4
- package/dist/cjs/model/token-budget.js +3 -0
- package/dist/cjs/model/transports.js +3 -2
- package/dist/cjs/structs/index.js +7 -6
- package/dist/cjs/structs/kits/presentation/formats.js +2 -0
- package/dist/cjs/structs/kits/text-blocks.js +11 -0
- package/dist/cjs/structs/model/session.js +11 -0
- package/dist/cjs/structs/support/associations.js +2 -0
- package/dist/cjs/support/associations.js +79 -0
- package/dist/cjs/support/context/snapshot.js +11 -1
- package/dist/cjs/support/decorators/index.js +45 -3
- package/dist/cjs/support/index.js +1 -0
- package/dist/cjs/support/model/capabilities.js +35 -5
- package/dist/cjs/support/model/chat-completions.js +11 -2
- package/dist/cjs/support/model/completion/calls.js +10 -56
- package/dist/cjs/support/model/preview-rules.js +11 -11
- package/dist/cjs/support/model/reply-preview.js +3 -3
- package/dist/cjs/support/model/session.js +152 -0
- package/dist/cjs/support/model/stage-transport.js +8 -8
- package/dist/cjs/support/model/transports.js +5 -2
- package/dist/cjs/support/tools.js +42 -17
- package/dist/esm/capabilities/index.d.ts +5 -10
- package/dist/esm/capabilities/index.js +5 -9
- package/dist/esm/capabilities/model.d.ts +17 -13
- package/dist/esm/capabilities/model.js +54 -10
- package/dist/esm/capabilities/tool-conditions.d.ts +9 -0
- package/dist/esm/capabilities/tool-conditions.js +59 -0
- package/dist/esm/capabilities/tool-runtime.js +10 -3
- package/dist/esm/capabilities/tools.d.ts +3 -3
- package/dist/esm/context/audit.js +5 -8
- package/dist/esm/context/index.d.ts +3 -4
- package/dist/esm/context/index.js +3 -4
- package/dist/esm/index.d.ts +19 -13
- package/dist/esm/index.js +18 -15
- package/dist/esm/kits/answering/tasks.d.ts +6 -6
- package/dist/esm/kits/answering/tasks.js +5 -5
- package/dist/esm/kits/domains/catalog.d.ts +42 -0
- package/dist/esm/kits/domains/catalog.js +110 -0
- package/dist/esm/kits/domains/index.d.ts +4 -0
- package/dist/esm/kits/domains/index.js +4 -0
- package/dist/esm/kits/domains/registry.d.ts +100 -0
- package/dist/esm/kits/{intents → domains}/registry.js +77 -31
- package/dist/esm/kits/{intents → domains}/scopes.d.ts +18 -18
- package/dist/esm/kits/{intents → domains}/scopes.js +21 -21
- package/dist/esm/kits/index.d.ts +6 -5
- package/dist/esm/kits/index.js +6 -5
- package/dist/esm/kits/presentation/formats.d.ts +42 -0
- package/dist/esm/kits/presentation/formats.js +105 -0
- package/dist/esm/kits/presentation/index.d.ts +14 -5
- package/dist/esm/kits/presentation/index.js +10 -5
- package/dist/esm/kits/reflection.js +3 -3
- package/dist/esm/kits/text-blocks.d.ts +24 -0
- package/dist/esm/kits/text-blocks.js +97 -0
- package/dist/esm/kits/tools.d.ts +69 -52
- package/dist/esm/kits/tools.js +246 -158
- package/dist/esm/model/index.d.ts +2 -6
- package/dist/esm/model/index.js +2 -6
- package/dist/esm/model/interactions/calls.d.ts +40 -0
- package/dist/esm/model/interactions/calls.js +58 -0
- package/dist/esm/model/interactions/json-object.js +11 -11
- package/dist/esm/model/interactions/native-functions.js +17 -23
- package/dist/esm/model/message-diagnostics.d.ts +6 -5
- package/dist/esm/model/message-diagnostics.js +13 -3
- package/dist/esm/model/options.js +2 -0
- package/dist/esm/model/preparation.js +39 -6
- package/dist/esm/model/runner.js +14 -0
- package/dist/esm/model/selection-transport.js +4 -4
- package/dist/esm/model/token-budget.js +3 -0
- package/dist/esm/model/transports.d.ts +2 -1
- package/dist/esm/model/transports.js +3 -2
- package/dist/esm/structs/capabilities/invocation.d.ts +1 -1
- package/dist/esm/structs/capabilities/model.d.ts +42 -11
- package/dist/esm/structs/capabilities/tools.d.ts +9 -4
- package/dist/esm/structs/common.d.ts +1 -1
- package/dist/esm/structs/index.d.ts +7 -6
- package/dist/esm/structs/index.js +7 -6
- package/dist/esm/structs/kits/answering/tasks.d.ts +2 -2
- package/dist/esm/structs/kits/{intents → domains}/catalog.d.ts +20 -20
- package/dist/esm/structs/kits/{intents → domains}/registry.d.ts +24 -21
- package/dist/esm/structs/kits/{intents → domains}/scopes.d.ts +9 -9
- package/dist/esm/structs/kits/presentation/formats.d.ts +42 -0
- package/dist/esm/structs/kits/presentation/formats.js +1 -0
- package/dist/esm/structs/kits/text-blocks.d.ts +25 -0
- package/dist/esm/structs/kits/text-blocks.js +10 -0
- package/dist/esm/structs/kits/tools.d.ts +82 -83
- package/dist/esm/structs/model/interactions.d.ts +18 -11
- package/dist/esm/structs/model/messages.d.ts +34 -2
- package/dist/esm/structs/model/runtime.d.ts +7 -0
- package/dist/esm/structs/model/session.d.ts +29 -0
- package/dist/esm/structs/model/session.js +10 -0
- package/dist/esm/structs/support/associations.d.ts +22 -0
- package/dist/esm/structs/support/associations.js +1 -0
- package/dist/esm/structs/support/model/interactions.d.ts +2 -2
- package/dist/esm/structs/support/model/messages.d.ts +6 -13
- package/dist/esm/structs/support/tools.d.ts +23 -23
- package/dist/esm/support/associations.d.ts +26 -0
- package/dist/esm/support/associations.js +76 -0
- package/dist/esm/support/context/snapshot.js +11 -1
- package/dist/esm/support/decorators/index.d.ts +13 -2
- package/dist/esm/support/decorators/index.js +40 -3
- package/dist/esm/support/decorators/pool.d.ts +6 -5
- package/dist/esm/support/decorators/types.d.ts +3 -1
- package/dist/esm/support/index.d.ts +1 -0
- package/dist/esm/support/index.js +1 -0
- package/dist/esm/support/model/capabilities.d.ts +8 -3
- package/dist/esm/support/model/capabilities.js +35 -5
- package/dist/esm/support/model/chat-completions.js +11 -2
- package/dist/esm/support/model/completion/calls.d.ts +6 -34
- package/dist/esm/support/model/completion/calls.js +8 -55
- package/dist/esm/support/model/index.d.ts +1 -1
- package/dist/esm/support/model/preview-rules.d.ts +13 -8
- package/dist/esm/support/model/preview-rules.js +11 -11
- package/dist/esm/support/model/reply-preview.d.ts +2 -2
- package/dist/esm/support/model/reply-preview.js +3 -3
- package/dist/esm/support/model/session.d.ts +61 -0
- package/dist/esm/support/model/session.js +148 -0
- package/dist/esm/support/model/stage-transport.d.ts +1 -1
- package/dist/esm/support/model/stage-transport.js +9 -9
- package/dist/esm/support/model/transports.d.ts +2 -0
- package/dist/esm/support/model/transports.js +2 -1
- package/dist/esm/support/tools.d.ts +11 -3
- package/dist/esm/support/tools.js +43 -18
- package/dist/esm/utils/catalog.d.ts +1 -1
- package/package.json +20 -6
- package/dist/cjs/execution/index.js +0 -30
- package/dist/cjs/kits/intents/catalog.js +0 -82
- package/dist/cjs/kits/intents/index.js +0 -35
- package/dist/esm/execution/index.d.ts +0 -11
- package/dist/esm/execution/index.js +0 -11
- package/dist/esm/kits/intents/catalog.d.ts +0 -39
- package/dist/esm/kits/intents/catalog.js +0 -79
- package/dist/esm/kits/intents/index.d.ts +0 -22
- package/dist/esm/kits/intents/index.js +0 -18
- package/dist/esm/kits/intents/registry.d.ts +0 -88
- /package/dist/cjs/structs/kits/{intents → domains}/catalog.js +0 -0
- /package/dist/cjs/structs/kits/{intents → domains}/registry.js +0 -0
- /package/dist/cjs/structs/kits/{intents → domains}/scopes.js +0 -0
- /package/dist/esm/structs/kits/{intents → domains}/catalog.js +0 -0
- /package/dist/esm/structs/kits/{intents → domains}/registry.js +0 -0
- /package/dist/esm/structs/kits/{intents → domains}/scopes.js +0 -0
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* registry binds an App context, validates input/output at the boundary and produces receipts, so
|
|
6
6
|
* individual tools never handle transportation, budget accounting or event emission.
|
|
7
7
|
*
|
|
8
|
-
* Exports: `ToolDefinition`, `ToolExecutionContext`, `
|
|
8
|
+
* Exports: `ToolDefinition`, `ToolExecutionContext`, `ErasedTool`, `RegisteredTool`,
|
|
9
9
|
* `ToolExecutionEvent`, `ToolRegistryPorts`, `ToolInvocationRequest`, `ToolRegistryOptions`.
|
|
10
10
|
*/
|
|
11
11
|
import type { InvocationMetadata } from '../invocation.js';
|
|
@@ -13,8 +13,9 @@ import type { ExecutionContext, MaybePromise, OperationContext, SchemaAdapter }
|
|
|
13
13
|
import type { DiagnosticContext } from '../diagnostics.js';
|
|
14
14
|
import type { RegistrationProjection } from '../../utils/registration.js';
|
|
15
15
|
import type { NodeReportingContext } from '../debug.js';
|
|
16
|
+
import type { ModelTool, ToolProposal } from './model.js';
|
|
16
17
|
/** One registered tool, typed by its input, output, host context and id literal. */
|
|
17
|
-
export interface
|
|
18
|
+
export interface ExecutableTool<Input = unknown, Output = unknown, App = unknown, Id extends string = string> extends ModelTool<Input, ToolProposal, App> {
|
|
18
19
|
/** Stable id; also the name the model calls. */
|
|
19
20
|
readonly id: Id;
|
|
20
21
|
/** Declared grouping used by registries and documentation; not an authorization boundary. */
|
|
@@ -32,6 +33,10 @@ export interface ToolDefinition<Input = unknown, Output = unknown, App = unknown
|
|
|
32
33
|
/** Validates untrusted output (for example a cached replay) before it is returned. */
|
|
33
34
|
parseOutput(value: unknown): Output;
|
|
34
35
|
}
|
|
36
|
+
/** Configuration form; Support supplies the identity resolver when omitted. */
|
|
37
|
+
export type ToolDefinition<Input = unknown, Output = unknown, App = unknown, Id extends string = string> = Omit<ExecutableTool<Input, Output, App, Id>, 'resolve'> & {
|
|
38
|
+
readonly resolve?: ExecutableTool<Input, Output, App, Id>['resolve'];
|
|
39
|
+
};
|
|
35
40
|
/** Execution facts handed to a tool for one invocation. */
|
|
36
41
|
export interface ToolExecutionContext extends ExecutionContext, NodeReportingContext {
|
|
37
42
|
/** Delegate bound by Core to this actual invocation. */
|
|
@@ -46,7 +51,7 @@ export interface ToolExecutionContext extends ExecutionContext, NodeReportingCon
|
|
|
46
51
|
readonly signal: AbortSignal;
|
|
47
52
|
}
|
|
48
53
|
/** Type-erased tool shape the registry executes after parsing at the boundary. */
|
|
49
|
-
export interface
|
|
54
|
+
export interface ErasedTool {
|
|
50
55
|
readonly id: string;
|
|
51
56
|
readonly kind: string;
|
|
52
57
|
/** Optional here because the erased view does not require model-facing prose. */
|
|
@@ -57,7 +62,7 @@ export interface ExecutableTool {
|
|
|
57
62
|
execute(input: unknown, context: ToolExecutionContext): unknown;
|
|
58
63
|
}
|
|
59
64
|
/** Registered snapshot: public data is retained, implementation helpers are not a contract. */
|
|
60
|
-
export type RegisteredTool<Tool extends
|
|
65
|
+
export type RegisteredTool<Tool extends ErasedTool = ErasedTool> = RegistrationProjection<Tool, ErasedTool>;
|
|
61
66
|
/** Fact emitted when one tool call settles, correlated by `invocationId`. */
|
|
62
67
|
export interface ToolExecutionEvent<Kind extends string = string> extends InvocationMetadata {
|
|
63
68
|
toolId: string;
|
|
@@ -107,7 +107,7 @@ export interface ExecutionContext {
|
|
|
107
107
|
* it as opaque and must not depend on application-specific fields.
|
|
108
108
|
*/
|
|
109
109
|
export interface OperationContext<App = unknown> extends ExecutionContext {
|
|
110
|
-
readonly app: Readonly<App>;
|
|
110
|
+
readonly app: unknown extends App ? App : Readonly<App>;
|
|
111
111
|
}
|
|
112
112
|
/**
|
|
113
113
|
* One search result.
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
* Public entry of the structs layer.
|
|
3
3
|
*
|
|
4
4
|
* Structs are the shape-only half of agent-core: declarations and frozen constant catalogs that the
|
|
5
|
-
* runtime modules (`
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* runtime modules (`tools`, `context`, `execution`, `model`, `kits`, `support`) both implement and
|
|
6
|
+
* consume. Runtime classes declared here only describe shape or initialize fields, so importing this
|
|
7
|
+
* barrel never starts execution.
|
|
8
8
|
*
|
|
9
9
|
* Exports: a curated re-export of the shared vocabulary, error classes, diagnostics/event
|
|
10
10
|
* envelopes, model and workflow contracts, and the optional Kit protocol definitions.
|
|
@@ -19,6 +19,7 @@ export * from './model/interactions.js';
|
|
|
19
19
|
export * from './context/journal.js';
|
|
20
20
|
export * from './support/transport/json.js';
|
|
21
21
|
export * from './model/messages.js';
|
|
22
|
+
export * from './model/session.js';
|
|
22
23
|
export * from './model/runtime.js';
|
|
23
24
|
export * from './support/model/provider.js';
|
|
24
25
|
export * from './kits/interaction.js';
|
|
@@ -32,10 +33,10 @@ export * from './kits/evidence.js';
|
|
|
32
33
|
export * from './kits/presentation/templates.js';
|
|
33
34
|
export * from './kits/retrieval.js';
|
|
34
35
|
export * from './kits/text-skills.js';
|
|
35
|
-
export * from './kits/
|
|
36
|
-
export * from './kits/
|
|
36
|
+
export * from './kits/domains/registry.js';
|
|
37
|
+
export * from './kits/domains/scopes.js';
|
|
37
38
|
export * from './kits/tools.js';
|
|
38
|
-
export * from './kits/
|
|
39
|
+
export * from './kits/domains/catalog.js';
|
|
39
40
|
export * from './support/registration.js';
|
|
40
41
|
export * from './diagnostics.js';
|
|
41
42
|
export * from './support/context.js';
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
* Public entry of the structs layer.
|
|
3
3
|
*
|
|
4
4
|
* Structs are the shape-only half of agent-core: declarations and frozen constant catalogs that the
|
|
5
|
-
* runtime modules (`
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* runtime modules (`tools`, `context`, `execution`, `model`, `kits`, `support`) both implement and
|
|
6
|
+
* consume. Runtime classes declared here only describe shape or initialize fields, so importing this
|
|
7
|
+
* barrel never starts execution.
|
|
8
8
|
*
|
|
9
9
|
* Exports: a curated re-export of the shared vocabulary, error classes, diagnostics/event
|
|
10
10
|
* envelopes, model and workflow contracts, and the optional Kit protocol definitions.
|
|
@@ -19,6 +19,7 @@ export * from './model/interactions.js';
|
|
|
19
19
|
export * from './context/journal.js';
|
|
20
20
|
export * from './support/transport/json.js';
|
|
21
21
|
export * from './model/messages.js';
|
|
22
|
+
export * from './model/session.js';
|
|
22
23
|
export * from './model/runtime.js';
|
|
23
24
|
export * from './support/model/provider.js';
|
|
24
25
|
export * from './kits/interaction.js';
|
|
@@ -32,10 +33,10 @@ export * from './kits/evidence.js';
|
|
|
32
33
|
export * from './kits/presentation/templates.js';
|
|
33
34
|
export * from './kits/retrieval.js';
|
|
34
35
|
export * from './kits/text-skills.js';
|
|
35
|
-
export * from './kits/
|
|
36
|
-
export * from './kits/
|
|
36
|
+
export * from './kits/domains/registry.js';
|
|
37
|
+
export * from './kits/domains/scopes.js';
|
|
37
38
|
export * from './kits/tools.js';
|
|
38
|
-
export * from './kits/
|
|
39
|
+
export * from './kits/domains/catalog.js';
|
|
39
40
|
export * from './support/registration.js';
|
|
40
41
|
export * from './diagnostics.js';
|
|
41
42
|
export * from './support/context.js';
|
|
@@ -16,8 +16,8 @@ export interface AnswerTaskDefinition<Input = unknown, Data = unknown> {
|
|
|
16
16
|
readonly readerId: string;
|
|
17
17
|
/** Output contract the answer must satisfy; must be registered. */
|
|
18
18
|
readonly outputId: string;
|
|
19
|
-
/**
|
|
20
|
-
readonly
|
|
19
|
+
/** Goals this task serves; non-empty. */
|
|
20
|
+
readonly goalIds: readonly string[];
|
|
21
21
|
/** Optional scope narrowing the task. */
|
|
22
22
|
readonly scopeId?: string;
|
|
23
23
|
/** Checks applied to the produced value; every id must be registered. */
|
|
@@ -1,26 +1,26 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Agent catalog contract for the
|
|
2
|
+
* Agent catalog contract for the Domain Tools Kit.
|
|
3
3
|
*
|
|
4
4
|
* Place in the package: an optional App-side projection that describes which intents, scopes and
|
|
5
5
|
* tools are available to one request. The ports read the App's real registries, so no parallel
|
|
6
6
|
* capability list exists; this module only declares what the catalog needs from them.
|
|
7
7
|
*
|
|
8
|
-
* Exports: `
|
|
8
|
+
* Exports: `CatalogGoal`, `CatalogScope`, `CatalogTask`, `CatalogTool`, `DescribedTool`,
|
|
9
9
|
* `AgentCatalogPorts`.
|
|
10
10
|
*/
|
|
11
|
-
/**
|
|
12
|
-
export interface
|
|
11
|
+
/** Goal as the catalog sees it: an id plus its declared delegates. */
|
|
12
|
+
export interface CatalogGoal<Id extends string = string> {
|
|
13
13
|
readonly id: Id;
|
|
14
|
-
readonly
|
|
14
|
+
readonly delegates: readonly string[];
|
|
15
15
|
}
|
|
16
16
|
/** Scope as the catalog sees it: an id plus the tools it may use. */
|
|
17
17
|
export interface CatalogScope {
|
|
18
18
|
readonly id: string;
|
|
19
19
|
readonly toolIds: readonly string[];
|
|
20
20
|
}
|
|
21
|
-
/** The
|
|
21
|
+
/** The goal currently accepted for the request, used to narrow the catalog. */
|
|
22
22
|
export interface CatalogTask<Id extends string = string> {
|
|
23
|
-
readonly
|
|
23
|
+
readonly goalId: Id;
|
|
24
24
|
/** Selected scope; `null` or `undefined` means a scope has not been chosen yet. */
|
|
25
25
|
readonly scopeId?: string | null;
|
|
26
26
|
}
|
|
@@ -28,12 +28,12 @@ export interface CatalogTask<Id extends string = string> {
|
|
|
28
28
|
export interface CatalogTool<App> {
|
|
29
29
|
readonly id: string;
|
|
30
30
|
/** Intent ids the tool serves, or `'all'` when it is always available. */
|
|
31
|
-
readonly
|
|
31
|
+
readonly goalIds: 'all' | readonly string[];
|
|
32
32
|
/** Returns whether the tool may run for this App state; absent means always available. */
|
|
33
|
-
|
|
34
|
-
/** Invocation
|
|
35
|
-
readonly
|
|
36
|
-
readonly
|
|
33
|
+
readonly active?: import('../../capabilities/model.js').ToolCondition<App>;
|
|
34
|
+
/** Invocation identity, when the tool participates in the lifecycle. */
|
|
35
|
+
readonly lifecycle?: {
|
|
36
|
+
readonly id?: string;
|
|
37
37
|
};
|
|
38
38
|
}
|
|
39
39
|
/** Model- or host-facing description of one tool. */
|
|
@@ -43,15 +43,15 @@ export interface DescribedTool {
|
|
|
43
43
|
readonly description: string;
|
|
44
44
|
readonly audience: string;
|
|
45
45
|
readonly effect: string;
|
|
46
|
-
readonly
|
|
46
|
+
readonly goalIds: readonly string[];
|
|
47
47
|
}
|
|
48
48
|
/** Ports the catalog reads from the App's registries. */
|
|
49
|
-
export interface AgentCatalogPorts<App, Id extends string, Intent extends
|
|
50
|
-
/** All registered
|
|
51
|
-
|
|
52
|
-
/** Registered
|
|
53
|
-
|
|
54
|
-
/** Registered scopes for the given
|
|
49
|
+
export interface AgentCatalogPorts<App, Id extends string, Intent extends CatalogGoal<Id>, Scope extends CatalogScope> {
|
|
50
|
+
/** All registered Tool ids, before availability filtering. */
|
|
51
|
+
goalIds(app: App): readonly Id[];
|
|
52
|
+
/** Registered domain Tools, optionally narrowed to `ids`. */
|
|
53
|
+
goals(ids?: readonly Id[]): readonly Intent[];
|
|
54
|
+
/** Registered scopes for the given Tool ids (all scopes when omitted). */
|
|
55
55
|
scopes(ids?: readonly Id[]): readonly Scope[];
|
|
56
56
|
/** When not `false`, the catalog is narrowed to `currentTask`; defaults to restriction on. */
|
|
57
57
|
readonly restrictToTask?: boolean;
|
|
@@ -60,7 +60,7 @@ export interface AgentCatalogPorts<App, Id extends string, Intent extends Catalo
|
|
|
60
60
|
readonly tools: {
|
|
61
61
|
values(): Iterable<CatalogTool<App>>;
|
|
62
62
|
has(id: string): boolean;
|
|
63
|
-
|
|
63
|
+
supportsGoal(id: Id, app: App): boolean;
|
|
64
64
|
/** Describes tools for an audience (for example `'model'`); must be synchronous. */
|
|
65
65
|
describe(audience?: string, app?: App): readonly DescribedTool[];
|
|
66
66
|
};
|
|
@@ -1,23 +1,24 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Domain Tool registry contract for the Domain Tools Kit.
|
|
3
3
|
*
|
|
4
|
-
* Place in the package: an optional App-side catalog of
|
|
5
|
-
*
|
|
4
|
+
* Place in the package: an optional App-side catalog of domain Tools. An intent names its allowed
|
|
5
|
+
* delegates and optional App-declared policies; the registry checks identity, allowed vocabulary,
|
|
6
6
|
* duplicate ids and sealing, while the meaning of each vocabulary value stays with the App.
|
|
7
7
|
*
|
|
8
|
-
* Exports: `
|
|
8
|
+
* Exports: `IntentTool`, `IntentPolicy`, `IntentDescription`, `IntentId`,
|
|
9
9
|
* `RegisteredIntent`.
|
|
10
10
|
*/
|
|
11
11
|
import type { BreakReason } from '../../utils/rules.js';
|
|
12
12
|
import type { RegistrationProjection } from '../../../utils/registration.js';
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
import type { ModelTool } from '../../capabilities/model.js';
|
|
14
|
+
/** One domain Tool. */
|
|
15
|
+
export interface IntentTool extends ModelTool<any, any> {
|
|
16
|
+
/** Unique Tool id, matched against the policy's `idPattern` when configured. */
|
|
16
17
|
id: string;
|
|
17
18
|
/** Non-blank model-facing description. */
|
|
18
19
|
description: string;
|
|
19
|
-
/**
|
|
20
|
-
|
|
20
|
+
/** Allowed delegate ids, retained in declaration order without imposing execution order; non-empty and unique. */
|
|
21
|
+
delegates?: readonly string[];
|
|
21
22
|
/** App-declared scope-mode name; validated against `policy.scopeModes` when that is set. */
|
|
22
23
|
scopePolicy?: string;
|
|
23
24
|
/** App-declared target-mode name; validated against `policy.targetModes` when that is set. */
|
|
@@ -31,9 +32,11 @@ export interface IntentDefinition {
|
|
|
31
32
|
/** App-declared handoff marker; validated against `policy.handoffValues` when that is set. */
|
|
32
33
|
preparedHandoff?: unknown;
|
|
33
34
|
}
|
|
35
|
+
/** Configuration form; object arguments and a Tool proposal are the registration defaults. */
|
|
36
|
+
export type IntentToolRegistration = Omit<IntentTool, 'inputSchema' | 'resolve'> & Partial<Pick<IntentTool, 'inputSchema' | 'resolve'>>;
|
|
34
37
|
/** Registration rules for one intent registry. */
|
|
35
|
-
export interface
|
|
36
|
-
/** Pattern every
|
|
38
|
+
export interface IntentPolicy<Definition extends IntentToolRegistration> {
|
|
39
|
+
/** Pattern every Tool id must match. */
|
|
37
40
|
readonly idPattern?: RegExp;
|
|
38
41
|
/** Allowed `scopePolicy` values; `undefined` accepts any value. */
|
|
39
42
|
readonly scopeModes?: readonly string[];
|
|
@@ -43,8 +46,8 @@ export interface IntentRegistryPolicy<Definition extends IntentDefinition> {
|
|
|
43
46
|
readonly contextTiers?: readonly string[];
|
|
44
47
|
/** Allowed `planIntent` values; `undefined` accepts any value. */
|
|
45
48
|
readonly actions?: readonly string[];
|
|
46
|
-
/** Allowed
|
|
47
|
-
readonly
|
|
49
|
+
/** Allowed delegate ids; `undefined` accepts any non-empty delegate. */
|
|
50
|
+
readonly delegates?: readonly string[];
|
|
48
51
|
/** Allowed `preparedHandoff` values; `undefined` accepts any value. */
|
|
49
52
|
readonly handoffValues?: readonly unknown[];
|
|
50
53
|
/** Extra App assertion, called after the built-in checks; must return void synchronously. */
|
|
@@ -54,24 +57,24 @@ export interface IntentRegistryPolicy<Definition extends IntentDefinition> {
|
|
|
54
57
|
readonly errors?: {
|
|
55
58
|
readonly sealed?: BreakReason;
|
|
56
59
|
readonly invalid?: BreakReason;
|
|
57
|
-
/** Builds the duplicate-id rejection; receives the
|
|
60
|
+
/** Builds the duplicate-id rejection; receives the Tool id. */
|
|
58
61
|
readonly duplicate?: (goal: string) => Error | string;
|
|
59
62
|
};
|
|
60
63
|
}
|
|
61
|
-
/** Registered
|
|
62
|
-
export type IntentDescription<Definition extends
|
|
63
|
-
|
|
64
|
+
/** Registered domain Tool with its delegates widened to the definition's delegate literals. */
|
|
65
|
+
export type IntentDescription<Definition extends IntentToolRegistration> = Omit<RegisteredIntent<Definition>, 'delegates'> & {
|
|
66
|
+
delegates: NonNullable<Definition['delegates']>[number][];
|
|
64
67
|
};
|
|
65
68
|
/** Union of the ids of a definition set, or `string` when it cannot be narrowed. */
|
|
66
69
|
export type IntentId<Definition> = Definition extends {
|
|
67
70
|
id: infer Id extends string;
|
|
68
71
|
} ? Id : string;
|
|
69
|
-
type RegisteredIntentLists<Definition extends
|
|
70
|
-
readonly [Key in keyof Pick<Definition, Extract<keyof Definition, '
|
|
72
|
+
type RegisteredIntentLists<Definition extends IntentToolRegistration> = {
|
|
73
|
+
readonly [Key in keyof Pick<Definition, Extract<keyof Definition, 'delegates' | 'auxiliaryActions'>>]: Readonly<Definition[Key]>;
|
|
71
74
|
};
|
|
72
75
|
/** Frozen registration view: list fields are frozen copies, helper methods are dropped. */
|
|
73
|
-
export type RegisteredIntent<Definition extends
|
|
76
|
+
export type RegisteredIntent<Definition extends IntentToolRegistration> = Readonly<Omit<RegistrationProjection<Definition, IntentTool>, 'delegates' | 'auxiliaryActions' | 'inputSchema' | 'resolve'> & ModelTool<any, any> & RegisteredIntentLists<Definition> & {
|
|
74
77
|
id: Definition['id'];
|
|
75
|
-
|
|
78
|
+
delegates: Readonly<NonNullable<Definition['delegates']>>;
|
|
76
79
|
}>;
|
|
77
80
|
export {};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Scope registry contract for the
|
|
2
|
+
* Scope registry contract for the Domain Tools Kit.
|
|
3
3
|
*
|
|
4
4
|
* Place in the package: an optional App-side catalog of scope definitions. A scope binds an intent
|
|
5
5
|
* to the sources and tools it may use; the registry validates identity, aliases, required bindings
|
|
@@ -19,8 +19,8 @@ export interface ScopeDefinition {
|
|
|
19
19
|
description: string;
|
|
20
20
|
/** Scope category; validated against `policy.categories` when that is set. */
|
|
21
21
|
category: string;
|
|
22
|
-
/**
|
|
23
|
-
|
|
22
|
+
/** Goals this scope serves; required when the policy sets `requireGoals`. */
|
|
23
|
+
goalIds?: readonly string[];
|
|
24
24
|
/** Referenced query scopes, resolved by the App. */
|
|
25
25
|
queryScopeIds?: readonly string[];
|
|
26
26
|
/** Referenced knowledge topics, resolved by the App. */
|
|
@@ -36,8 +36,8 @@ export interface ScopeDefinition {
|
|
|
36
36
|
}
|
|
37
37
|
/** Registration rules for one scope registry. */
|
|
38
38
|
export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
|
|
39
|
-
/** Require at least one
|
|
40
|
-
readonly
|
|
39
|
+
/** Require at least one Tool id per scope. */
|
|
40
|
+
readonly requireGoals?: boolean;
|
|
41
41
|
/** Require at least one query scope or knowledge topic per scope. */
|
|
42
42
|
readonly requireSources?: boolean;
|
|
43
43
|
/** Require at least one tool id per scope. */
|
|
@@ -49,7 +49,7 @@ export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
|
|
|
49
49
|
/** Extra App assertion, called after the built-in checks; must return void synchronously. */
|
|
50
50
|
readonly assertDefinition?: (definition: Definition) => void;
|
|
51
51
|
/** Replaces the default intent membership test; must return boolean synchronously. */
|
|
52
|
-
readonly
|
|
52
|
+
readonly acceptsTool?: (definition: Readonly<Definition>, goal: string) => boolean;
|
|
53
53
|
/** Diagnostic tags attached to registration rejections. */
|
|
54
54
|
readonly tags?: readonly string[];
|
|
55
55
|
readonly errors?: {
|
|
@@ -59,7 +59,7 @@ export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
|
|
|
59
59
|
}
|
|
60
60
|
/** Registered evidence entry: public data only, frozen by the registry. */
|
|
61
61
|
export type RegisteredScopeEvidence<Definition extends ScopeDefinition> = Readonly<RegistrationData<NonNullable<Definition['evidence']>[number]>>;
|
|
62
|
-
type ScopeListKey = '
|
|
62
|
+
type ScopeListKey = 'goalIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases';
|
|
63
63
|
type RegisteredScopeLists<Definition extends ScopeDefinition> = {
|
|
64
64
|
readonly [Key in ScopeListKey]: [NonNullable<Definition[Key]>] extends [never] ? readonly [] : NonNullable<Definition[Key]> extends readonly string[] ? Readonly<NonNullable<Definition[Key]>> : readonly string[];
|
|
65
65
|
};
|
|
@@ -74,8 +74,8 @@ export type RegisteredScope<Definition extends ScopeDefinition> = Readonly<Omit<
|
|
|
74
74
|
evidence: ScopeEvidenceList<Definition>;
|
|
75
75
|
}>;
|
|
76
76
|
/** Plain description with mutable arrays, for documentation and model-facing catalogs. */
|
|
77
|
-
export type ScopeDescription<Definition extends ScopeDefinition> = Omit<RegisteredScope<Definition>, '
|
|
78
|
-
|
|
77
|
+
export type ScopeDescription<Definition extends ScopeDefinition> = Omit<RegisteredScope<Definition>, 'goalIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases' | 'evidence'> & {
|
|
78
|
+
goalIds: string[];
|
|
79
79
|
queryScopeIds: string[];
|
|
80
80
|
knowledgeTopicIds: string[];
|
|
81
81
|
toolIds: string[];
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reply-format contract for the Presentation Kit.
|
|
3
|
+
*
|
|
4
|
+
* A format exists only where the App provides a template for the final reply. Replies without a
|
|
5
|
+
* resolved format have no output-format requirement, so callers skip these checks instead of
|
|
6
|
+
* re-asking the model.
|
|
7
|
+
*
|
|
8
|
+
* Exports: `ReplyFormatCheck`, `ReplyFormatDefinition`, `CompiledReplyFormat`, `ReplyFormatOptions`.
|
|
9
|
+
*/
|
|
10
|
+
/** One check a template declares, evaluated against the rendered bubbles. */
|
|
11
|
+
export interface ReplyFormatCheck {
|
|
12
|
+
/** Stable check id referenced by formats. */
|
|
13
|
+
readonly id: string;
|
|
14
|
+
/** Human-readable statement of the template requirement. */
|
|
15
|
+
readonly description: string;
|
|
16
|
+
/** Returns whether the reply satisfies this requirement. */
|
|
17
|
+
readonly accepts: (bubbles: readonly string[]) => boolean;
|
|
18
|
+
}
|
|
19
|
+
/** A template-bound reply format, matched against per-turn facts. */
|
|
20
|
+
export interface ReplyFormatDefinition<Context = unknown> {
|
|
21
|
+
/** Stable format id. */
|
|
22
|
+
readonly id: string;
|
|
23
|
+
/** Human-readable statement of the template. */
|
|
24
|
+
readonly description: string;
|
|
25
|
+
/** Check ids this template requires. */
|
|
26
|
+
readonly checks: readonly string[];
|
|
27
|
+
/** Whether the current turn uses this template. */
|
|
28
|
+
readonly when: (context: Context) => boolean;
|
|
29
|
+
}
|
|
30
|
+
/** A resolved format with its checks bound; callers only inspect replies using it. */
|
|
31
|
+
export interface CompiledReplyFormat {
|
|
32
|
+
readonly id: string;
|
|
33
|
+
readonly description: string;
|
|
34
|
+
readonly checks: readonly string[];
|
|
35
|
+
/** Checks the reply fails; empty means the template format is satisfied. */
|
|
36
|
+
readonly inspect: (bubbles: readonly string[]) => readonly ReplyFormatCheck[];
|
|
37
|
+
}
|
|
38
|
+
/** Declaration input for `defineReplyFormats`. */
|
|
39
|
+
export interface ReplyFormatOptions<Context = unknown> {
|
|
40
|
+
readonly formats: readonly ReplyFormatDefinition<Context>[];
|
|
41
|
+
readonly checks: readonly ReplyFormatCheck[];
|
|
42
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Text block contract for the Text Blocks Kit.
|
|
3
|
+
*
|
|
4
|
+
* Place in the package: an optional App-side helper for splitting long plain text into
|
|
5
|
+
* structure-aware blocks before paging or retrieval. File reading, paging, search, storage
|
|
6
|
+
* and prompt wording stay with the App.
|
|
7
|
+
*
|
|
8
|
+
* Exports: `TextBlock`, `TextBlockOptions`.
|
|
9
|
+
*/
|
|
10
|
+
/** One structure-aware block of a long text. */
|
|
11
|
+
export interface TextBlock {
|
|
12
|
+
/** One-based position in source order; stable for a given text and target size. */
|
|
13
|
+
readonly number: number;
|
|
14
|
+
/** Exact source substring, including its own line endings. */
|
|
15
|
+
readonly text: string;
|
|
16
|
+
/** Start offset in UTF-16 code units. */
|
|
17
|
+
readonly start: number;
|
|
18
|
+
/** End offset (exclusive) in UTF-16 code units; `end - start === text.length`. */
|
|
19
|
+
readonly end: number;
|
|
20
|
+
}
|
|
21
|
+
/** Splitting options. */
|
|
22
|
+
export interface TextBlockOptions {
|
|
23
|
+
/** Target block size in characters; only a single over-long line may exceed it. */
|
|
24
|
+
readonly targetChars: number;
|
|
25
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Text block contract for the Text Blocks Kit.
|
|
3
|
+
*
|
|
4
|
+
* Place in the package: an optional App-side helper for splitting long plain text into
|
|
5
|
+
* structure-aware blocks before paging or retrieval. File reading, paging, search, storage
|
|
6
|
+
* and prompt wording stay with the App.
|
|
7
|
+
*
|
|
8
|
+
* Exports: `TextBlock`, `TextBlockOptions`.
|
|
9
|
+
*/
|
|
10
|
+
export {};
|