evolcore 0.0.42 → 0.0.43-test.1

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 (189) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/bin/ec-safe-output.js +4 -1
  3. package/dist/ability/application-service.js +882 -0
  4. package/dist/ability/authorization.js +70 -0
  5. package/dist/ability/command-contract.js +105 -0
  6. package/dist/ability/daemon.js +137 -0
  7. package/dist/ability/development.js +450 -0
  8. package/dist/ability/environment.js +75 -0
  9. package/dist/ability/interop-v1.js +547 -0
  10. package/dist/ability/management.js +79 -0
  11. package/dist/ability/package.js +264 -0
  12. package/dist/ability/provider.js +73 -0
  13. package/dist/ability/publication.js +107 -0
  14. package/dist/ability/resources.js +106 -0
  15. package/dist/ability/runtime.js +212 -0
  16. package/dist/ability/secrets.js +47 -0
  17. package/dist/ability/store.js +112 -0
  18. package/dist/ability/toolchain.js +69 -0
  19. package/dist/ability/types.js +14 -0
  20. package/dist/ability/versions.js +32 -0
  21. package/dist/agents/baseagent.js +2 -2
  22. package/dist/agents/claude-runner.js +4 -0
  23. package/dist/agents/codex-runner.js +81 -17
  24. package/dist/agents/ecagent-plugin-lazy.js +41 -0
  25. package/dist/agents/ecagent-runner.js +18 -11
  26. package/dist/aun/ability-device-routing.js +12 -1
  27. package/dist/aun/aid/agentmd.js +2 -2
  28. package/dist/aun/aid/client.js +1 -1
  29. package/dist/aun/aid/identity.js +45 -0
  30. package/dist/aun/aid/index.js +1 -0
  31. package/dist/aun/aid/managed-operation.js +73 -2
  32. package/dist/channels/aun.js +64 -18
  33. package/dist/channels/builtin-plugins.js +14 -0
  34. package/dist/channels/dingtalk.js +78 -26
  35. package/dist/channels/feishu.js +89 -14
  36. package/dist/channels/qqbot.js +84 -19
  37. package/dist/channels/wechat.js +77 -19
  38. package/dist/channels/wecom.js +67 -22
  39. package/dist/cli/ability-command.js +92 -0
  40. package/dist/cli/aun-commands.js +124 -85
  41. package/dist/cli/daemon-commands.js +37 -85
  42. package/dist/cli/index.js +14 -0
  43. package/dist/cli/init.js +11 -13
  44. package/dist/cli/managed-command-guard.js +6 -0
  45. package/dist/cli/model.js +101 -104
  46. package/dist/cli/provider-command.js +6 -4
  47. package/dist/cli/restart-monitor.js +52 -11
  48. package/dist/cli/upgrade-command.js +102 -0
  49. package/dist/cli/version.js +1 -1
  50. package/dist/config/access-policy.js +4 -2
  51. package/dist/config/builtin-roles.js +1 -0
  52. package/dist/config/config-field-policy.js +4 -0
  53. package/dist/config/config-manager.js +7 -0
  54. package/dist/config/provider-ipc-service.js +10 -0
  55. package/dist/config/providers-config.js +12 -3
  56. package/dist/config/providers-management.js +45 -9
  57. package/dist/config/schema-migration.js +40 -22
  58. package/dist/contracts/ecweb-service-protocol.js +2 -1
  59. package/dist/core/agent-runtime.js +2 -1
  60. package/dist/core/auth/agent-delegation.js +21 -5
  61. package/dist/core/auth/auth-gateway.js +31 -9
  62. package/dist/core/auth/authorization-audit.js +52 -4
  63. package/dist/core/auth/delegation-authorization.js +140 -4
  64. package/dist/core/auth/operation-authorizer.js +114 -13
  65. package/dist/core/auth/operation-catalog.js +118 -4
  66. package/dist/core/baseagent-loader.js +14 -1
  67. package/dist/core/channel-loader.js +47 -9
  68. package/dist/core/channel-runtime.js +1 -1
  69. package/dist/core/command/agent-storage-menu.js +1 -1
  70. package/dist/core/command/cli-intent-parser.js +26 -13
  71. package/dist/core/command/command-handler.js +232 -76
  72. package/dist/core/command/connect-menu.js +10 -4
  73. package/dist/core/command/daemon-diagnostics.js +3 -3
  74. package/dist/core/command/data-root-resolver.js +2 -3
  75. package/dist/core/command/menu-catalog.js +10 -3
  76. package/dist/core/command/menu-handler.js +321 -46
  77. package/dist/core/command/menu-protocol.js +53 -7
  78. package/dist/core/command/pa-workspace-calendar.js +1 -2
  79. package/dist/core/command/pa-workspace-items.js +486 -0
  80. package/dist/core/command/pa-workspace-store.js +10 -1
  81. package/dist/core/command/slash-gate.js +2 -2
  82. package/dist/core/command/slash-handler.js +67 -25
  83. package/dist/core/contact-bind-registry.js +27 -0
  84. package/dist/core/daemon-control.js +3 -3
  85. package/dist/core/daemon-lifecycle.js +2 -1
  86. package/dist/core/event-bus.js +9 -2
  87. package/dist/core/handoff/ipc-registration.js +1 -0
  88. package/dist/core/host-snapshot.js +1 -2
  89. package/dist/core/initialization/service.js +32 -11
  90. package/dist/core/ipc-registration.js +18 -5
  91. package/dist/core/memory/consolidation-context.js +2 -2
  92. package/dist/core/message/aun-request-registry.js +99 -18
  93. package/dist/core/message/im-renderer.js +16 -11
  94. package/dist/core/message/message-admission.js +25 -20
  95. package/dist/core/message/message-bridge.js +21 -47
  96. package/dist/core/message/message-queue.js +3 -0
  97. package/dist/core/message/response-engine.js +7 -5
  98. package/dist/core/model/catalog-service.js +1 -1
  99. package/dist/core/permission/ec-command-parser.js +41 -9
  100. package/dist/core/permission/permission-result.js +1 -0
  101. package/dist/core/permission/protected-paths.js +25 -14
  102. package/dist/core/permission/tool-policy.js +108 -107
  103. package/dist/core/plugin-lifecycle.js +133 -0
  104. package/dist/core/runner-reload-transaction.js +4 -1
  105. package/dist/core/system-session/memory.js +16 -3
  106. package/dist/core/task/task-activity-store.js +50 -0
  107. package/dist/core/task/task-image-resources.js +140 -0
  108. package/dist/core/thread/ipc-operation.js +1 -1
  109. package/dist/core/thread/thread-service.js +0 -1
  110. package/dist/directory/canonical-digest.js +5 -3
  111. package/dist/directory/owner-directory-admission.js +22 -2
  112. package/dist/directory/owner-directory-cache.js +394 -60
  113. package/dist/directory/owner-directory-markdown.js +29 -2
  114. package/dist/directory/owner-directory-scope.js +35 -16
  115. package/dist/ecweb/basic-settings-service.js +4 -1
  116. package/dist/ecweb/pairing.js +41 -0
  117. package/dist/ecweb/providers-service.js +8 -1
  118. package/dist/{utils/ecweb-utils.js → ecweb/runtime/launch.js} +3 -27
  119. package/dist/ecweb/runtime/lifecycle.js +184 -0
  120. package/dist/{utils/ecweb-supervisor.js → ecweb/runtime/supervisor.js} +32 -27
  121. package/dist/index.js +34 -25
  122. package/dist/ipc.js +124 -7
  123. package/dist/response-system/engines/v1/proactive-flow.js +1 -1
  124. package/dist/trigger/authorization.js +2 -2
  125. package/dist/utils/atomic-write.js +24 -0
  126. package/dist/utils/avatar-upload.js +3 -1
  127. package/dist/utils/cross-platform.js +31 -2
  128. package/dist/utils/host-info.js +36 -0
  129. package/dist/utils/instance-registry.js +38 -11
  130. package/dist/utils/logger.js +9 -0
  131. package/dist/utils/{process-tree-stats.js → process-tree.js} +29 -0
  132. package/dist/utils/tool-summary.js +9 -1
  133. package/dist/utils/upgrade-jobs.js +96 -15
  134. package/dist/utils/windows-autostart.js +1 -1
  135. package/ecagent/README.md +19 -0
  136. package/ecagent/dist/harness/agent-harness.js +9 -0
  137. package/ecagent/dist/harness/env/nodejs.js +71 -11
  138. package/ecagent/dist/harness/env/windows-shell.d.ts +7 -0
  139. package/ecagent/dist/harness/env/windows-shell.js +132 -0
  140. package/kits/docs/aun/ABILITY_CALLING.md +38 -9
  141. package/kits/docs/evolcore/INDEX.md +5 -1
  142. package/kits/docs/evolcore/ability.md +181 -0
  143. package/kits/docs/evolcore/aid.md +20 -0
  144. package/kits/docs/evolcore/config.md +10 -6
  145. package/kits/docs/evolcore/menu-protocol.md +40 -1
  146. package/kits/docs/evolcore/provider.md +2 -2
  147. package/kits/docs/evolcore/tool-authorization.md +270 -0
  148. package/kits/runtime/ability-job.ps1 +41 -0
  149. package/kits/runtime/ability-runner.mjs +67 -0
  150. package/kits/runtime/ability-secret.ps1 +59 -0
  151. package/kits/runtime/ability-templates/go/main.go +59 -0
  152. package/kits/runtime/ability-templates/java/Json.java +67 -0
  153. package/kits/runtime/ability-templates/java/Runner.java +42 -0
  154. package/kits/runtime/ability-templates/python/runner.py +48 -0
  155. package/kits/runtime/ability-templates/rust/json.rs +87 -0
  156. package/kits/runtime/ability-templates/rust/runner.rs +35 -0
  157. package/kits/schemas/_meta.json +12 -1
  158. package/kits/schemas/ability-plugin.schema.1.json +107 -0
  159. package/kits/schemas/ability-project.schema.1.json +31 -0
  160. package/kits/schemas/agent-config.schema.16.json +20 -0
  161. package/kits/schemas/agent-config.schema.17.json +20 -0
  162. package/kits/schemas/agent-config.schema.18.json +917 -0
  163. package/kits/skills/.switches.json +4 -0
  164. package/kits/skills/aid-ability/SKILL.md +5 -4
  165. package/kits/skills/ec-ability/SKILL.md +67 -0
  166. package/kits/skills/ec-ability/references/contract-checklist.md +37 -0
  167. package/kits/skills/ec-ability/references/development.md +104 -0
  168. package/kits/skills/ec-ability/references/management.md +117 -0
  169. package/kits/skills/ec-ability/references/recovery.md +27 -0
  170. package/kits/skills/ec-ability/references/runtime-protocol.md +109 -0
  171. package/kits/skills/ec-ability/references/workflows.md +15 -0
  172. package/kits/skills/ec-service-proxy/SKILL.md +12 -0
  173. package/kits/skills/personal-assistant/SKILL.md +240 -6
  174. package/kits/skills/personal-assistant/references/02-bootstrap.md +78 -4
  175. package/kits/skills/personal-assistant/scripts/clean.mjs +397 -0
  176. package/kits/skills/personal-assistant/scripts/init.mjs +113 -25
  177. package/kits/skills/personal-assistant/scripts/lock.mjs +189 -0
  178. package/kits/skills/personal-assistant/scripts/migrate.mjs +35 -10
  179. package/kits/skills/personal-assistant/scripts/verify.mjs +2 -1
  180. package/kits/skills/personal-assistant/templates/persona-section.md +54 -0
  181. package/kits/skills/personal-assistant/triggers/ingest-daily.json +1 -1
  182. package/kits/templates/memory-consolidation/notes.md +1 -1
  183. package/kits/templates/system-fragments/channel.md +2 -1
  184. package/kits/templates/system-fragments/commands.md +1 -0
  185. package/package.json +5 -3
  186. package/dist/core/command/data-root-error.js +0 -10
  187. package/dist/utils/machine-info.js +0 -46
  188. package/dist/utils/process-tree-worker.js +0 -31
  189. package/dist/utils/windows-output.js +0 -36
@@ -0,0 +1,882 @@
1
+ import path from 'node:path';
2
+ import { randomUUID, createHash } from 'node:crypto';
3
+ import canonicalize from 'canonicalize';
4
+ import Ajv from 'ajv';
5
+ import { AbilityStore } from './store.js';
6
+ import { acquireAbilityPackage, materializeDefinition, validateAbilityConfig } from './package.js';
7
+ import { AbilityRunner, runtimeDescriptor } from './runtime.js';
8
+ import { AbilitySecrets } from './secrets.js';
9
+ import { resourceCall, validateResourceGrant } from './resources.js';
10
+ import { consumeGrant, executionGrant, grantState, validateRemoteGrant } from './authorization.js';
11
+ import { assertPackageVersion, sameJson, versionImpact } from './versions.js';
12
+ import { abilityReleaseId, abilitySummary, buildAbilityIndex, operationFingerprint, operationKey, sha256Hex } from './interop-v1.js';
13
+ import { AbilityError, abilityAssert } from './types.js';
14
+ const ajv = new Ajv({ strict: false, allErrors: true, addUsedSchema: false });
15
+ const RESULT_RETENTION_MS = 7 * 86400000;
16
+ const ACTIONS = ['read', 'result-read', 'install', 'configure', 'enable', 'disable', 'invoke', 'publish', 'upgrade', 'rollback', 'uninstall', 'grant', 'retire'];
17
+ /** One daemon-owned service shared by CLI, ECWeb and the AUN Provider adapter. */
18
+ export class AbilityApplicationService {
19
+ host;
20
+ store;
21
+ secrets;
22
+ runners = new Map();
23
+ active = new Map();
24
+ flights = new Map();
25
+ executions = new Set();
26
+ publications = new Map();
27
+ closed = false;
28
+ accepting = true;
29
+ constructor(root, host) {
30
+ this.host = host;
31
+ this.store = new AbilityStore(root);
32
+ this.secrets = new AbilitySecrets(path.join(root, 'secrets'));
33
+ this.store.transaction(() => {
34
+ for (const transition of this.store.list('transition')) {
35
+ const prior = transition.previous;
36
+ prior.revision = (this.store.get('instance', prior.id)?.revision ?? prior.revision) + 1;
37
+ this.store.put('instance', prior.id, prior.target.aid, prior, prior.revision);
38
+ this.store.remove('transition', prior.id);
39
+ }
40
+ for (const job of this.store.list('job'))
41
+ if (job.state === 'running') {
42
+ job.state = 'failed';
43
+ job.stage = 'interrupted';
44
+ job.updatedAt = Date.now();
45
+ job.error = { code: 'JOB_INTERRUPTED', message: 'Daemon stopped; inspect state before a new command' };
46
+ this.store.put('job', job.id, job.targetAid, job);
47
+ }
48
+ for (const operation of this.store.list('invocation'))
49
+ if (operation.state === 'executing') {
50
+ operation.state = 'unknown';
51
+ operation.updatedAt = Date.now();
52
+ operation.error = { code: 'EXECUTION_UNKNOWN', message: 'Daemon exited while execution was active' };
53
+ this.store.put('invocation', operation.id, operation.targetAid, operation);
54
+ }
55
+ for (const instance of this.store.list('instance'))
56
+ if (!instance.deletedAt) {
57
+ instance.runtimeState = 'stopped';
58
+ if (instance.publishedPaths.length)
59
+ instance.publicationState = 'degraded';
60
+ this.store.put('instance', instance.id, instance.target.aid, instance, instance.revision);
61
+ this.markPublicationDirty(instance.target.aid, instance.publishedPaths.length > 0);
62
+ }
63
+ });
64
+ }
65
+ async targets(actor) {
66
+ const result = [];
67
+ for (const target of this.host.targets()) {
68
+ const operations = [];
69
+ for (const action of ACTIONS)
70
+ if (await this.host.authorize(actor, target, action))
71
+ operations.push(action);
72
+ if (operations.includes('read'))
73
+ result.push({ ...target, operations });
74
+ }
75
+ return result;
76
+ }
77
+ async authorize(actor, aid, action) {
78
+ abilityAssert(!this.closed, 'SERVICE_CLOSED', 'Ability service is closing', 503);
79
+ const target = this.host.targets().find(item => item.aid === aid);
80
+ abilityAssert(target, 'TARGET_NOT_FOUND', 'AID is not managed by this daemon', 404);
81
+ abilityAssert(await this.host.authorize(actor, target, action), 'PERMISSION_DENIED', 'Operation is not authorized for this AID', 403);
82
+ return target;
83
+ }
84
+ instance(aid, id, deleted = false) {
85
+ const value = this.store.get('instance', id);
86
+ abilityAssert(value && value.target.aid === aid && (deleted || !value.deletedAt), 'INSTANCE_NOT_FOUND', 'Instance is not available under this AID', 404);
87
+ return value;
88
+ }
89
+ pkg(instance) {
90
+ const pkg = this.store.get('package', instance.packageDigest);
91
+ abilityAssert(pkg, 'PACKAGE_NOT_FOUND', 'Instance package is unavailable', 503);
92
+ return { ...pkg, source: instance.source ?? pkg.source };
93
+ }
94
+ view(instance) {
95
+ const pkg = this.pkg(instance);
96
+ const definitions = pkg.definitions.map(item => materializeDefinition(item.definition, instance.semanticRevision));
97
+ const grants = instance.grants.map(grant => {
98
+ let status = grantState(instance, grant, this.store);
99
+ const scope = grant.value;
100
+ if (status === 'active' && grant.permission === 'remote-call' && !definitions.some(row => row.path === scope.path && row.definition_id === scope.definitionId))
101
+ status = 'contract_changed';
102
+ return { ...grant, status, usage: this.store.get('grant-usage', grant.id) ?? { calls: 0, totals: {} } };
103
+ });
104
+ return { ...instance, grants, source: pkg.source, secretBackend: this.secrets.backend, secretBackendStatus: this.secrets.status, secretSlots: Object.keys(instance.secretRefs ?? {}), pluginId: pkg.manifest.id, version: pkg.manifest.version, manifest: pkg.manifest, configSchema: pkg.configSchema,
105
+ executionProfile: 'trusted-subprocess', abilities: pkg.definitions.map(item => ({ ...materializeDefinition(item.definition, instance.semanticRevision), handler: item.handler,
106
+ usage: item.usage, published: instance.publishedPaths.includes(String(item.definition.path)) })) };
107
+ }
108
+ async list(actor, aid) {
109
+ await this.authorize(actor, aid, 'read');
110
+ return this.store.list('instance', aid).filter(item => !item.deletedAt).map(item => this.view(item));
111
+ }
112
+ async show(actor, aid, id) { await this.authorize(actor, aid, 'read'); return this.view(this.instance(aid, id)); }
113
+ async context(actor, aid) {
114
+ const target = await this.authorize(actor, aid, 'read');
115
+ const operations = [];
116
+ for (const action of ACTIONS)
117
+ if (await this.host.authorize(actor, target, action))
118
+ operations.push(action);
119
+ const codeApprovalPolicy = this.host.codeApprovalPolicy?.(target) ?? { enabled: true, source: 'host-default' };
120
+ return { targetAid: aid, targetKind: target.kind, operations,
121
+ canApproveCode: codeApprovalPolicy.enabled && (this.host.canApproveCode
122
+ ? await this.host.canApproveCode(actor, aid)
123
+ : this.host.approveCode ? await this.host.approveCode(actor) : false),
124
+ codeApprovalPolicy,
125
+ selfManagementPolicy: 'not-implemented', authorization: 'current-owner-and-task-delegation' };
126
+ }
127
+ async status(actor, aid, id) {
128
+ await this.authorize(actor, aid, 'read');
129
+ const rows = id ? [this.instance(aid, id)] : this.store.list('instance', aid).filter(item => !item.deletedAt);
130
+ const publication = this.store.get('publication', aid);
131
+ const instances = rows.map(instance => {
132
+ const pkg = this.pkg(instance);
133
+ return { id: instance.id, name: instance.name, revision: instance.revision, pluginId: pkg.manifest.id, version: pkg.manifest.version,
134
+ packageDigest: instance.packageDigest, desiredState: instance.desiredState, runtimeState: instance.runtimeState,
135
+ runnerPresent: this.runners.has(instance.id), trustedCodeApproved: instance.trustedCodeApproved,
136
+ publicationState: instance.publicationState, publishedPaths: instance.publishedPaths, error: instance.error,
137
+ runtime: runtimeDescriptor(pkg) };
138
+ });
139
+ // A completed empty index is as important as a completed nonempty index.
140
+ const publicationConverged = publication?.state !== 'pending' && instances.every(row => row.publishedPaths.length ? row.publicationState === 'published' : row.publicationState === 'unpublished');
141
+ return { targetAid: aid, publicationConverged,
142
+ publication: { state: publication?.state ?? 'idle', revision: publication?.revision ?? 0, updatedAt: publication?.updatedAt, error: publication?.error }, instances };
143
+ }
144
+ async doctor(actor, aid, id) {
145
+ const status = await this.status(actor, aid, id);
146
+ const diagnostics = [];
147
+ if (status.publication.state === 'pending')
148
+ diagnostics.push({ code: 'PUBLICATION_PENDING', severity: 'warning',
149
+ message: 'AUN publication has not been confirmed.', suggestion: 'Check target AUN connectivity and index ownership; the daemon reconciles the same durable intent.' });
150
+ for (const row of status.instances) {
151
+ const instance = this.instance(aid, row.id);
152
+ const pkg = this.pkg(instance);
153
+ const add = (code, severity, message, suggestion) => diagnostics.push({ code, severity, instanceId: row.id, message, suggestion });
154
+ if (!instance.trustedCodeApproved)
155
+ add('CODE_APPROVAL_REQUIRED', 'warning', 'Executable code has not been approved.', 'Ask an authorized target Owner and host operator to review and enable this exact package.');
156
+ if (instance.desiredState === 'enabled' && (instance.runtimeState !== 'ready' || !this.runners.has(instance.id)))
157
+ add('RUNTIME_NOT_READY', 'error', 'The enabled instance has no ready runner.', 'Inspect the original enable/upgrade job and package before submitting a new action.');
158
+ if (instance.runtimeState === 'failed')
159
+ add('RUNTIME_FAILED', 'error', 'The last runtime activation failed.', 'Review package entry, readiness and required resource grants; query the original job.');
160
+ if (row.runtime.executableExists === false)
161
+ add('RUNTIME_EXECUTABLE_MISSING', 'error', 'The runtime executable is not available at its configured path or on PATH.', 'Configure the required runtime externally, or update the reviewed process-rpc command and create a new immutable package. EvolCore does not install environments.');
162
+ if (row.runtime.processTreeIsolation === 'direct-spawn')
163
+ add('PROCESS_TREE_ISOLATION_LIMITED', 'warning', 'This process-rpc runtime uses direct spawn on Windows.', 'Use a trusted host policy until the generic process-rpc Job Object host is deployed.');
164
+ if (instance.publishedPaths.length && instance.desiredState !== 'enabled')
165
+ add('PUBLISHED_INSTANCE_DISABLED', 'warning', 'Publication is selected but the instance is disabled.', 'Enable the reviewed instance, or explicitly unpublish it.');
166
+ const missingSecrets = pkg.manifest.permissions.secretSlots.filter(slot => !instance.secretRefs?.[slot]);
167
+ if (missingSecrets.length)
168
+ add('SECRET_SLOTS_MISSING', 'warning', 'Required secret slots are not configured: ' + missingSecrets.join(', '), 'Use the authorized secrets --stdin command when the secret backend is available.');
169
+ if (pkg.manifest.permissions.secretSlots.length && this.secrets.status !== 'ready')
170
+ add('SECRET_BACKEND_UNAVAILABLE', 'warning', 'The secret backend is not verified available.', 'Deploy a supported backend consistent with host policy.');
171
+ const grants = instance.grants.filter(grant => grantState(instance, grant, this.store) === 'active');
172
+ if (pkg.manifest.permissions.workspace !== 'none' && !grants.some(grant => grant.permission === 'workspace'))
173
+ add('WORKSPACE_GRANT_MISSING', 'warning', 'No active workspace grant is present.', 'Ask the Owner to authorize the required directory scope.');
174
+ if (pkg.manifest.permissions.networkOrigins.length && !grants.some(grant => grant.permission === 'http'))
175
+ add('HTTP_GRANT_MISSING', 'warning', 'No active HTTPS grant is present.', 'Ask the Owner to authorize the declared origins.');
176
+ }
177
+ return { ...status, healthy: !diagnostics.some(row => row.severity !== 'info'), diagnostics, checks: 'stored-state-and-runner-presence',
178
+ limitations: ['No business invocation or external connectivity probe was performed.', 'Static diagnostics do not establish end-to-end AUN availability.'] };
179
+ }
180
+ async preview(actor, aid, source, instanceId) {
181
+ const target = await this.authorize(actor, aid, instanceId ? 'upgrade' : 'install');
182
+ abilityAssert(typeof source === 'string' && source.length <= 2048, 'SOURCE_INVALID', 'Package source is required');
183
+ const current = instanceId ? this.instance(aid, instanceId) : undefined;
184
+ const pkg = await acquireAbilityPackage(source, path.join(this.store.root, 'objects/sha256'));
185
+ abilityAssert(pkg.manifest.targets.includes(target.kind), 'TARGET_UNSUPPORTED', 'Package does not support target type');
186
+ if (current)
187
+ abilityAssert(this.pkg(current).manifest.id === pkg.manifest.id, 'PLUGIN_MISMATCH', 'Upgrade must use the same plugin ID');
188
+ assertPackageVersion(this.store, pkg);
189
+ const preview = { id: randomUUID(), target, actorKey: actor.key, packageDigest: pkg.digest,
190
+ createdAt: Date.now(), expiresAt: Date.now() + 30 * 60000, source: pkg.source, ...(current ? { instanceId: current.id, revision: current.revision } : {}) };
191
+ this.store.transaction(() => { if (!this.store.get('package', pkg.digest))
192
+ this.store.put('package', pkg.digest, '', pkg); this.store.put('preview', preview.id, aid, preview); this.store.audit(actor.key, aid, 'preview', pkg.digest); });
193
+ return { ...preview, manifest: pkg.manifest, source: pkg.source, configSchema: pkg.configSchema, definitions: pkg.definitions, previous: current ? this.view(current) : undefined, impact: current ? versionImpact(current, this.pkg(current), pkg) : undefined };
194
+ }
195
+ previewFor(actor, aid, id, instanceId) {
196
+ const preview = typeof id === 'string' ? this.store.get('preview', id) : undefined;
197
+ abilityAssert(preview && preview.actorKey === actor.key && preview.target.aid === aid && preview.expiresAt > Date.now() && preview.instanceId === instanceId, 'PREVIEW_EXPIRED', 'Obtain a current package preview for this actor and AID', 409);
198
+ const pkg = this.store.get('package', preview.packageDigest);
199
+ return { preview, pkg: { ...pkg, source: preview.source ?? pkg.source } };
200
+ }
201
+ async submit(actor, aid, action, input) {
202
+ abilityAssert(this.accepting, 'SERVICE_CLOSED', 'Ability service is closing', 503);
203
+ abilityAssert(ACTIONS.includes(action) && action !== 'read' && action !== 'result-read', 'ACTION_UNSUPPORTED', 'Unsupported mutation');
204
+ await this.authorize(actor, aid, action);
205
+ abilityAssert(typeof input.commandId === 'string' && /^[A-Za-z0-9_-]{8,128}$/.test(input.commandId), 'COMMAND_ID_REQUIRED', 'A unique commandId is required');
206
+ const fingerprint = sha256Hex(canonicalize({ action, input }));
207
+ const priorId = this.store.commandJob(actor.key, aid, input.commandId);
208
+ if (priorId) {
209
+ const prior = this.store.get('job', priorId);
210
+ abilityAssert(prior.fingerprint === fingerprint, 'COMMAND_CONFLICT', 'commandId was used for different input', 409);
211
+ return this.jobView(actor, aid, prior);
212
+ }
213
+ const job = { id: randomUUID(), targetAid: aid, actorKey: actor.key, commandId: input.commandId, fingerprint, action,
214
+ state: 'running', stage: 'queued', instanceId: input.instanceId, createdAt: Date.now(), updatedAt: Date.now() };
215
+ this.store.transaction(() => { this.store.bindCommand(actor.key, aid, input.commandId, job.id); this.store.put('job', job.id, aid, job); this.store.audit(actor.key, aid, action + '.requested', job.id); });
216
+ const resource = aid;
217
+ const previous = this.flights.get(resource) ?? Promise.resolve();
218
+ const flight = previous.catch(() => { }).then(async () => {
219
+ try {
220
+ await this.authorize(actor, aid, action);
221
+ job.stage = 'executing';
222
+ this.store.put('job', job.id, aid, job);
223
+ job.result = await this.execute(actor, aid, action, input);
224
+ job.state = 'completed';
225
+ job.stage = 'completed';
226
+ }
227
+ catch (error) {
228
+ job.state = 'failed';
229
+ job.stage = 'failed';
230
+ job.error = { code: error instanceof AbilityError ? error.code : 'ABILITY_FAILED', message: error instanceof AbilityError ? error.message : 'Ability operation failed; inspect diagnostics' };
231
+ }
232
+ job.updatedAt = Date.now();
233
+ this.store.transaction(() => { this.store.put('job', job.id, aid, job); this.store.audit(actor.key, aid, action + '.' + job.state, job.id); });
234
+ });
235
+ this.flights.set(resource, flight);
236
+ void flight.then(() => { if (this.flights.get(resource) === flight)
237
+ this.flights.delete(resource); }, () => { if (this.flights.get(resource) === flight)
238
+ this.flights.delete(resource); });
239
+ return { ...job };
240
+ }
241
+ async job(actor, aid, id, commandId) {
242
+ await this.authorize(actor, aid, 'read');
243
+ const job = this.store.get('job', id ?? this.store.commandJob(actor.key, aid, commandId ?? '') ?? '');
244
+ if (job?.targetAid !== aid || job.actorKey !== actor.key)
245
+ return undefined;
246
+ return this.jobView(actor, aid, job);
247
+ }
248
+ async jobView(actor, aid, job) {
249
+ if (job.action !== 'invoke')
250
+ return job;
251
+ const target = this.host.targets().find(target => target.aid === aid);
252
+ const canResults = await this.host.authorize(actor, target, 'result-read');
253
+ return { ...job, result: canResults && job.result ? this.resultView(job.result) : undefined };
254
+ }
255
+ async drain() { await Promise.all([...this.flights.values()]); }
256
+ save(instance, previous, actor, action) {
257
+ instance.revision = previous + 1;
258
+ instance.updatedAt = Date.now();
259
+ this.store.transaction(() => { this.store.put('instance', instance.id, instance.target.aid, instance, instance.revision, previous); this.store.audit(actor, instance.target.aid, action, instance.id); this.markPublicationDirty(instance.target.aid, instance.publishedPaths.length > 0); });
260
+ return instance;
261
+ }
262
+ async execute(actor, aid, action, input) {
263
+ if (action === 'install') {
264
+ if (input.approveTrustedCode === true) {
265
+ abilityAssert(this.host.codeApprovalPolicy?.(this.host.targets().find(target => target.aid === aid))?.enabled !== false, 'CODE_APPROVAL_DISABLED', 'Trusted ability code approval is disabled by the target Agent Owner', 403);
266
+ abilityAssert(!this.host.approveCode || await this.host.approveCode(actor), 'HOST_OPERATOR_REQUIRED', 'Trusted subprocess code approval requires a host operator', 403);
267
+ }
268
+ const { pkg } = this.previewFor(actor, aid, input.previewId);
269
+ assertPackageVersion(this.store, pkg);
270
+ abilityAssert(typeof input.name === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(input.name), 'INSTANCE_NAME_INVALID', 'Use a name of 1–64 letters, digits, underscores or hyphens');
271
+ const config = input.config ?? {};
272
+ validateAbilityConfig(pkg.configSchema, config);
273
+ const instance = { id: randomUUID(), target: await this.authorize(actor, aid, 'install'), name: input.name, packageDigest: pkg.digest, revision: 1,
274
+ config, source: pkg.source, desiredState: 'disabled', runtimeState: 'stopped', publicationState: 'unpublished', publishedPaths: [], semanticRevision: randomUUID(), generation: randomUUID(),
275
+ trustedCodeApproved: input.approveTrustedCode === true, approvedByAid: input.approveTrustedCode === true ? actor.aid : undefined, createdAt: Date.now(), updatedAt: Date.now(), grants: [] };
276
+ this.store.transaction(() => { this.store.claimName(aid, instance.name, instance.id); this.store.put('instance', instance.id, aid, instance); this.store.audit(actor.key, aid, 'installed', instance.id); });
277
+ return this.view(instance);
278
+ }
279
+ let instance = this.instance(aid, input.instanceId);
280
+ abilityAssert(Number.isSafeInteger(input.expectedRevision) && input.expectedRevision === instance.revision, 'REVISION_CONFLICT', 'Refresh instance before submitting', 409);
281
+ const previous = instance.revision;
282
+ if (action === 'retire') {
283
+ const historical = this.store.get('history', input.generation);
284
+ abilityAssert(historical?.id === instance.id && historical.target.aid === aid && input.generation !== instance.generation, 'GENERATION_NOT_FOUND', 'Select a historical rollback point for this instance');
285
+ this.store.remove('history', input.generation);
286
+ this.save(instance, previous, actor.key, 'history.retired');
287
+ await this.syncIfDirty(aid);
288
+ return this.view(instance);
289
+ }
290
+ if (action === 'enable') {
291
+ if (input.approveTrustedCode === true) {
292
+ abilityAssert(this.host.codeApprovalPolicy?.(this.host.targets().find(target => target.aid === aid))?.enabled !== false, 'CODE_APPROVAL_DISABLED', 'Trusted ability code approval is disabled by the target Agent Owner', 403);
293
+ abilityAssert(!this.host.approveCode || await this.host.approveCode(actor), 'HOST_OPERATOR_REQUIRED', 'Trusted subprocess code approval requires a host operator', 403);
294
+ }
295
+ abilityAssert(instance.trustedCodeApproved && instance.approvedByAid === actor.aid || input.approveTrustedCode === true, 'TRUST_APPROVAL_REQUIRED', 'Explicit trusted-subprocess approval is required', 403);
296
+ instance.trustedCodeApproved = true;
297
+ instance.approvedByAid = actor.aid;
298
+ instance.desiredState = 'enabled';
299
+ this.save(instance, previous, actor.key, action);
300
+ try {
301
+ await this.start(instance);
302
+ }
303
+ catch (error) {
304
+ const failed = this.instance(aid, instance.id);
305
+ failed.desiredState = 'disabled';
306
+ failed.runtimeState = 'failed';
307
+ failed.error = error instanceof AbilityError ? `${error.code}: ${error.message}` : 'ABILITY_FAILED: Ability operation failed; inspect diagnostics';
308
+ this.save(failed, failed.revision, actor.key, 'enable.failed');
309
+ throw error;
310
+ }
311
+ if (instance.publishedPaths.length)
312
+ await this.syncPublication(aid);
313
+ return this.view(this.instance(aid, instance.id));
314
+ }
315
+ if (action === 'disable' || action === 'uninstall') {
316
+ instance.desiredState = 'disabled';
317
+ instance.runtimeState = 'draining';
318
+ if (action === 'uninstall') {
319
+ instance.publishedPaths = [];
320
+ instance.publicationState = 'revoking';
321
+ }
322
+ this.save(instance, previous, actor.key, action);
323
+ await this.stop(instance.id);
324
+ instance = this.instance(aid, instance.id);
325
+ const rev = instance.revision;
326
+ instance.runtimeState = 'stopped';
327
+ if (action === 'uninstall') {
328
+ instance.deletedAt = Date.now();
329
+ instance.publicationState = 'unpublished';
330
+ }
331
+ this.store.transaction(() => { this.save(instance, rev, actor.key, action + '.stopped'); if (action === 'uninstall')
332
+ this.store.releaseName(instance.id); });
333
+ await this.syncIfDirty(aid);
334
+ return this.view(instance);
335
+ }
336
+ if (action === 'configure' || action === 'upgrade' || action === 'rollback') {
337
+ const previousActivation = structuredClone(instance);
338
+ if (action === 'configure' && !input.secret) {
339
+ validateAbilityConfig(this.pkg(instance).configSchema, input.config);
340
+ if (sameJson(input.config, instance.config))
341
+ return this.view(instance);
342
+ }
343
+ if (input.secret) {
344
+ abilityAssert(action === 'configure' && this.pkg(instance).manifest.permissions.secretSlots.includes(input.secret.slot), 'SECRET_SLOT_INVALID', 'Secret slot is not declared');
345
+ input.config = instance.config;
346
+ }
347
+ const candidate = action === 'configure' ? this.pkg(instance) : action === 'upgrade' ? this.previewFor(actor, aid, input.previewId, instance.id).pkg
348
+ : this.store.get('package', this.store.get('history', input.generation)?.packageDigest ?? '');
349
+ abilityAssert(candidate, 'GENERATION_NOT_FOUND', 'Previous generation is unavailable');
350
+ const old = action === 'rollback' ? this.store.get('history', input.generation) : instance;
351
+ abilityAssert(old?.target.aid === aid && old.id === instance.id, 'GENERATION_NOT_FOUND', 'Generation does not belong to this instance');
352
+ if (action === 'upgrade') {
353
+ abilityAssert(this.host.codeApprovalPolicy?.(this.host.targets().find(target => target.aid === aid))?.enabled !== false, 'CODE_APPROVAL_DISABLED', 'Trusted ability code approval is disabled by the target Agent Owner', 403);
354
+ abilityAssert(!this.host.approveCode || await this.host.approveCode(actor), 'HOST_OPERATOR_REQUIRED', 'New executable code requires host operator approval', 403);
355
+ const preview = this.previewFor(actor, aid, input.previewId, instance.id).preview;
356
+ abilityAssert(preview.revision === previous, 'REVISION_CONFLICT', 'Upgrade preview is stale', 409);
357
+ abilityAssert(input.approveTrustedCode === true, 'TRUST_APPROVAL_REQUIRED', 'Review and approve the candidate package', 403);
358
+ assertPackageVersion(this.store, candidate);
359
+ const impact = versionImpact(instance, this.pkg(instance), candidate);
360
+ abilityAssert(!impact.downgrade || input.approveDowngrade === true, 'DOWNGRADE_APPROVAL_REQUIRED', 'A lower version requires explicit downgrade approval', 409);
361
+ abilityAssert(!(impact.removedPaths.length || impact.changedPaths.length || impact.configSchemaChanged || impact.permissionsChanged) || input.approveCompatibilityChange === true, 'COMPATIBILITY_APPROVAL_REQUIRED', 'Review and approve contract, configuration and permission changes', 409);
362
+ const priorSource = this.pkg(instance).source;
363
+ abilityAssert(priorSource.kind === candidate.source.kind && (priorSource.kind === 'local' ? priorSource.locator === candidate.source.locator : priorSource.locator.split('@')[0] === candidate.source.locator.split('@')[0]) || input.approveSourceChange === true, 'SOURCE_APPROVAL_REQUIRED', 'Source changes require explicit approval', 403);
364
+ }
365
+ const config = action === 'configure' ? input.config : action === 'upgrade' ? input.config ?? old.config : old.config;
366
+ validateAbilityConfig(candidate.configSchema, config);
367
+ if (action === 'upgrade' && candidate.digest === instance.packageDigest && sameJson(config, instance.config))
368
+ return this.view(instance);
369
+ const impact = versionImpact(instance, this.pkg(instance), candidate);
370
+ abilityAssert(!impact.externalDataWarning || input.acknowledgeExternalData === true, 'EXTERNAL_DATA_ACK_REQUIRED', 'Workspace files are not rolled back; confirm operator-managed backup and migration', 409);
371
+ if (input.secret) {
372
+ const handle = randomUUID();
373
+ await this.secrets.set(instance.id, input.secret.slot, handle, input.secret.value);
374
+ instance.secretRefs = { ...instance.secretRefs, [input.secret.slot]: handle };
375
+ }
376
+ const prior = previousActivation;
377
+ const wasEnabled = instance.desiredState === 'enabled';
378
+ this.store.put('transition', instance.id, aid, { previous: prior });
379
+ try {
380
+ instance.runtimeState = 'draining';
381
+ this.store.transaction(() => {
382
+ this.store.put('instance', instance.id, aid, instance, previous);
383
+ this.markPublicationDirty(aid, instance.publishedPaths.length > 0);
384
+ });
385
+ await this.stop(instance.id);
386
+ this.store.put('history', instance.generation, aid, previousActivation);
387
+ instance.packageDigest = candidate.digest;
388
+ instance.config = config;
389
+ instance.semanticRevision = randomUUID();
390
+ instance.generation = randomUUID();
391
+ instance.runtimeState = 'stopped';
392
+ instance.dataGeneration = randomUUID();
393
+ this.store.checkpointKv(action === 'rollback' ? old : previousActivation, instance);
394
+ instance.source = action === 'rollback' ? old.source : candidate.source;
395
+ if (action === 'upgrade') {
396
+ instance.approvedByAid = actor.aid;
397
+ instance.trustedCodeApproved = true;
398
+ }
399
+ if (action === 'rollback')
400
+ instance.secretRefs = old.secretRefs;
401
+ instance.publishedPaths = instance.publishedPaths.filter(value => candidate.definitions.some(item => item.definition.path === value));
402
+ if (instance.publishedPaths.length)
403
+ instance.publicationState = 'degraded';
404
+ this.save(instance, previous, actor.key, action);
405
+ let migration;
406
+ if (action === 'upgrade' && impact.data.migrationRequired) {
407
+ const values = this.store.kvValues(instance);
408
+ abilityAssert(Buffer.byteLength(JSON.stringify(values)) <= 524288, 'DATA_MIGRATION_TOO_LARGE', 'KV migration is limited to 512 KiB; export and migrate larger stores explicitly');
409
+ if (Object.keys(values).length)
410
+ migration = { fromVersion: impact.data.fromVersion, toVersion: impact.data.toVersion, values };
411
+ }
412
+ if (wasEnabled || migration) {
413
+ await this.start(instance, migration);
414
+ if (!wasEnabled) {
415
+ await this.stop(instance.id);
416
+ instance.runtimeState = 'stopped';
417
+ this.store.put('instance', instance.id, aid, instance, instance.revision);
418
+ }
419
+ }
420
+ }
421
+ catch (error) {
422
+ await this.stop(instance.id);
423
+ prior.revision = instance.revision + 1;
424
+ prior.runtimeState = 'stopped';
425
+ prior.error = 'Candidate failed; previous generation restored';
426
+ this.store.put('instance', prior.id, aid, prior, prior.revision);
427
+ this.store.remove('transition', instance.id);
428
+ if (wasEnabled)
429
+ try {
430
+ await this.start(prior);
431
+ }
432
+ catch { /* persisted failed state */ }
433
+ this.markPublicationDirty(aid, prior.publishedPaths.length > 0);
434
+ throw error;
435
+ }
436
+ this.store.remove('transition', instance.id);
437
+ await this.syncIfDirty(aid);
438
+ return this.view(this.instance(aid, instance.id));
439
+ }
440
+ if (action === 'grant') {
441
+ if (input.approvalId) {
442
+ const approval = this.store.get('approval', input.approvalId);
443
+ abilityAssert(approval && approval.targetAid === aid && approval.instanceId === instance.id && this.approvalView(approval).status === 'pending', 'APPROVAL_UNAVAILABLE', 'Approval requires a pending request, current contract and an active grant', 409);
444
+ abilityAssert(['approved', 'denied'].includes(input.decision), 'APPROVAL_INVALID', 'Select approved or denied');
445
+ const definition = this.pkg(instance).definitions.find(row => row.definition.path === approval.path);
446
+ abilityAssert(definition && materializeDefinition(definition.definition, instance.semanticRevision).definition_id === approval.definitionId, 'CONTRACT_CHANGED', 'Approval contract has changed', 409);
447
+ approval.state = input.decision;
448
+ approval.decidedBy = actor.key;
449
+ this.store.put('approval', approval.id, aid, approval);
450
+ this.save(instance, previous, actor.key, 'approval.' + input.decision);
451
+ await this.syncIfDirty(aid);
452
+ return this.view(instance);
453
+ }
454
+ let resourceBinding = input.permission === 'workspace' || input.permission === 'http';
455
+ if (input.revokeId) {
456
+ const grant = instance.grants.find(value => value.id === input.revokeId);
457
+ abilityAssert(grant, 'GRANT_NOT_FOUND', 'Grant not found', 404);
458
+ grant.revokedAt = Date.now();
459
+ resourceBinding = grant.permission === 'workspace' || grant.permission === 'http';
460
+ }
461
+ else {
462
+ abilityAssert(['storage', 'remote-call', 'workspace', 'http'].includes(input.permission), 'PERMISSION_UNSUPPORTED', 'Unsupported resource grant');
463
+ abilityAssert(typeof input.expiresAt === 'number' && input.expiresAt > Date.now() && input.expiresAt <= Date.now() + 365 * 86400000, 'EXPIRY_REQUIRED', 'Grant needs an expiry within one year');
464
+ if (input.permission === 'remote-call') {
465
+ abilityAssert(input.confirmed === true, 'CONFIRMATION_REQUIRED', 'Confirm a caller, path and immutable definition');
466
+ validateRemoteGrant(input.value, this.pkg(instance), this.pkg(instance).definitions.map(row => materializeDefinition(row.definition, instance.semanticRevision)));
467
+ }
468
+ validateResourceGrant(input.permission, input.value, this.pkg(instance));
469
+ instance.grants.push({ id: randomUUID(), permission: input.permission, value: input.value ?? true, createdAt: Date.now(), expiresAt: input.expiresAt, issuedByAid: actor.aid });
470
+ }
471
+ if (resourceBinding) {
472
+ const prior = this.instance(aid, instance.id);
473
+ this.store.put('history', prior.generation, aid, prior);
474
+ instance.semanticRevision = randomUUID();
475
+ instance.generation = randomUUID();
476
+ instance.dataGeneration = randomUUID();
477
+ this.store.checkpointKv(prior, instance);
478
+ if (instance.publishedPaths.length)
479
+ instance.publicationState = 'preparing';
480
+ }
481
+ this.save(instance, previous, actor.key, action);
482
+ await this.syncIfDirty(aid);
483
+ return this.view(instance);
484
+ }
485
+ if (action === 'publish') {
486
+ abilityAssert(this.host.publish, 'PUBLICATION_UNAVAILABLE', 'AUN publication backend is unavailable', 503);
487
+ abilityAssert(Array.isArray(input.paths) && input.paths.every((value) => typeof value === 'string' && this.pkg(instance).definitions.some(item => item.definition.path === value)), 'PATH_INVALID', 'Select registered ability paths');
488
+ if (input.paths.length)
489
+ abilityAssert(instance.runtimeState === 'ready', 'INSTANCE_NOT_READY', 'Enable the instance before publication', 409);
490
+ instance.publishedPaths = [...new Set(input.paths)];
491
+ instance.publicationState = input.paths.length ? 'preparing' : 'revoking';
492
+ this.save(instance, previous, actor.key, action);
493
+ await this.syncPublication(aid);
494
+ return this.view(this.instance(aid, instance.id));
495
+ }
496
+ if (action === 'invoke') {
497
+ abilityAssert(input.confirmed === true, 'CONFIRMATION_REQUIRED', 'Explicit confirmation of this local invocation is required', 403);
498
+ return this.invoke(actor.key, aid, instance.id, input.path, input.definitionId, input.params ?? {}, input.operationId ?? randomUUID(), { actor });
499
+ }
500
+ throw new AbilityError('ACTION_UNSUPPORTED', 'Unsupported Ability operation');
501
+ }
502
+ async start(instance, migration) {
503
+ await this.stop(instance.id);
504
+ const pkg = this.pkg(instance);
505
+ abilityAssert(!this.host.runtimeAuthorized || await this.host.runtimeAuthorized(instance), 'OWNER_REVALIDATION_REQUIRED', 'Code approval is not held by the current verified Owner', 403);
506
+ validateAbilityConfig(pkg.configSchema, instance.config);
507
+ const refs = instance.secretRefs ?? {};
508
+ for (const slot of pkg.manifest.permissions.secretSlots) {
509
+ abilityAssert(refs[slot], 'SECRET_UNAVAILABLE', 'Configure all declared secret slots before enabling', 503);
510
+ await this.secrets.get(instance.id, slot, refs[slot]);
511
+ }
512
+ for (const other of this.store.list('instance', instance.target.aid)) {
513
+ if (other.id !== instance.id && !other.deletedAt && other.desiredState === 'enabled')
514
+ abilityAssert(!this.pkg(other).definitions.some(left => pkg.definitions.some(right => left.definition.path === right.definition.path)), 'PATH_CONFLICT', 'Another enabled instance owns this AID/path', 409);
515
+ }
516
+ instance.runtimeState = 'starting';
517
+ this.store.put('instance', instance.id, instance.target.aid, instance, instance.revision);
518
+ const runner = new AbilityRunner((id, method, args) => this.broker(instance.id, id, method, args), () => {
519
+ if (this.closed)
520
+ return;
521
+ this.runners.delete(instance.id);
522
+ const current = this.store.get('instance', instance.id);
523
+ if (current && !this.closed) {
524
+ current.runtimeState = 'failed';
525
+ current.error = 'Runner exited';
526
+ if (current.publishedPaths.length)
527
+ current.publicationState = 'degraded';
528
+ this.store.transaction(() => { this.store.put('instance', current.id, current.target.aid, current, current.revision); this.markPublicationDirty(current.target.aid, current.publishedPaths.length > 0); });
529
+ }
530
+ });
531
+ try {
532
+ const migratedData = await runner.start(pkg, instance, migration);
533
+ if (migration) {
534
+ abilityAssert(migratedData, 'DATA_MIGRATION_REQUIRED', 'The plugin must return migrated KV values');
535
+ this.store.replaceKv(instance, migratedData);
536
+ }
537
+ this.runners.set(instance.id, runner);
538
+ instance.runtimeState = 'ready';
539
+ delete instance.error;
540
+ }
541
+ catch (error) {
542
+ await runner.close();
543
+ instance.runtimeState = 'failed';
544
+ instance.error = error instanceof AbilityError ? `${error.code}: ${error.message}` : 'Runner initialization failed';
545
+ this.store.put('instance', instance.id, instance.target.aid, instance, instance.revision);
546
+ this.markPublicationDirty(instance.target.aid, instance.publishedPaths.length > 0);
547
+ throw error;
548
+ }
549
+ this.store.put('instance', instance.id, instance.target.aid, instance, instance.revision);
550
+ this.markPublicationDirty(instance.target.aid, instance.publishedPaths.length > 0);
551
+ }
552
+ async stop(id) {
553
+ const runner = this.runners.get(id);
554
+ this.runners.delete(id);
555
+ if (!runner)
556
+ return;
557
+ const deadline = Date.now() + 5000;
558
+ while ([...this.active.values()].some(value => value.instanceId === id) && Date.now() < deadline)
559
+ await new Promise(resolve => setTimeout(resolve, 25));
560
+ if (![...this.active.values()].some(value => value.instanceId === id))
561
+ try {
562
+ await runner.call('shutdown', {}, 2000);
563
+ }
564
+ catch { /* force cleanup follows */ }
565
+ await runner.close();
566
+ }
567
+ validGrant(instance, permission) { return instance.grants.some(grant => grant.permission === permission && !grant.revokedAt && !!grant.expiresAt && grant.expiresAt > Date.now() && grant.issuedByAid === instance.approvedByAid); }
568
+ async broker(instanceId, invocationId, method, args) {
569
+ const active = this.active.get(invocationId);
570
+ const instance = this.store.get('instance', instanceId);
571
+ abilityAssert(active && active.instanceId === instanceId && instance && !instance.deletedAt && instance.desiredState === 'enabled' && active.generation === instance.generation, 'LEASE_EXPIRED', 'Invocation lease is no longer valid', 403);
572
+ abilityAssert(!this.host.runtimeAuthorized || await this.host.runtimeAuthorized(instance), 'OWNER_REVALIDATION_REQUIRED', 'Current Owner approval is required', 403);
573
+ abilityAssert(this.store.get('instance', instanceId)?.revision === instance.revision, 'LEASE_EXPIRED', 'Resource authorization changed', 403);
574
+ if (method === 'host.status')
575
+ return { ready: instance.runtimeState === 'ready' };
576
+ if (!method.startsWith('storage.')) {
577
+ const check = () => {
578
+ const current = this.store.get('instance', instanceId);
579
+ abilityAssert(this.active.has(invocationId) && current && current.desiredState === 'enabled' && current.generation === active.generation && current.revision === instance.revision, 'LEASE_EXPIRED', 'Resource authorization changed', 403);
580
+ };
581
+ this.store.audit('invocation:' + invocationId, instance.target.aid, method, instanceId);
582
+ return resourceCall(instance, this.pkg(instance), this.secrets, instance.secretRefs ?? {}, method, args, check);
583
+ }
584
+ abilityAssert(method.startsWith('storage.') && this.validGrant(instance, 'storage'), 'RESOURCE_DENIED', 'Resource is not granted', 403);
585
+ abilityAssert(typeof args.key === 'string' && /^[A-Za-z0-9._-]{1,128}$/.test(args.key), 'KEY_INVALID', 'Invalid storage key');
586
+ const entry = this.store.kvAddress(instance, args.key);
587
+ if (method === 'storage.get')
588
+ return this.store.get(entry.kind, entry.id) ?? null;
589
+ abilityAssert(method === 'storage.set' || method === 'storage.delete', 'METHOD_UNSUPPORTED', 'Unsupported resource method');
590
+ const value = method === 'storage.delete' ? null : args.value;
591
+ abilityAssert(Buffer.byteLength(JSON.stringify(value) ?? '') <= 65536, 'VALUE_TOO_LARGE', 'Storage value exceeds 64 KiB');
592
+ this.store.transaction(() => { this.store.audit('invocation:' + invocationId, instance.target.aid, method, instanceId); this.store.put(entry.kind, entry.id, instance.target.aid, value); });
593
+ return { ok: true };
594
+ }
595
+ invoke(callerKey, aid, instanceId, abilityPath, definitionId, params, operationId, context) {
596
+ const flight = this.performInvocation(callerKey, aid, instanceId, abilityPath, definitionId, params, operationId, context);
597
+ this.executions.add(flight);
598
+ void flight.then(() => this.executions.delete(flight), () => this.executions.delete(flight));
599
+ return flight;
600
+ }
601
+ async performInvocation(callerKey, aid, instanceId, abilityPath, definitionId, params, operationId, context) {
602
+ abilityAssert(!this.closed, 'SERVICE_CLOSED', 'Ability service is closing', 503);
603
+ abilityAssert(typeof operationId === 'string' && operationId.length > 0 && operationId.length <= 256, 'OPERATION_ID_INVALID', 'Operation ID is required');
604
+ if (!context.remote) {
605
+ abilityAssert(context.actor && context.actor.key === callerKey, 'PERMISSION_DENIED', 'Authenticated local actor is required', 403);
606
+ await this.authorize(context.actor, aid, 'invoke');
607
+ }
608
+ const approval = this.instance(aid, instanceId, true);
609
+ abilityAssert(!this.host.runtimeAuthorized || await this.host.runtimeAuthorized(approval), 'OWNER_REVALIDATION_REQUIRED', 'Current Owner approval is required', 403);
610
+ const id = operationKey(callerKey, aid, operationId);
611
+ const fingerprint = operationFingerprint({ ability_path: abilityPath, definition_id: definitionId, params, async: context.async === true });
612
+ const old = this.store.get('invocation', id);
613
+ if (old) {
614
+ if (context.remote)
615
+ abilityAssert(this.remoteAllowed(this.instance(aid, old.instanceId, true), callerKey, { path: old.path, definition_id: old.definitionId }, old.grantId), 'RESULT_WITHHELD', 'Current result authorization is required', 403);
616
+ else
617
+ await this.authorize(context.actor, aid, 'result-read');
618
+ abilityAssert(old.fingerprint === fingerprint, 'IDEMPOTENCY_CONFLICT', 'Operation ID already belongs to different input', 409);
619
+ return this.resultView(old);
620
+ }
621
+ const instance = this.instance(aid, instanceId);
622
+ const pkg = this.pkg(instance);
623
+ const item = pkg.definitions.find(value => value.definition.path === abilityPath);
624
+ abilityAssert(item, 'ABILITY_NOT_FOUND', 'Ability not found', 404);
625
+ const definition = materializeDefinition(item.definition, instance.semanticRevision);
626
+ abilityAssert(definition.definition_id === definitionId, 'CONTRACT_CHANGED', 'Definition changed; rediscover before a new operation', 409);
627
+ abilityAssert(instance.runtimeState === 'ready' && instance.desiredState === 'enabled' && this.runners.has(instanceId), 'INSTANCE_NOT_READY', 'Instance is not ready', 409);
628
+ const validate = ajv.compile(definition.params_schema);
629
+ abilityAssert(validate(params) && Buffer.byteLength(JSON.stringify(params)) <= pkg.manifest.limits.maxParamsBytes, 'PARAMS_INVALID', 'Parameters do not match the ability contract');
630
+ abilityAssert([...this.active.values()].filter(value => value.instanceId === instanceId).length < pkg.manifest.limits.maxConcurrency, 'RESOURCE_BUSY', 'Instance is busy', 409);
631
+ let grant;
632
+ if (context.remote) {
633
+ abilityAssert(instance.publicationState === 'published' && instance.publishedPaths.includes(abilityPath), 'PERMISSION_DENIED', 'Ability is not currently published', 403);
634
+ grant = executionGrant(instance, callerKey, definition, params, this.store);
635
+ abilityAssert(grant, 'PERMISSION_DENIED', 'Caller lacks an available scoped grant for this definition', 403);
636
+ if (grant.value.mode === 'approval') {
637
+ const pending = this.store.get('approval', id);
638
+ if (pending)
639
+ abilityAssert(pending.fingerprint === fingerprint && pending.grantId === grant.id, 'IDEMPOTENCY_CONFLICT', 'Approval belongs to different input', 409);
640
+ if (!pending) {
641
+ const approval = { id, targetAid: aid, instanceId, grantId: grant.id, callerAid: callerKey, operationId, path: abilityPath, definitionId, fingerprint, params: structuredClone(params), state: 'pending', expiresAt: Date.now() + 600000, createdAt: Date.now() };
642
+ this.store.transaction(() => { this.store.put('approval', id, aid, approval); this.store.audit(callerKey, aid, 'approval.requested', id); });
643
+ }
644
+ abilityAssert(pending?.state === 'approved' && pending.expiresAt > Date.now(), 'CONFIRMATION_UNAVAILABLE', 'Owner approval is pending or unavailable; retry the original operation with the same input after approval', 409);
645
+ }
646
+ }
647
+ const invocation = { id, targetAid: aid, instanceId, callerKey, operationId, fingerprint, path: abilityPath, definitionId,
648
+ generation: instance.generation, state: 'executing', createdAt: Date.now(), updatedAt: Date.now(),
649
+ idempotencyKey: 'ecop1_' + createHash('sha256').update(canonicalize({ domain: 'evolcore.ability-operation/v1', providerAid: aid, callerKey: (context.remote ? 'aun:' : 'local:') + callerKey, operationId })).digest('base64url') };
650
+ invocation.resultExpiresAt = Date.now() + RESULT_RETENTION_MS;
651
+ invocation.grantId = grant?.id;
652
+ this.store.transaction(() => {
653
+ if (grant) {
654
+ consumeGrant(grant, params, aid, this.store);
655
+ const approval = this.store.get('approval', id);
656
+ if (approval?.state === 'approved') {
657
+ approval.state = 'consumed';
658
+ this.store.put('approval', id, aid, approval);
659
+ }
660
+ }
661
+ this.store.audit(callerKey, aid, 'invocation.admitted', id);
662
+ this.store.put('invocation', id, aid, invocation);
663
+ });
664
+ this.active.set(id, { instanceId, generation: instance.generation });
665
+ try {
666
+ const result = await this.runners.get(instanceId).call('invoke', { invocationId: id, handler: item.handler, params, operationId,
667
+ idempotencyKey: invocation.idempotencyKey, caller: { kind: context.remote ? 'aun' : 'local', aid: context.actor?.aid ?? callerKey } }, pkg.manifest.limits.executionTimeoutMs);
668
+ abilityAssert(Buffer.byteLength(JSON.stringify(result)) <= pkg.manifest.limits.maxResultBytes && ajv.compile(definition.result_schema)(result), 'RESULT_INVALID', 'Plugin result does not match contract', 502);
669
+ invocation.state = 'completed';
670
+ invocation.ok = true;
671
+ invocation.result = result;
672
+ }
673
+ catch (error) {
674
+ invocation.state = 'unknown';
675
+ invocation.ok = false;
676
+ invocation.error = { code: error instanceof AbilityError ? error.code : 'EXECUTION_UNKNOWN', message: 'Execution failed or outcome is unknown; inspect original operation' };
677
+ }
678
+ finally {
679
+ this.active.delete(id);
680
+ }
681
+ invocation.updatedAt = Date.now();
682
+ this.store.transaction(() => { this.store.put('invocation', id, aid, invocation); this.store.audit(callerKey, aid, 'invocation.' + invocation.state, id); });
683
+ return invocation;
684
+ }
685
+ remoteAllowed(instance, caller, definition, grantId) {
686
+ return instance.grants.some(grant => {
687
+ const value = grant.value;
688
+ return grant.permission === 'remote-call' && (!grantId || grant.id === grantId) && !grant.revokedAt && !!grant.expiresAt && grant.expiresAt > Date.now()
689
+ && grant.issuedByAid === instance.approvedByAid
690
+ && value?.callerAid === caller && value?.path === definition.path && value?.definitionId === definition.definition_id;
691
+ });
692
+ }
693
+ async remoteResult(callerKey, aid, operationId) {
694
+ const value = this.store.get('invocation', operationKey(callerKey, aid, operationId));
695
+ abilityAssert(value, 'RESULT_WITHHELD', 'Current result authorization is required', 403);
696
+ const instance = this.instance(aid, value.instanceId, true);
697
+ abilityAssert(!this.host.runtimeAuthorized || await this.host.runtimeAuthorized(instance), 'RESULT_WITHHELD', 'Current result authorization is required', 403);
698
+ const current = this.instance(aid, value.instanceId, true);
699
+ abilityAssert(current.approvedByAid === instance.approvedByAid && this.remoteAllowed(current, callerKey, { path: value.path, definition_id: value.definitionId }, value.grantId), 'RESULT_WITHHELD', 'Current result authorization is required', 403);
700
+ return this.resultView(value);
701
+ }
702
+ async invocation(actor, aid, id) { await this.authorize(actor, aid, 'result-read'); const value = this.store.get('invocation', id); abilityAssert(value?.targetAid === aid, 'INVOCATION_NOT_FOUND', 'Invocation not found', 404); return this.resultView(value); }
703
+ resultView(value) {
704
+ const resultExpiresAt = value.resultExpiresAt ?? value.createdAt + RESULT_RETENTION_MS;
705
+ return value.resultExpired || value.state !== 'executing' && resultExpiresAt <= Date.now()
706
+ ? { ...value, resultExpiresAt, result: undefined, resultExpired: true, ok: false, error: { code: 'RESULT_EXPIRED', message: 'Result expired; execution receipt is retained' } }
707
+ : { ...value, resultExpiresAt };
708
+ }
709
+ approvalView(approval) {
710
+ let status = approval.state;
711
+ if (approval.state === 'pending' || approval.state === 'approved') {
712
+ const instance = this.store.get('instance', approval.instanceId);
713
+ const grant = instance?.grants.find(grant => grant.id === approval.grantId);
714
+ const definition = instance && this.pkg(instance).definitions.find(row => row.definition.path === approval.path);
715
+ if (approval.expiresAt <= Date.now())
716
+ status = 'expired';
717
+ else if (!instance || instance.deletedAt)
718
+ status = 'instance_unavailable';
719
+ else if (!definition || materializeDefinition(definition.definition, instance.semanticRevision).definition_id !== approval.definitionId)
720
+ status = 'contract_changed';
721
+ else if (!grant)
722
+ status = 'grant_unavailable';
723
+ else if (grantState(instance, grant, this.store) !== 'active')
724
+ status = grantState(instance, grant, this.store);
725
+ }
726
+ return { ...approval, status, params: approval.expiresAt <= Date.now() ? {} : approval.params };
727
+ }
728
+ async approvals(actor, aid) {
729
+ await this.authorize(actor, aid, 'grant');
730
+ return this.store.list('approval', aid).map(value => this.approvalView(value));
731
+ }
732
+ async history(actor, aid, id) {
733
+ await this.authorize(actor, aid, 'read');
734
+ const target = this.host.targets().find(target => target.aid === aid);
735
+ const canResults = await this.host.authorize(actor, target, 'result-read');
736
+ const canApprove = await this.host.authorize(actor, target, 'grant');
737
+ const publication = this.store.get('publication', aid);
738
+ return { generations: this.store.list('history', aid).filter(value => !id || value.id === id).map(value => ({ generation: value.generation, instanceId: value.id, version: this.pkg(value).manifest.version, updatedAt: value.updatedAt })),
739
+ invocations: this.store.list('invocation', aid).filter(value => !id || value.instanceId === id).sort((a, b) => b.createdAt - a.createdAt).slice(0, 100).map(value => { const result = this.resultView(value); return canResults ? result : { ...result, result: undefined, error: undefined }; }),
740
+ approvals: canApprove ? (await this.approvals(actor, aid)).filter(value => !id || value.instanceId === id) : [],
741
+ jobs: this.store.list('job', aid).filter(value => value.actorKey === actor.key && (!id || value.instanceId === id)).sort((a, b) => b.createdAt - a.createdAt).slice(0, 100).map(job => job.action === 'invoke' ? { ...job, result: canResults && job.result ? this.resultView(job.result) : undefined } : job), audit: this.store.auditRows(aid), publication: publication && { state: publication.state, updatedAt: publication.updatedAt, error: publication.error } };
742
+ }
743
+ published(aid) {
744
+ const result = [];
745
+ for (const instance of this.store.list('instance', aid))
746
+ if (!instance.deletedAt && instance.desiredState === 'enabled' && instance.runtimeState === 'ready') {
747
+ const pkg = this.pkg(instance);
748
+ for (const item of pkg.definitions)
749
+ if (instance.publishedPaths.includes(String(item.definition.path))) {
750
+ const definition = materializeDefinition(item.definition, instance.semanticRevision);
751
+ const usage = { ...item.usage, definition_id: definition.definition_id };
752
+ result.push({ instance, definition, usage, releaseId: abilityReleaseId(pkg.manifest.version, definition, usage), version: pkg.manifest.version });
753
+ }
754
+ }
755
+ return result;
756
+ }
757
+ markPublicationDirty(aid, force = false) {
758
+ const previous = this.store.get('publication', aid);
759
+ if (!force && !previous)
760
+ return;
761
+ this.store.put('publication', aid, aid, { ...previous, state: 'pending', revision: (previous?.revision ?? 0) + 1, updatedAt: Date.now() });
762
+ }
763
+ async syncIfDirty(aid) { if (this.host.publish && this.store.get('publication', aid)?.state === 'pending')
764
+ await this.syncPublication(aid); }
765
+ async syncPublication(aid) {
766
+ const previous = this.publications.get(aid) ?? Promise.resolve();
767
+ const flight = previous.catch(() => { }).then(() => this.performPublication(aid));
768
+ this.publications.set(aid, flight);
769
+ try {
770
+ await flight;
771
+ }
772
+ finally {
773
+ if (this.publications.get(aid) === flight)
774
+ this.publications.delete(aid);
775
+ }
776
+ }
777
+ async performPublication(aid) {
778
+ abilityAssert(this.host.publish, 'PUBLICATION_UNAVAILABLE', 'AUN publication backend unavailable', 503);
779
+ const rows = this.published(aid);
780
+ const documents = [];
781
+ for (const item of rows)
782
+ documents.push({ path: `/ability/definitions/${item.definition.definition_id}/${item.definition.path}.json`, content: canonicalize(item.definition) }, { path: `/ability/releases/${item.releaseId}/${item.definition.path}.usage.json`, content: JSON.stringify(item.usage) });
783
+ for (const item of rows) {
784
+ const snapshot = { schema: 'aun.ability.release.v1', plugin_version: item.version, release_id: item.releaseId, definition: item.definition, usage: item.usage };
785
+ const existing = this.store.get('release', item.releaseId);
786
+ abilityAssert(!existing || canonicalize(existing) === canonicalize(snapshot), 'IMMUTABLE_CONFLICT', 'Release snapshot content differs', 409);
787
+ this.store.put('release', item.releaseId, aid, snapshot);
788
+ }
789
+ const catalogTime = Math.max(0, ...this.store.list('instance', aid).map(value => value.updatedAt));
790
+ documents.push({ path: '/ability/index.json', content: JSON.stringify(buildAbilityIndex({ publisherAid: aid, updatedAt: new Date(catalogTime).toISOString(), capabilities: rows.map(row => abilitySummary(row.definition, aid, row.releaseId, row.version)) })) });
791
+ const previous = this.store.get('publication', aid);
792
+ const revision = previous?.revision ?? 0;
793
+ const expectedIndexes = [...new Set([...(previous?.expectedIndexes ?? []), previous?.indexContent, previous?.documents?.find(value => value.path === '/ability/index.json')?.content].filter((value) => typeof value === 'string'))];
794
+ this.store.put('publication', aid, aid, { ...previous, state: 'pending', revision, documents, expectedIndexes, updatedAt: Date.now() });
795
+ try {
796
+ await this.host.publish(aid, documents, expectedIndexes);
797
+ const current = this.store.get('publication', aid);
798
+ const indexContent = documents[documents.length - 1].content;
799
+ if ((current.revision ?? 0) !== revision) {
800
+ this.store.put('publication', aid, aid, { ...current, state: 'pending', expectedIndexes: [...new Set([...(current.expectedIndexes ?? []), indexContent])], indexContent });
801
+ return;
802
+ }
803
+ this.store.put('publication', aid, aid, { state: 'completed', revision, indexContent, updatedAt: Date.now() });
804
+ for (const instance of this.store.list('instance', aid)) {
805
+ instance.publicationState = instance.publishedPaths.length ? instance.runtimeState === 'ready' && instance.desiredState === 'enabled' ? 'published' : 'degraded' : 'unpublished';
806
+ if (instance.error === 'Publication synchronization failed')
807
+ delete instance.error;
808
+ this.store.put('instance', instance.id, aid, instance, instance.revision);
809
+ }
810
+ }
811
+ catch (error) {
812
+ const current = this.store.get('publication', aid);
813
+ this.store.put('publication', aid, aid, { ...current, state: 'pending', error: { code: error instanceof AbilityError ? error.code : 'PUBLICATION_FAILED', message: error instanceof AbilityError ? error.message : 'Publication remains pending; inspect connectivity and index ownership' } });
814
+ for (const instance of this.store.list('instance', aid)) {
815
+ instance.publicationState = instance.publishedPaths.length ? 'degraded' : 'revoking';
816
+ instance.error = 'Publication synchronization failed';
817
+ this.store.put('instance', instance.id, aid, instance, instance.revision);
818
+ }
819
+ throw error;
820
+ }
821
+ }
822
+ async recover() {
823
+ if (this.secrets.status === 'unverified')
824
+ await this.secrets.probe();
825
+ if (!this.accepting)
826
+ return;
827
+ for (const invocation of this.store.list('invocation')) {
828
+ const normalized = this.resultView(invocation);
829
+ if (!sameJson(normalized, invocation))
830
+ this.store.put('invocation', invocation.id, invocation.targetAid, normalized);
831
+ }
832
+ for (const job of this.store.list('job'))
833
+ if (job.action === 'invoke' && job.result) {
834
+ const normalized = this.resultView(job.result);
835
+ if (!sameJson(normalized, job.result)) {
836
+ job.result = normalized;
837
+ this.store.put('job', job.id, job.targetAid, job);
838
+ }
839
+ }
840
+ for (const approval of this.store.list('approval'))
841
+ if (approval.expiresAt < Date.now() && Object.keys(approval.params).length) {
842
+ approval.params = {};
843
+ this.store.put('approval', approval.id, approval.targetAid, approval);
844
+ }
845
+ for (const target of this.host.targets()) {
846
+ if (this.flights.has(target.aid))
847
+ continue;
848
+ const flight = (async () => {
849
+ let restored = false;
850
+ for (const instance of this.store.list('instance', target.aid))
851
+ if (!instance.deletedAt && instance.runtimeState !== 'ready' && instance.desiredState === 'enabled' && instance.trustedCodeApproved) {
852
+ try {
853
+ await this.start(instance);
854
+ restored = true;
855
+ }
856
+ catch {
857
+ const current = this.instance(target.aid, instance.id);
858
+ current.runtimeState = 'failed';
859
+ current.error = 'Recovery requires valid code, configuration and current Owner approval';
860
+ this.store.put('instance', current.id, current.target.aid, current, current.revision);
861
+ }
862
+ }
863
+ const publication = this.store.get('publication', target.aid);
864
+ if (this.host.publish && publication && (restored || publication.state === 'pending'))
865
+ try {
866
+ await this.syncPublication(target.aid);
867
+ }
868
+ catch { /* retry pending intent later */ }
869
+ })();
870
+ this.flights.set(target.aid, flight);
871
+ try {
872
+ await flight;
873
+ }
874
+ finally {
875
+ if (this.flights.get(target.aid) === flight)
876
+ this.flights.delete(target.aid);
877
+ }
878
+ }
879
+ }
880
+ async close() { if (this.closed)
881
+ return; this.accepting = false; await this.drain(); this.closed = true; await Promise.all([...this.runners.keys()].map(id => this.stop(id))); await Promise.allSettled([...this.executions, ...this.publications.values()]); this.store.close(); }
882
+ }