evolcore 0.0.43-test.3 → 0.0.43-test.5

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.
Files changed (192) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/bin/ecmsg.js +492 -0
  3. package/bin/install-codex-managed-hooks.mjs +130 -8
  4. package/dist/ability/application-service.js +37 -0
  5. package/dist/ability/resources.js +28 -0
  6. package/dist/ability/runtime.js +6 -1
  7. package/dist/agents/claude-runner.js +7 -5
  8. package/dist/agents/codex/app-server-client.js +0 -12
  9. package/dist/agents/codex-runner.js +12 -54
  10. package/dist/agents/ecagent-runner.js +130 -35
  11. package/dist/aun/aid/agentmd.js +56 -12
  12. package/dist/aun/aid/control-aid.js +15 -0
  13. package/dist/aun/aid/identity.js +8 -0
  14. package/dist/aun/aid/ownership-operation.js +12 -3
  15. package/dist/aun/menu/client.js +8 -7
  16. package/dist/aun/menu/index.js +1 -1
  17. package/dist/aun/menu/transport.js +8 -5
  18. package/dist/aun/service-proxy.js +3 -0
  19. package/dist/channels/aun.js +56 -22
  20. package/dist/channels/daemon.js +12 -4
  21. package/dist/cli/agent-command.js +5 -0
  22. package/dist/cli/agent-create.js +32 -8
  23. package/dist/cli/agent.js +9 -3
  24. package/dist/cli/aid-bind-command.js +3 -0
  25. package/dist/cli/aun-commands.js +12 -5
  26. package/dist/cli/code-stats.js +451 -213
  27. package/dist/cli/ctl-command.js +1 -3
  28. package/dist/cli/daemon-commands.js +42 -21
  29. package/dist/cli/directory.js +7 -8
  30. package/dist/cli/ecmsg-gateway.js +204 -0
  31. package/dist/cli/getmeta-command.js +2 -1
  32. package/dist/cli/index.js +6 -0
  33. package/dist/cli/init.js +58 -18
  34. package/dist/cli/provider-command.js +82 -5
  35. package/dist/cli/restart-monitor.js +11 -19
  36. package/dist/cli/stats.js +8 -1
  37. package/dist/cli/task-context.js +3 -0
  38. package/dist/cli/trigger-command.js +20 -14
  39. package/dist/config/boot-log.js +23 -2
  40. package/dist/config/config-field-policy.js +2 -0
  41. package/dist/config/config-manager.js +13 -17
  42. package/dist/config/daemon-services.js +1 -0
  43. package/dist/config/peer-role-resolver.js +6 -6
  44. package/dist/config/provider-identity-migration.js +202 -0
  45. package/dist/config/provider-identity.js +37 -0
  46. package/dist/config/provider-ipc-service.js +40 -3
  47. package/dist/config/provider-local-sync.js +153 -0
  48. package/dist/config/providers-config.js +32 -4
  49. package/dist/config/providers-management.js +144 -68
  50. package/dist/config/providers.js +4 -1
  51. package/dist/config/role-schema.js +3 -3
  52. package/dist/config/schema-migration.js +188 -3
  53. package/dist/core/agent-application-service.js +11 -0
  54. package/dist/core/agent-ipc-registration.js +2 -0
  55. package/dist/core/agent-runtime.js +45 -11
  56. package/dist/core/auth/auth-gateway.js +8 -6
  57. package/dist/core/auth/delegation-diagnostics.js +6 -2
  58. package/dist/core/auth/operation-authorizer.js +5 -2
  59. package/dist/core/auth/operation-catalog.js +6 -4
  60. package/dist/core/baseagent-loader.js +11 -3
  61. package/dist/core/bootstrap-service.js +8 -0
  62. package/dist/core/channel-loader.js +61 -23
  63. package/dist/core/command/agent-control.js +4 -1
  64. package/dist/core/command/chatmode-config.js +46 -0
  65. package/dist/core/command/cli-intent-parser.js +2 -1
  66. package/dist/core/command/command-handler.js +16 -20
  67. package/dist/core/command/daemon-diagnostics.js +2 -1
  68. package/dist/core/command/menu-catalog.js +1 -1
  69. package/dist/core/command/menu-handler.js +16 -16
  70. package/dist/core/command/menu-protocol.js +4 -2
  71. package/dist/core/command/provider-menu.js +4 -2
  72. package/dist/core/command/role-menu.js +2 -2
  73. package/dist/core/command/slash-handler.js +56 -42
  74. package/dist/core/daemon-lifecycle.js +35 -17
  75. package/dist/core/event-catalog.js +19 -0
  76. package/dist/core/evolagent-registry.js +3 -0
  77. package/dist/core/handoff/runtime.js +9 -3
  78. package/dist/core/initialization/service.js +4 -3
  79. package/dist/core/ipc-registration.js +6 -0
  80. package/dist/core/message/aun-ipc-sender.js +81 -3
  81. package/dist/core/message/im-renderer.js +24 -19
  82. package/dist/core/message/message-admission.js +13 -2
  83. package/dist/core/message/response-engine.js +40 -41
  84. package/dist/core/message/send-options.js +40 -0
  85. package/dist/core/message/send-routing.js +310 -0
  86. package/dist/core/model/model-capabilities.js +37 -0
  87. package/dist/core/model/model-catalog.js +6 -2
  88. package/dist/core/ownership/owner-resolver.js +117 -14
  89. package/dist/core/permission/ec-command-parser.js +195 -27
  90. package/dist/core/permission/readonly-shell-query.js +66 -7
  91. package/dist/core/permission/tool-error-code.js +13 -1
  92. package/dist/core/permission/tool-policy.js +74 -20
  93. package/dist/core/plugin-lifecycle.js +6 -2
  94. package/dist/core/relation/pa-team.js +7 -2
  95. package/dist/core/relation/same-owner-proof.js +131 -0
  96. package/dist/core/session/session-idle-monitor.js +94 -16
  97. package/dist/core/session/session-manager.js +69 -16
  98. package/dist/core/thread/thread-route.js +5 -2
  99. package/dist/directory/owner-directory-cache.js +690 -99
  100. package/dist/directory/owner-directory-markdown.js +146 -36
  101. package/dist/directory/owner-directory-query-operation.js +7 -9
  102. package/dist/directory/owner-directory-scope.js +12 -0
  103. package/dist/directory/owner-directory-search.js +5 -1
  104. package/dist/directory/owner-directory-store.js +28 -0
  105. package/dist/ecweb/basic-settings-service.js +15 -1
  106. package/dist/ecweb/message-context-service.js +2 -2
  107. package/dist/ecweb/providers-service.js +3 -1
  108. package/dist/ecweb/runtime/lifecycle.js +38 -5
  109. package/dist/ecweb/runtime/supervisor.js +157 -49
  110. package/dist/index.js +202 -38
  111. package/dist/paths.js +2 -1
  112. package/dist/proxy/manager.js +2 -0
  113. package/dist/proxy/service-supervisor.js +379 -143
  114. package/dist/response-system/engines/v1/proactive-flow.js +4 -0
  115. package/dist/trigger/application-service.js +1 -0
  116. package/dist/trigger/audit.js +3 -2
  117. package/dist/trigger/authorization.js +2 -3
  118. package/dist/trigger/event-source.js +4 -0
  119. package/dist/trigger/feedback.js +26 -2
  120. package/dist/trigger/history.js +4 -3
  121. package/dist/trigger/ipc-service.js +24 -19
  122. package/dist/trigger/manager.js +3 -5
  123. package/dist/trigger/parser.js +4 -21
  124. package/dist/trigger/patch.js +3 -15
  125. package/dist/trigger/scheduler.js +48 -13
  126. package/dist/trigger/system-definitions.js +2 -2
  127. package/dist/trigger/validation.js +4 -13
  128. package/dist/utils/autostart.js +2 -2
  129. package/dist/utils/cross-platform.js +36 -8
  130. package/dist/utils/error-utils.js +8 -0
  131. package/dist/utils/macos-autostart.js +31 -0
  132. package/dist/utils/model-prices.jsonl +15 -8
  133. package/dist/utils/process-introspect.js +21 -1
  134. package/dist/utils/public-suffix.js +5811 -0
  135. package/dist/utils/startup-trace.js +7 -1
  136. package/dist/utils/windows-autostart.js +42 -7
  137. package/ecagent/dist/harness/compaction/branch-summarization.js +1 -1
  138. package/ecagent/dist/harness/compaction/compaction.js +4 -4
  139. package/ecagent/dist/harness/env/nodejs.js +46 -2
  140. package/kits/docs/aun/ABILITY_CALLING.md +3 -3
  141. package/kits/docs/channels/aun.md +1 -1
  142. package/kits/docs/channels/feishu.md +2 -2
  143. package/kits/docs/context-assembly.md +20 -4
  144. package/kits/docs/evolcore/INDEX.md +3 -2
  145. package/kits/docs/evolcore/agent.md +2 -2
  146. package/kits/docs/evolcore/aid.md +8 -2
  147. package/kits/docs/evolcore/ctl.md +13 -4
  148. package/kits/docs/evolcore/directory.md +48 -15
  149. package/kits/docs/evolcore/file-navigation.md +63 -49
  150. package/kits/docs/evolcore/group.md +6 -6
  151. package/kits/docs/evolcore/memory-consolidation.md +1 -1
  152. package/kits/docs/evolcore/menu-protocol.md +33 -3
  153. package/kits/docs/evolcore/model.md +5 -3
  154. package/kits/docs/evolcore/msg.md +28 -27
  155. package/kits/docs/evolcore/provider.md +39 -5
  156. package/kits/docs/evolcore/response.md +3 -1
  157. package/kits/docs/evolcore/thread-chain.md +12 -14
  158. package/kits/docs/evolcore/tool-authorization.md +21 -1
  159. package/kits/docs/evolcore/trigger.md +12 -9
  160. package/kits/docs/identity/ROLE_DETAIL.md +1 -1
  161. package/kits/docs/prompt-loading-architecture.md +30 -20
  162. package/kits/eck_manifest.auxiliary.json +5 -5
  163. package/kits/eck_manifest.json +28 -49
  164. package/kits/eck_manifest.memory.json +18 -18
  165. package/kits/rules/01-overview.md +43 -45
  166. package/kits/rules/02-navigation.md +44 -53
  167. package/kits/rules/03-identity.md +21 -25
  168. package/kits/rules/04-relation.md +23 -33
  169. package/kits/rules/05-venue.md +24 -25
  170. package/kits/rules/06-channel.md +3 -3
  171. package/kits/schemas/_meta.json +20 -27
  172. package/kits/schemas/agent-config.schema.19.json +10 -6
  173. package/kits/schemas/providers.schema.2.json +74 -0
  174. package/kits/schemas/relation-config.schema.12.json +2 -2
  175. package/kits/schemas/role-config.schema.2.json +5 -5
  176. package/kits/schemas/role-registry.schema.1.json +1 -1
  177. package/kits/skills/ec-agent-create/SKILL.md +1 -0
  178. package/kits/skills/ec-service-proxy/SKILL.md +3 -0
  179. package/kits/skills/ec-trigger/SKILL.md +4 -4
  180. package/kits/skills/ec-trigger/references/examples.md +1 -1
  181. package/kits/templates/system-fragments/channel.md +5 -5
  182. package/kits/templates/system-fragments/commands.md +3 -2
  183. package/kits/templates/system-fragments/directory-contacts.md +10 -3
  184. package/kits/templates/system-fragments/identity.md +0 -1
  185. package/kits/templates/system-fragments/personal-assistant.md +22 -3
  186. package/kits/templates/system-fragments/reply.md +47 -28
  187. package/kits/templates/system-fragments/session.md +2 -9
  188. package/kits/templates/system-fragments/thread.md +5 -5
  189. package/package.json +17 -13
  190. package/kits/schemas/agent-config.schema.20.json +0 -925
  191. package/kits/schemas/relation-config.schema.13.json +0 -289
  192. package/kits/schemas/role-config.schema.3.json +0 -1038
@@ -1,13 +1,17 @@
1
1
  import { createHash } from 'node:crypto';
2
+ import { isDeepStrictEqual } from 'node:util';
2
3
  import fs from 'node:fs';
3
4
  import path, { posix } from 'node:path';
4
5
  import { resolvePaths } from '../paths.js';
5
6
  import { ConfigTarget, mutateConfig } from './config-manager.js';
6
7
  import { atomicReadJson } from '../utils/atomic-write.js';
7
8
  import { readProvidersFile, validateProvidersFile } from './providers.js';
8
- import { providerEnvironmentVariable, providerNameFromBaseUrlIfStatic, resolveProviderService, resolveProviderServiceForBaseagent, validateProviderName } from './providers-config.js';
9
+ import { providerEnvironmentVariable, providerNameFromBaseUrlIfStatic, resolveProviderId, resolveProviderService, resolveProviderServiceForBaseagent, validateProviderName } from './providers-config.js';
10
+ import { providerIdentity } from './provider-identity.js';
9
11
  export const PROVIDER_SECRET_MASK = '<redacted>';
10
12
  function providerReferences(providerId, providerFile) {
13
+ const registry = readProvidersFile(providerFile);
14
+ const referencedIds = new Set([providerId, ...Object.entries(registry.aliases ?? {}).filter(([, target]) => target === providerId).map(([alias]) => alias)]);
11
15
  const root = path.dirname(path.resolve(providerFile));
12
16
  const agentsDir = path.join(root, 'agents');
13
17
  const candidates = [path.join(agentsDir, 'defaults.json')];
@@ -26,6 +30,7 @@ function providerReferences(providerId, providerFile) {
26
30
  };
27
31
  for (const agent of directories(agentsDir)) {
28
32
  candidates.push(path.join(agentsDir, agent.name, 'config.json'));
33
+ candidates.push(path.join(agentsDir, agent.name, 'data', 'initialization.json'));
29
34
  for (const relation of directories(path.join(agentsDir, agent.name, 'relations'))) {
30
35
  candidates.push(path.join(agentsDir, agent.name, 'relations', relation.name, 'config.json'));
31
36
  }
@@ -40,7 +45,7 @@ function providerReferences(providerId, providerFile) {
40
45
  return;
41
46
  for (const [key, child] of Object.entries(value)) {
42
47
  const childPath = fieldPath + '.' + key;
43
- if (key === 'provider' && child === providerId)
48
+ if (key === 'provider' && typeof child === 'string' && referencedIds.has(child))
44
49
  references.push({ file, path: childPath });
45
50
  visit(child, childPath, file);
46
51
  }
@@ -52,7 +57,7 @@ function providerReferences(providerId, providerFile) {
52
57
  continue;
53
58
  if (!value || typeof value !== 'object' || Array.isArray(value))
54
59
  throw new Error();
55
- for (const field of ['baseagents', 'agents', 'Services', 'decision_model']) {
60
+ for (const field of ['baseagents', 'agents', 'Services', 'decision_model', 'plan', 'creation']) {
56
61
  visit(value[field], field, path.relative(root, file).replace(/\\/g, '/'));
57
62
  }
58
63
  }
@@ -82,7 +87,7 @@ function revisionValue(value) {
82
87
  .map(([key, entry]) => [key, revisionValue(entry)]));
83
88
  }
84
89
  export function providersRevision(value) {
85
- return createHash('sha256').update(JSON.stringify(revisionValue({ providers: value.providers, ...(value.nextId !== undefined ? { nextId: value.nextId } : {}) }))).digest('hex');
90
+ return createHash('sha256').update(JSON.stringify(revisionValue({ providers: value.providers, ...(value.nextId !== undefined ? { nextId: value.nextId } : {}), ...(Object.keys(value.aliases ?? {}).length ? { aliases: value.aliases } : {}) }))).digest('hex');
86
91
  }
87
92
  export function readProvidersSnapshot(file = resolvePaths().providersConfig) {
88
93
  return providersSnapshot(readProvidersFile(file));
@@ -92,7 +97,9 @@ export function readProviderForExport(providerId, serviceType, file = resolvePat
92
97
  throw new Error('Invalid provider identifier');
93
98
  if (serviceType !== undefined && (!/^[A-Za-z0-9_-]+$/u.test(serviceType) || ['__proto__', 'constructor', 'prototype'].includes(serviceType)))
94
99
  throw new Error('Invalid service type');
95
- const provider = readProvidersFile(file).providers[providerId];
100
+ const registry = readProvidersFile(file);
101
+ providerId = resolveProviderId(providerId, registry);
102
+ const provider = registry.providers[providerId];
96
103
  if (!provider)
97
104
  throw Object.assign(new Error('Provider not found'), { statusCode: 404 });
98
105
  const exported = structuredClone(provider);
@@ -120,6 +127,7 @@ function providersSnapshot(value) {
120
127
  return {
121
128
  ...(value.$schema_version !== undefined ? { $schema_version: value.$schema_version } : {}),
122
129
  ...(value.nextId !== undefined ? { nextId: value.nextId } : {}),
130
+ ...(value.aliases ? { aliases: structuredClone(value.aliases) } : {}),
123
131
  providers,
124
132
  revision: providersRevision(value),
125
133
  };
@@ -155,14 +163,17 @@ export function resolveProviderDraftService(input, file = resolvePaths().provide
155
163
  throw new Error('Invalid provider identifier');
156
164
  }
157
165
  const current = readProvidersFile(file);
158
- const previous = Object.hasOwn(current.providers, input.providerId) ? current.providers[input.providerId] : undefined;
166
+ const providerId = resolveProviderId(input.providerId, current);
167
+ const previous = Object.hasOwn(current.providers, providerId) ? current.providers[providerId] : undefined;
159
168
  const provider = resolveDraftProvider(input.value, previous, input.imports);
169
+ if (previous)
170
+ assertProviderDomainUnchanged(previous, provider);
160
171
  if (input.baseagent) {
161
- return resolveProviderServiceForBaseagent(input.providerId, input.baseagent, input.serviceType, {
162
- providers: { [input.providerId]: provider },
172
+ return resolveProviderServiceForBaseagent(providerId, input.baseagent, input.serviceType, {
173
+ providers: { [providerId]: provider },
163
174
  });
164
175
  }
165
- return resolveProviderService(input.providerId, input.serviceType, { providers: { [input.providerId]: provider } });
176
+ return resolveProviderService(providerId, input.serviceType, { providers: { [providerId]: provider } });
166
177
  }
167
178
  export async function updateProvider(input, file = resolvePaths().providersConfig) {
168
179
  if (!/^[A-Za-z0-9_-]+$/u.test(input.providerId) || ['__proto__', 'constructor', 'prototype'].includes(input.providerId)) {
@@ -170,23 +181,26 @@ export async function updateProvider(input, file = resolvePaths().providersConfi
170
181
  }
171
182
  const result = mutateConfig(ConfigTarget.Providers, { providerFile: file }, config => {
172
183
  const current = config;
184
+ const providerId = resolveProviderId(input.providerId, current);
173
185
  if (providersRevision(current) !== input.revision) {
174
186
  throw Object.assign(new Error('Providers changed after loading; reload before saving'), { code: 'CONFLICT', statusCode: 409, data: { kind: 'revision_conflict' } });
175
187
  }
176
- if (!Object.hasOwn(current.providers, input.providerId)) {
188
+ if (!Object.hasOwn(current.providers, providerId)) {
177
189
  throw Object.assign(new Error(`Provider not found: ${input.providerId}`), { code: 'NOT_FOUND', statusCode: 404 });
178
190
  }
179
191
  if (input.remove) {
180
- assertProviderUnreferenced(input.providerId, file);
181
- current.nextId = nextProviderSequence(current);
182
- delete current.providers[input.providerId];
192
+ assertProviderUnreferenced(providerId, file);
193
+ delete current.providers[providerId];
194
+ removeProviderAliases(current, providerId);
183
195
  }
184
196
  else {
185
- const value = retainSecrets(input.value, current.providers[input.providerId]);
186
- const normalized = validateProvidersFile({ providers: { [input.providerId]: value } });
187
- if (normalized.providers[input.providerId].name !== undefined)
188
- normalized.providers[input.providerId].name = validateProviderName(normalized.providers[input.providerId].name);
189
- current.providers[input.providerId] = normalized.providers[input.providerId];
197
+ const previous = current.providers[providerId];
198
+ const value = retainSecrets(input.value, previous);
199
+ const normalized = validateProvidersFile({ providers: { draft: value } }).providers.draft;
200
+ assertProviderDomainUnchanged(previous, normalized);
201
+ if (normalized.name !== undefined)
202
+ normalized.name = validateProviderName(normalized.name);
203
+ current.providers[providerId] = normalized;
190
204
  }
191
205
  return current;
192
206
  });
@@ -228,7 +242,7 @@ export function parseProviderImport(text) {
228
242
  const value = parsed;
229
243
  const isProviderMap = Object.values(value).every(provider => provider && typeof provider === 'object'
230
244
  && !Array.isArray(provider) && Object.hasOwn(provider, 'common'));
231
- const isSingleProvider = !isProviderMap && ['name', 'common', 'services'].some(field => Object.hasOwn(value, field));
245
+ const isSingleProvider = !isProviderMap && ['name', 'domain', 'common', 'services'].some(field => Object.hasOwn(value, field));
232
246
  if (!Object.hasOwn(value, 'providers') && isSingleProvider && !Object.hasOwn(value, 'common')) {
233
247
  throw new Error('Provider configuration is missing "common"; check the field spelling');
234
248
  }
@@ -247,18 +261,67 @@ export function previewProviderImport(text) {
247
261
  }
248
262
  export function previewProviderValue(value) {
249
263
  const normalized = validateProvidersFile({ providers: { preview: value } });
264
+ normalized.providers.preview.domain = providerIdentity(normalized.providers.preview).domain;
250
265
  return { provider: providersSnapshot(normalized).providers.preview };
251
266
  }
252
- function nextProviderSequence(config) {
253
- let nextId = config.nextId ?? 1;
254
- for (const providerId of Object.keys(config.providers)) {
255
- const match = /^provider-(\d+)$/u.exec(providerId);
256
- if (match)
257
- nextId = Math.max(nextId, Number(match[1]) + 1);
267
+ function removeProviderAliases(config, providerId) {
268
+ for (const [alias, target] of Object.entries(config.aliases ?? {})) {
269
+ if (target === providerId)
270
+ delete config.aliases[alias];
258
271
  }
259
- if (!Number.isSafeInteger(nextId) || nextId >= Number.MAX_SAFE_INTEGER)
260
- throw new Error('Provider ID sequence is exhausted');
261
- return nextId;
272
+ if (config.aliases && !Object.keys(config.aliases).length)
273
+ delete config.aliases;
274
+ }
275
+ function assertProviderDomainUnchanged(previous, next) {
276
+ let previousDomain;
277
+ try {
278
+ previousDomain = providerIdentity(previous).domain;
279
+ }
280
+ catch (error) {
281
+ const code = error?.code;
282
+ if (previous.domain === undefined && (code === 'PROVIDER_DOMAIN_REQUIRED' || code === 'PROVIDER_DOMAIN_INVALID')) {
283
+ if (previous.common.baseUrl === next.common.baseUrl) {
284
+ if (next.domain !== undefined)
285
+ next.domain = providerIdentity(next).domain;
286
+ return;
287
+ }
288
+ }
289
+ throw error;
290
+ }
291
+ const identity = providerIdentity(next);
292
+ if (identity.domain !== previousDomain) {
293
+ throw Object.assign(new Error('Provider domain is immutable; create a different Provider'), { code: 'PROVIDER_DOMAIN_IMMUTABLE' });
294
+ }
295
+ next.domain = identity.domain;
296
+ }
297
+ function existingProviderDomain(provider) {
298
+ try {
299
+ return providerIdentity(provider).domain;
300
+ }
301
+ catch {
302
+ return undefined;
303
+ }
304
+ }
305
+ function availableProviderId(config, provider) {
306
+ const identity = providerIdentity(provider);
307
+ provider.domain = identity.domain;
308
+ for (const [existingId, existing] of Object.entries(config.providers)) {
309
+ const domain = existingProviderDomain(existing);
310
+ if (existingId === identity.providerId && domain !== identity.domain) {
311
+ throw Object.assign(new Error('Provider ID hash collision; no ID was reassigned'), {
312
+ code: 'PROVIDER_ID_COLLISION', statusCode: 409, data: { kind: 'provider_id_collision', providerId: identity.providerId, domain: identity.domain, existingDomain: domain },
313
+ });
314
+ }
315
+ if (domain === identity.domain) {
316
+ throw Object.assign(new Error('Provider domain already exists; update or explicitly merge it'), {
317
+ code: 'PROVIDER_CONFLICT', statusCode: 409, data: { kind: 'provider_domain_exists', providerId: existingId, domain },
318
+ });
319
+ }
320
+ }
321
+ if (Object.hasOwn(config.aliases ?? {}, identity.providerId)) {
322
+ throw Object.assign(new Error('Provider ID conflicts with a legacy alias'), { code: 'PROVIDER_ID_COLLISION', statusCode: 409 });
323
+ }
324
+ return identity.providerId;
262
325
  }
263
326
  export async function createProvider(input, file = resolvePaths().providersConfig) {
264
327
  if (!/^[a-f0-9]{64}$/u.test(input.revision))
@@ -274,10 +337,14 @@ export async function createProvider(input, file = resolvePaths().providersConfi
274
337
  if (providersRevision(current) !== input.revision) {
275
338
  throw Object.assign(new Error('Providers changed after loading; reload before saving'), { code: 'CONFLICT', statusCode: 409, data: { kind: 'revision_conflict' } });
276
339
  }
277
- const sequence = nextProviderSequence(current);
278
- const providerId = `provider-${sequence}`;
340
+ const identity = providerIdentity(provider);
341
+ provider.domain = identity.domain;
342
+ const existing = current.providers[identity.providerId];
343
+ if (existing && isDeepStrictEqual(existing, provider))
344
+ return { current, providerId: identity.providerId };
345
+ const providerId = availableProviderId(current, provider);
279
346
  current.providers[providerId] = provider;
280
- current.nextId = sequence + 1;
347
+ delete current.nextId;
281
348
  return { current, providerId };
282
349
  });
283
350
  return { ...providersSnapshot(result.value.current), providerId: result.value.providerId };
@@ -335,14 +402,16 @@ function resolveDraftProvider(value, previous, imports = []) {
335
402
  for (const item of imports) {
336
403
  const imported = validateProvidersFile({ providers: { imported: item } }).providers.imported;
337
404
  rejectMaskedImportSecrets({ imported });
338
- const secretSourceHost = secretSource ? providerHostname(secretSource.common.baseUrl) : undefined;
339
- const importedHost = providerHostname(imported.common.baseUrl);
340
- if (secretSource && secretSourceHost && importedHost && secretSourceHost !== importedHost) {
405
+ if (secretSource && providerIdentity(secretSource).domain !== providerIdentity(imported).domain) {
341
406
  throw new Error('Imported Provider domain does not match the target Provider');
342
407
  }
343
408
  secretSource = secretSource ? mergeImportedProvider(secretSource, imported) : imported;
344
409
  }
345
- return validateProvidersFile({ providers: { draft: retainSecrets(value, secretSource) } }).providers.draft;
410
+ const provider = validateProvidersFile({ providers: { draft: retainSecrets(value, secretSource) } }).providers.draft;
411
+ if (imports.length && secretSource && providerIdentity(provider).domain !== providerIdentity(secretSource).domain) {
412
+ throw new Error('Imported Provider domain does not match the draft Provider');
413
+ }
414
+ return provider;
346
415
  }
347
416
  export async function saveProviderChanges(input, file = resolvePaths().providersConfig) {
348
417
  if (!Array.isArray(input.changes) || !input.changes.length)
@@ -368,25 +437,31 @@ export async function saveProviderChanges(input, file = resolvePaths().providers
368
437
  }
369
438
  const providerIds = {};
370
439
  const originalIds = new Set(Object.keys(current.providers));
371
- if (input.changes.some(change => change.remove))
372
- current.nextId = nextProviderSequence(current);
440
+ const resolvedIds = new Set();
373
441
  for (const change of input.changes) {
374
- if (change.create ? originalIds.has(change.providerId) : !originalIds.has(change.providerId)) {
442
+ const targetId = change.create ? change.providerId : resolveProviderId(change.providerId, current);
443
+ if (resolvedIds.has(targetId))
444
+ throw new Error('Duplicate provider change');
445
+ resolvedIds.add(targetId);
446
+ if (change.create ? originalIds.has(targetId) : !originalIds.has(targetId)) {
375
447
  throw new Error(change.create ? 'Provider already exists' : 'Provider not found');
376
448
  }
377
449
  if (change.remove) {
378
- assertProviderUnreferenced(change.providerId, file);
379
- delete current.providers[change.providerId];
450
+ assertProviderUnreferenced(targetId, file);
451
+ delete current.providers[targetId];
452
+ removeProviderAliases(current, targetId);
380
453
  continue;
381
454
  }
382
- const previous = change.create ? undefined : current.providers[change.providerId];
455
+ const previous = change.create ? undefined : current.providers[targetId];
383
456
  const provider = resolveDraftProvider(change.value, previous, change.imports);
457
+ if (previous)
458
+ assertProviderDomainUnchanged(previous, provider);
384
459
  provider.name ||= providerNameFromBaseUrlIfStatic(provider.common.baseUrl);
385
460
  if (provider.name !== undefined)
386
461
  provider.name = validateProviderName(provider.name);
387
- const providerId = change.create ? `provider-${nextProviderSequence(current)}` : change.providerId;
462
+ const providerId = change.create ? availableProviderId(current, provider) : targetId;
388
463
  if (change.create)
389
- current.nextId = Number(providerId.slice('provider-'.length)) + 1;
464
+ delete current.nextId;
390
465
  current.providers[providerId] = provider;
391
466
  providerIds[change.providerId] = providerId;
392
467
  }
@@ -394,9 +469,7 @@ export async function saveProviderChanges(input, file = resolvePaths().providers
394
469
  });
395
470
  return { ...providersSnapshot(result.value.current), providerIds: result.value.providerIds };
396
471
  }
397
- export async function importOrMergeBaseagentProvider(input, file = resolvePaths().providersConfig) {
398
- if (!/^[a-f0-9]{64}$/u.test(input.revision))
399
- throw new Error('A valid providers revision is required');
472
+ export function importBaseagentProviderIntoRegistry(current, input) {
400
473
  const normalized = validateProvidersFile({ providers: { imported: input.value } });
401
474
  rejectMaskedImportSecrets(normalized.providers);
402
475
  const imported = normalized.providers.imported;
@@ -405,33 +478,36 @@ export async function importOrMergeBaseagentProvider(input, file = resolvePaths(
405
478
  imported.name = validateProviderName(input.name);
406
479
  if (input.resolution === 'cancel')
407
480
  throw Object.assign(new Error('Provider import cancelled'), { code: 'CANCELLED', statusCode: 409 });
481
+ const identity = providerIdentity(imported);
482
+ imported.domain = identity.domain;
483
+ const match = Object.entries(current.providers).find(([, provider]) => existingProviderDomain(provider) === identity.domain);
484
+ if (match && input.requireResolution && input.resolution === undefined) {
485
+ const [providerId, existing] = match;
486
+ throw Object.assign(new Error('Provider conflict requires an explicit resolution'), {
487
+ code: 'PROVIDER_CONFLICT', statusCode: 409,
488
+ data: { kind: 'provider_conflict', providerId, overlaps: Object.keys(imported.services || {}).filter(type => Object.hasOwn(existing.services || {}, type)) },
489
+ });
490
+ }
491
+ if (match && input.resolution !== 'create') {
492
+ const [providerId, existing] = match;
493
+ const replaceServiceTypes = new Set(Object.entries(input.serviceDecisions || {}).filter(([, decision]) => decision === 'imported').map(([type]) => type));
494
+ current.providers[providerId] = validateProvidersFile({ providers: { [providerId]: mergeImportedProvider(existing, imported, replaceServiceTypes) } }).providers[providerId];
495
+ return { current, providerId, merged: true };
496
+ }
497
+ const providerId = availableProviderId(current, imported);
498
+ current.providers[providerId] = imported;
499
+ delete current.nextId;
500
+ return { current, providerId, merged: false };
501
+ }
502
+ export async function importOrMergeBaseagentProvider(input, file = resolvePaths().providersConfig) {
503
+ if (!/^[a-f0-9]{64}$/u.test(input.revision))
504
+ throw new Error('A valid providers revision is required');
408
505
  const result = mutateConfig(ConfigTarget.Providers, { providerFile: file }, config => {
409
506
  const current = config;
410
507
  if (providersRevision(current) !== input.revision) {
411
508
  throw Object.assign(new Error('Providers changed after loading; reload before saving'), { code: 'CONFLICT', statusCode: 409, data: { kind: 'revision_conflict' } });
412
509
  }
413
- const importedHost = providerHostname(imported.common.baseUrl);
414
- const importedName = imported.name?.trim().toLowerCase();
415
- const match = Object.entries(current.providers).find(([, provider]) => (!!importedName && provider.name?.trim().toLowerCase() === importedName)
416
- || (!!importedHost && providerHostname(provider.common.baseUrl) === importedHost));
417
- if (match && input.requireResolution && input.resolution === undefined) {
418
- const [providerId, existing] = match;
419
- throw Object.assign(new Error('Provider conflict requires an explicit resolution'), {
420
- code: 'PROVIDER_CONFLICT', statusCode: 409,
421
- data: { kind: 'provider_conflict', providerId, overlaps: Object.keys(imported.services || {}).filter(type => Object.hasOwn(existing.services || {}, type)) },
422
- });
423
- }
424
- if (match && input.resolution !== 'create') {
425
- const [providerId, existing] = match;
426
- const replaceServiceTypes = new Set(Object.entries(input.serviceDecisions || {}).filter(([, decision]) => decision === 'imported').map(([type]) => type));
427
- current.providers[providerId] = validateProvidersFile({ providers: { [providerId]: mergeImportedProvider(existing, imported, replaceServiceTypes) } }).providers[providerId];
428
- return { current, providerId, merged: true };
429
- }
430
- const sequence = nextProviderSequence(current);
431
- const providerId = `provider-${sequence}`;
432
- current.providers[providerId] = imported;
433
- current.nextId = sequence + 1;
434
- return { current, providerId, merged: false };
510
+ return importBaseagentProviderIntoRegistry(current, input);
435
511
  });
436
512
  return { ...providersSnapshot(result.value.current), providerId: result.value.providerId, merged: result.value.merged };
437
513
  }
@@ -1,10 +1,13 @@
1
1
  import { resolvePaths } from '../paths.js';
2
2
  import { ConfigTarget, read, write } from './config-manager.js';
3
- import { assertProviderSelectionWrite as validateSelectionWrite, resolveProviderModelOverrides as resolveModelOverrides, resolveProviderService as resolveService, resolveProviderServiceForBaseagent as resolveServiceForBaseagent, resolveServiceSelection as resolveSelection, } from './providers-config.js';
3
+ import { assertProviderSelectionWrite as validateSelectionWrite, resolveProviderModelOverrides as resolveModelOverrides, resolveProviderService as resolveService, resolveProviderServiceForBaseagent as resolveServiceForBaseagent, resolveServiceSelection as resolveSelection, resolveProviderId as resolveId, } from './providers-config.js';
4
4
  export { providerIsConfigured, providerServiceTypeForBaseagent, providerServiceTypesForBaseagent, providerServiceTypeForPurpose, validateProvidersFile, } from './providers-config.js';
5
5
  export function readProvidersFile(file = resolvePaths().providersConfig) {
6
6
  return read(ConfigTarget.Providers, { providerFile: file }) ?? { providers: {} };
7
7
  }
8
+ export function resolveProviderId(providerId, file = resolvePaths().providersConfig) {
9
+ return resolveId(providerId, readProvidersFile(file));
10
+ }
8
11
  export function writeProvidersFile(value, file = resolvePaths().providersConfig) {
9
12
  write(ConfigTarget.Providers, value, { providerFile: file });
10
13
  }
@@ -33,12 +33,12 @@ export function rolePermissionFields() {
33
33
  patterns: field.patterns?.map((pattern) => ({ ...pattern, kind: 'pattern' })),
34
34
  }));
35
35
  }
36
- /** Read compatibility for policies saved before group delivery became proactive-only. */
36
+ /** Read compatibility for published v1 policies; current policies validate strictly. */
37
37
  export function normalizeRoleGroupChatmodeCompat(value) {
38
38
  if (!isRecord(value) || !isRecord(value.permissions))
39
39
  return value;
40
40
  const version = value.$schema_version ?? 1;
41
- if (version !== 1 && version !== 2)
41
+ if (version !== 1)
42
42
  return value;
43
43
  const group = value.permissions['chatmode.group'];
44
44
  if (!isRecord(group))
@@ -82,7 +82,7 @@ export function validateRoleConfig(value) {
82
82
  const compatible = normalizeRoleGroupChatmodeCompat(normalizeRoleEffortCompat(value));
83
83
  const schema = loadSchema('role-config');
84
84
  const normalized = isRecord(compatible)
85
- && (!Object.hasOwn(compatible, '$schema_version') || compatible.$schema_version === 1 || compatible.$schema_version === 2)
85
+ && (!Object.hasOwn(compatible, '$schema_version') || compatible.$schema_version === 1)
86
86
  ? { ...compatible, $schema_version: schema.version }
87
87
  : compatible;
88
88
  if (!schema.validate(normalized)) {
@@ -2,15 +2,19 @@ import crypto from 'crypto';
2
2
  import fs from 'fs';
3
3
  import path from 'path';
4
4
  import { resolvePaths } from '../paths.js';
5
- import { ConfigError } from './config-manager.js';
5
+ import { acquireConfigMutationLock, ConfigError } from './config-manager.js';
6
6
  import { firstConfiguredOwner } from './owner-config.js';
7
7
  import { resolveLegacyBaseagentModelSelection } from '../agents/baseagent.js';
8
+ import { loadSchema } from './schema-registry.js';
9
+ import { planProviderIdentityMigration } from './provider-identity-migration.js';
8
10
  const MIGRATION_KIND = {
9
11
  'auxiliary-model-v1': 'auxiliary-model',
10
12
  'agent-only-model-v1': 'agent-only-model',
11
13
  'agent-model-provider-v1': 'agent-only-model',
12
14
  'provider-service-type-v1': 'provider-service-type',
15
+ 'provider-domain-id-v1': 'provider-domain-id',
13
16
  'relation-config-v11-v1': 'agent-only-model',
17
+ 'published-schema-consolidation-v1': 'agent-only-model',
14
18
  'legacy-model-selection-v1': 'agent-only-model',
15
19
  'access-policy-v17-v1': 'agent-only-model',
16
20
  'peer-file-v1': 'agent-only-model',
@@ -1211,11 +1215,14 @@ function planAgentModelProviderMigration(home) {
1211
1215
  }
1212
1216
  const providersFile = path.join(home, 'providers.json');
1213
1217
  let providers = {};
1218
+ let providerRegistry = {};
1214
1219
  if (fs.existsSync(providersFile)) {
1215
1220
  try {
1216
1221
  const raw = readJson(providersFile).value;
1217
- if (isRecord(raw) && isRecord(raw.providers))
1222
+ if (isRecord(raw) && isRecord(raw.providers)) {
1223
+ providerRegistry = raw;
1218
1224
  providers = { ...raw.providers };
1225
+ }
1219
1226
  }
1220
1227
  catch {
1221
1228
  providers = {};
@@ -1311,7 +1318,7 @@ function planAgentModelProviderMigration(home) {
1311
1318
  summary.filesChanged += 1;
1312
1319
  }
1313
1320
  if (Object.keys(providers).length > 0) {
1314
- const nextText = jsonText({ $schema_version: 1, providers });
1321
+ const nextText = jsonText({ $schema_version: 1, ...providerRegistry, providers });
1315
1322
  if (nextText !== providersBefore) {
1316
1323
  changes.push({ file: providersFile, kind: 'agent-only-model', before: providersBefore, after: nextText });
1317
1324
  details.push({ file: 'providers.json', removed: [] });
@@ -1413,6 +1420,65 @@ function planProviderServiceTypeMigration(home) {
1413
1420
  }
1414
1421
  return { home, changes, summary, details };
1415
1422
  }
1423
+ export function runProviderIdentitySchemaMigration(options = {}) {
1424
+ const id = 'provider-domain-id-v1';
1425
+ const home = path.resolve(options.home || resolvePaths().root);
1426
+ const release = acquireLock(home, id);
1427
+ try {
1428
+ assertDaemonStopped(home);
1429
+ recoverJournal(home, id);
1430
+ const plan = planProviderIdentityMigration(home);
1431
+ const backup = options.apply ? applyMigration(plan, id) : null;
1432
+ return { ok: true, mode: options.apply ? 'applied' : 'dry-run',
1433
+ home, changedFiles: plan.changes.length, backup, summary: plan.summary, pending: plan.pending };
1434
+ }
1435
+ finally {
1436
+ release();
1437
+ }
1438
+ }
1439
+ export async function ensureProviderIdentityMigrationOnStartup() {
1440
+ try {
1441
+ const result = runProviderIdentitySchemaMigration({ apply: true });
1442
+ return result.changedFiles === 0 && result.pending.length === 0 ? null : result;
1443
+ }
1444
+ catch (error) {
1445
+ throw new ConfigError('PROVIDER_IDENTITY_MIGRATION_FAILED', 'Automatic Provider identity migration failed; resolve conflicting domains or connection settings before restarting', { cause: error });
1446
+ }
1447
+ }
1448
+ export function commitProviderSyncMigration(plan) {
1449
+ const id = 'provider-domain-id-v1';
1450
+ const releaseMigration = acquireLock(plan.home, id);
1451
+ const releases = [];
1452
+ try {
1453
+ if (fs.existsSync(journalPath(plan.home, id))) {
1454
+ throw Object.assign(new Error('An unfinished Provider migration requires startup recovery'), { code: 'CONFLICT' });
1455
+ }
1456
+ const expected = new Map(plan.expected.map(item => [item.file, item.before]));
1457
+ for (const item of plan.changes)
1458
+ expected.set(item.file, item.before);
1459
+ const home = path.resolve(plan.home);
1460
+ for (const file of [...expected.keys()].sort()) {
1461
+ const relative = path.relative(home, file);
1462
+ if (!relative || relative.startsWith('..') || path.isAbsolute(relative))
1463
+ throw new Error('Unsafe Provider sync path');
1464
+ for (let current = path.resolve(file); current !== home; current = path.dirname(current)) {
1465
+ if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink())
1466
+ throw new Error('Provider sync does not follow symlinks');
1467
+ }
1468
+ releases.push(acquireConfigMutationLock(file));
1469
+ const actual = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
1470
+ if (actual !== expected.get(file)) {
1471
+ throw Object.assign(new Error('Configuration changed during Provider sync; retry after reviewing the current configuration'), { code: 'CONFLICT' });
1472
+ }
1473
+ }
1474
+ return applyMigration(plan, id);
1475
+ }
1476
+ finally {
1477
+ for (const release of releases.reverse())
1478
+ release();
1479
+ releaseMigration();
1480
+ }
1481
+ }
1416
1482
  export function runProviderServiceTypeSchemaMigration(options = {}) {
1417
1483
  const id = 'provider-service-type-v1';
1418
1484
  const home = path.resolve(options.home || resolvePaths().root);
@@ -1542,6 +1608,125 @@ export async function ensureRelationConfigVersionMigrationOnStartup() {
1542
1608
  throw new ConfigError('RELATION_CONFIG_VERSION_MIGRATION_FAILED', `Automatic relation-config version migration failed: ${detail}`, { cause: error });
1543
1609
  }
1544
1610
  }
1611
+ // ── Published schema consolidation: retired v20/v13 → v19/v12 ───────────────
1612
+ /**
1613
+ * The unpublished v20/v13 schemas only split the group-chatmode consolidation
1614
+ * from v19/v12. Once those files were removed, persisted configs created in
1615
+ * the short release window must be restamped before the contact-book startup
1616
+ * gate decides they are an unknown future format.
1617
+ */
1618
+ const PUBLISHED_SCHEMA_CONSOLIDATIONS = [
1619
+ { logicalName: 'agent-config', from: 20, to: 19 },
1620
+ { logicalName: 'relation-config', from: 13, to: 12 },
1621
+ ];
1622
+ function restampPublishedSchemaConsolidation(value, file, consolidation) {
1623
+ if (value.$schema_version !== consolidation.from)
1624
+ return null;
1625
+ const next = { ...value, $schema_version: consolidation.to };
1626
+ const schema = loadSchema(consolidation.logicalName, consolidation.to);
1627
+ if (!schema.validate(next)) {
1628
+ const detail = (schema.validate.errors ?? [])
1629
+ .map(error => `${error.instancePath || '/'} ${error.message}`)
1630
+ .join('; ');
1631
+ throw new Error(`${file}: retired ${consolidation.logicalName} schema v${consolidation.from} `
1632
+ + `is not compatible with published v${consolidation.to}: ${detail}`);
1633
+ }
1634
+ return next;
1635
+ }
1636
+ function planPublishedSchemaConsolidationMigration(home) {
1637
+ const changes = [];
1638
+ const summary = {
1639
+ agentsScanned: 0,
1640
+ relationsScanned: 0,
1641
+ filesRestamped: 0,
1642
+ };
1643
+ const agentsRoot = path.join(home, 'agents');
1644
+ if (!fs.existsSync(agentsRoot))
1645
+ return { home, changes, summary };
1646
+ const agentConsolidation = PUBLISHED_SCHEMA_CONSOLIDATIONS[0];
1647
+ const relationConsolidation = PUBLISHED_SCHEMA_CONSOLIDATIONS[1];
1648
+ for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
1649
+ if (!entry.isDirectory() || !validAid(entry.name))
1650
+ continue;
1651
+ const directory = path.join(agentsRoot, entry.name);
1652
+ const agentFile = path.join(directory, 'config.json');
1653
+ if (fs.existsSync(agentFile)) {
1654
+ summary.agentsScanned += 1;
1655
+ let parsed;
1656
+ try {
1657
+ parsed = readJson(agentFile);
1658
+ }
1659
+ catch {
1660
+ continue;
1661
+ }
1662
+ if (isRecord(parsed.value)) {
1663
+ const next = restampPublishedSchemaConsolidation(parsed.value, agentFile, agentConsolidation);
1664
+ if (next) {
1665
+ changes.push({ file: agentFile, kind: 'agent-only-model', before: parsed.text, after: jsonText(next) });
1666
+ summary.filesRestamped += 1;
1667
+ }
1668
+ }
1669
+ }
1670
+ for (const relationFile of walkRelationConfigs(path.join(directory, 'relations'))) {
1671
+ summary.relationsScanned += 1;
1672
+ let parsed;
1673
+ try {
1674
+ parsed = readJson(relationFile);
1675
+ }
1676
+ catch {
1677
+ continue;
1678
+ }
1679
+ if (!isRecord(parsed.value))
1680
+ continue;
1681
+ const next = restampPublishedSchemaConsolidation(parsed.value, relationFile, relationConsolidation);
1682
+ if (!next)
1683
+ continue;
1684
+ changes.push({ file: relationFile, kind: 'agent-only-model', before: parsed.text, after: jsonText(next) });
1685
+ summary.filesRestamped += 1;
1686
+ }
1687
+ }
1688
+ return { home, changes, summary };
1689
+ }
1690
+ export function runPublishedSchemaConsolidationMigration(options = {}) {
1691
+ const id = 'published-schema-consolidation-v1';
1692
+ const home = path.resolve(options.home || resolvePaths().root);
1693
+ const release = acquireLock(home, id);
1694
+ try {
1695
+ assertDaemonStopped(home);
1696
+ recoverJournal(home, id);
1697
+ const plan = planPublishedSchemaConsolidationMigration(home);
1698
+ const backup = options.apply ? applyMigration(plan, id) : null;
1699
+ return {
1700
+ ok: true,
1701
+ mode: options.apply ? 'applied' : 'dry-run',
1702
+ home,
1703
+ changedFiles: plan.changes.length,
1704
+ backup,
1705
+ summary: plan.summary,
1706
+ };
1707
+ }
1708
+ finally {
1709
+ release();
1710
+ }
1711
+ }
1712
+ export async function ensurePublishedSchemaConsolidationMigrationOnStartup() {
1713
+ const home = resolvePaths().root;
1714
+ try {
1715
+ const result = runPublishedSchemaConsolidationMigration({ home, apply: true });
1716
+ if (result.changedFiles === 0)
1717
+ return null;
1718
+ return {
1719
+ mode: 'applied',
1720
+ changedFiles: result.changedFiles,
1721
+ backup: result.backup,
1722
+ summary: result.summary,
1723
+ };
1724
+ }
1725
+ catch (error) {
1726
+ const detail = error instanceof Error ? error.message : String(error);
1727
+ throw new ConfigError('PUBLISHED_SCHEMA_CONSOLIDATION_MIGRATION_FAILED', `Automatic published schema consolidation failed: ${detail}`, { cause: error });
1728
+ }
1729
+ }
1545
1730
  // ── Agent 消息准入重写:v16 → v17 → v18 ──────────────────────────────────────
1546
1731
  const ACCESS_POLICY_TARGET_VERSION = 18;
1547
1732
  /**