ScopeRegistry

KIT · class · Runtime value

Generic scope relationships; categories, intent policy and extra fields belong to the host.

A scope is addressable by its id or by any of its aliases; aliases resolve to the declaring scope, and a name may be claimed only once across both namespaces.

Import

TypeScript

import { ScopeRegistry } from '@jangts/agent-core/kits/domains';

JavaScript

import { ScopeRegistry } from '@jangts/agent-core/kits/domains';

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/kits/domains, @jangts/agent-core/kits.

Definition

class ScopeRegistry<Definition>

Type parameters

Type parameter	Constraint	Default type
Definition	ScopeDefinition	ScopeDefinition

Constructor

new ScopeRegistry<Definition extends ScopeDefinition = ScopeDefinition>(policy?: ScopeRegistryPolicy<Definition>): ScopeRegistry<Definition>

Parameter	Type	Passing	Description
policy	ScopeRegistryPolicy<Definition>	Optional	—

Fields of policy

Field	Type	Required	Description
requireGoals	boolean | undefined	Optional	Read-only. Require at least one Tool id per scope.
requireSources	boolean | undefined	Optional	Read-only. Require at least one query scope or knowledge topic per scope.
requireTools	boolean | undefined	Optional	Read-only. Require at least one tool id per scope.
idPattern	RegExp | undefined	Optional	Read-only. Pattern every id and alias must match.
categories	readonly string[] | undefined	Optional	Read-only. Allowed category values; undefined accepts any value.
assertDefinition	((definition: Definition) => void) | undefined	Optional	Read-only. Extra App assertion, called after the built-in checks; must return void synchronously.
acceptsTool	((definition: Readonly<Definition>, goal: string) => boolean) | undefined	Optional	Read-only. Replaces the default intent membership test; must return boolean synchronously.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to registration rejections.
errors	{ readonly sealed?: BreakReason; readonly invalid?: BreakReason; } | undefined	Optional	Read-only. See the type definition and usage context.

Returns: ScopeRegistry<Definition>.

Instance properties

Field	Type	Required	Description
definitions	readonly Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>[]	Required	Read-only. Registered scopes in registration order.

Member index

Member	Purpose
create	Static. Create and seal a complete scope catalog in one call.
register	Validate, freeze and add one scope together with its aliases. Every name is checked for conflicts before any of them is stored, so a rejected scope leaves no partial alias entry behind.
registerAll	Register every scope in iteration order.
seal	Finalize the registry; no registration is accepted afterwards.
ids	Registered scope ids in registration order; aliases are not included.
values	Iterate the registered scopes.
entries	Iterate [id, scope] pairs.
require	Registered scope for an id or alias.
normalize	Resolve an alias to its scope id; unknown names are returned unchanged.
get	Registered scope for an id or alias, or undefined for a null/unknown name.
has	Whether the name resolves to a registered scope.
acceptsTool	Whether a scope accepts an intent. The App may override the declared goalIds through acceptsTool; without an override the membership check applies.
acceptsQuery	Whether the scope declares this query scope; a null scope accepts nothing.
is	Whether the scope belongs to the given App category.
queryScopeIds	Every query scope declared by any registered scope, deduplicated.
topics	Knowledge topic ids of one scope; copied so callers cannot mutate the registry.
evidence	Evidence declarations of one scope; copied so callers cannot mutate the registry.
contextTier	Declared context tier of one scope, if any.
describe	Copy the scopes that accept at least one of the given goals.

Member details

create

Static member.

Create and seal a complete scope catalog in one call.

ScopeRegistry.create<Definition extends ScopeDefinition>(definitions: Iterable<Definition>, policy?: ScopeRegistryPolicy<Definition>): ScopeRegistry<Definition>

Create and seal a complete catalog; use the constructor for incremental installation.

Type parameter	Constraint	Default type
Definition	ScopeDefinition	—

Parameter	Type	Passing	Description
definitions	Iterable<Definition>	Required	—
policy	ScopeRegistryPolicy<Definition>	Optional	—

Fields of policy

Field	Type	Required	Description
requireGoals	boolean | undefined	Optional	Read-only. Require at least one Tool id per scope.
requireSources	boolean | undefined	Optional	Read-only. Require at least one query scope or knowledge topic per scope.
requireTools	boolean | undefined	Optional	Read-only. Require at least one tool id per scope.
idPattern	RegExp | undefined	Optional	Read-only. Pattern every id and alias must match.
categories	readonly string[] | undefined	Optional	Read-only. Allowed category values; undefined accepts any value.
assertDefinition	((definition: Definition) => void) | undefined	Optional	Read-only. Extra App assertion, called after the built-in checks; must return void synchronously.
acceptsTool	((definition: Readonly<Definition>, goal: string) => boolean) | undefined	Optional	Read-only. Replaces the default intent membership test; must return boolean synchronously.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to registration rejections.
errors	{ readonly sealed?: BreakReason; readonly invalid?: BreakReason; } | undefined	Optional	Read-only. See the type definition and usage context.

Returns: ScopeRegistry<Definition>.

register

Instance method.

Validate, freeze and add one scope together with its aliases.

Every name is checked for conflicts before any of them is stored, so a rejected scope leaves no partial alias entry behind.

register(input: Definition): ScopeRegistry<Definition>

Validate, freeze and add one scope together with its aliases.

Every name is checked for conflicts before any of them is stored, so a rejected scope leaves no partial alias entry behind.

Parameter	Type	Passing	Description
input	Definition	Required	—

Returns: ScopeRegistry<Definition>.

registerAll

Instance method.

Register every scope in iteration order.

registerAll(definitions: Iterable<Definition>): ScopeRegistry<Definition>

Register every scope in iteration order.

Parameter	Type	Passing	Description
definitions	Iterable<Definition>	Required	—

Returns: ScopeRegistry<Definition>.

seal

Instance method.

Finalize the registry; no registration is accepted afterwards.

seal(): ScopeRegistry<Definition>

Finalize the registry; no registration is accepted afterwards.

No call parameters.

Returns: ScopeRegistry<Definition>.

ids

Instance method.

Registered scope ids in registration order; aliases are not included.

ids(): readonly string[]

Registered scope ids in registration order; aliases are not included.

No call parameters.

Returns: readonly string[].

values

Instance method.

Iterate the registered scopes.

values(): MapIterator<Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>>

Iterate the registered scopes.

No call parameters.

Returns: MapIterator<Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>>.

entries

Instance method.

Iterate [id, scope] pairs.

entries(): MapIterator<[string, Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>]>

Iterate [id, scope] pairs.

No call parameters.

Returns: MapIterator<[string, Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>]>.

require

Instance method.

Registered scope for an id or alias.

require(id: string): Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>

Registered scope for an id or alias.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>.

Return value structure

Field	Type	Required	Description
id	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["id"]	Required	Unique scope id, matched against the policy's idPattern when configured.
description	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["description"]	Required	Non-blank description.
category	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["category"]	Required	Scope category; validated against policy.categories when that is set.
contextTier	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["contextTier"] | undefined	Optional	App-declared context tier, passed through for the App's own policy.
evidence	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["evidence"]	Required	See the type definition and usage context.

normalize

Instance method.

Resolve an alias to its scope id; unknown names are returned unchanged.

normalize(scope: string): string

Resolve an alias to its scope id; unknown names are returned unchanged.

Parameter	Type	Passing	Description
scope	string	Required	—

Returns: string.

get

Instance method.

Registered scope for an id or alias, or undefined for a null/unknown name.

get(scope?: string | null): RegisteredScope<Definition> | undefined

Registered scope for an id or alias, or undefined for a null/unknown name.

Parameter	Type	Passing	Description
scope	string | null | undefined	Optional	—

Returns: Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["id"]	Required	Unique scope id, matched against the policy's idPattern when configured.
description	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["description"]	Required	Non-blank description.
category	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["category"]	Required	Scope category; validated against policy.categories when that is set.
contextTier	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["contextTier"] | undefined	Optional	App-declared context tier, passed through for the App's own policy.
evidence	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["evidence"]	Required	See the type definition and usage context.

has

Instance method.

Whether the name resolves to a registered scope.

has(scope?: string | null): boolean

Whether the name resolves to a registered scope.

Parameter	Type	Passing	Description
scope	string | null | undefined	Optional	—

Returns: boolean.

acceptsTool

Instance method.

Whether a scope accepts an intent.

The App may override the declared goalIds through acceptsTool; without an override the membership check applies.

acceptsTool(scope: string, goal: string): boolean

Whether a scope accepts an intent.

The App may override the declared goalIds through acceptsTool; without an override the membership check applies.

Parameter	Type	Passing	Description
scope	string	Required	—
goal	string	Required	—

Returns: boolean.

acceptsQuery

Instance method.

Whether the scope declares this query scope; a null scope accepts nothing.

acceptsQuery(scope: string | null, queryScope: string): boolean

Whether the scope declares this query scope; a null scope accepts nothing.

Parameter	Type	Passing	Description
scope	string | null	Required	—
queryScope	string	Required	—

Returns: boolean.

is

Instance method.

Whether the scope belongs to the given App category.

is(scope: string | null | undefined, category: Definition["category"]): boolean

Whether the scope belongs to the given App category.

Parameter	Type	Passing	Description
scope	string | null | undefined	Required	—
category	Definition["category"]	Required	—

Returns: boolean.

queryScopeIds

Instance method.

Every query scope declared by any registered scope, deduplicated.

queryScopeIds(): string[]

Every query scope declared by any registered scope, deduplicated.

No call parameters.

Returns: string[].

topics

Instance method.

Knowledge topic ids of one scope; copied so callers cannot mutate the registry.

topics(scope?: string | null): string[]

Knowledge topic ids of one scope; copied so callers cannot mutate the registry.

Parameter	Type	Passing	Description
scope	string | null | undefined	Optional	—

Returns: string[].

evidence

Instance method.

Evidence declarations of one scope; copied so callers cannot mutate the registry.

evidence(scope?: string | null): RegisteredScopeEvidence<Definition>[]

Evidence declarations of one scope; copied so callers cannot mutate the registry.

Parameter	Type	Passing	Description
scope	string | null | undefined	Optional	—

Returns: Readonly<RegistrationData<NonNullable<Definition["evidence"]>[number]>>[].

contextTier

Instance method.

Declared context tier of one scope, if any.

contextTier(scope?: string | null): Definition["contextTier"] | undefined

Declared context tier of one scope, if any.

Parameter	Type	Passing	Description
scope	string | null | undefined	Optional	—

Returns: Definition["contextTier"] \| undefined.

describe

Instance method.

Copy the scopes that accept at least one of the given goals.

describe(goals?: readonly string[]): ScopeDescription<Definition>[]

Copy the scopes that accept at least one of the given goals.

Parameter	Type	Passing	Description
goals	readonly string[] | undefined	Optional	—

Returns: ScopeDescription<Definition>[].

Examples

• Domain Tools: tool declarations and scope relationships: One list provides the available tools, allowed delegates, scope aliases, sources, and tool relationships.

Register one tool that explains an interface

Beginner · Node.js

TypeScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([
  { id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: true },
]);
console.log(tools.ids(), tools.allows('explain', 'read'));
const scopes = ScopeRegistry.create([
  { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge' },
]);
console.log(scopes.require('sdk').knowledgeTopicIds);

JavaScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([
    { id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: true },
]);
console.log(tools.ids(), tools.allows('explain', 'read'));
const scopes = ScopeRegistry.create([
    { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge' },
]);
console.log(scopes.require('sdk').knowledgeTopicIds);

Add constraints and scope relationships while keeping the same query entry

Configuration · Node.js

TypeScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = new IntentRegistry({ idPattern: /^[a-z-]+$/, delegates: ['read', 'reply'] })
  .registerAll([{ id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: '用户希望了解 SDK 接口或用法。' }]).seal();
const scopes = ScopeRegistry.create([
  { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge', aliases: ['agent-core'], goalIds: ['explain'], knowledgeTopicIds: ['manual'], toolIds: ['read-source'] },
], { categories: ['knowledge'], requireGoals: true, requireSources: true });
console.log(tools.describe(), scopes.normalize('agent-core'));
console.log(scopes.acceptsTool('agent-core', 'explain'), scopes.topics('sdk'));

JavaScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = new IntentRegistry({ idPattern: /^[a-z-]+$/, delegates: ['read', 'reply'] })
    .registerAll([{ id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: '用户希望了解 SDK 接口或用法。' }]).seal();
const scopes = ScopeRegistry.create([
    { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge', aliases: ['agent-core'], goalIds: ['explain'], knowledgeTopicIds: ['manual'], toolIds: ['read-source'] },
], { categories: ['knowledge'], requireGoals: true, requireSources: true });
console.log(tools.describe(), scopes.normalize('agent-core'));
console.log(scopes.acceptsTool('agent-core', 'explain'), scopes.topics('sdk'));

Related policy source

• Tool validation and sealing
• Scope relationships and aliases

Related definitions

• createScopeRegistry
• RegisteredScope
• RegisteredScopeEvidence
• ScopeDefinition
• ScopeDescription
• ScopeRegistryPolicy