@octopi-agent/engine 0.102.10 → 0.121.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/builtin-model-info.js +28 -7
- package/dist/config-admin/agent-presets.d.ts +32 -0
- package/dist/config-admin/agent-presets.js +133 -0
- package/dist/config-admin/discover.d.ts +33 -4
- package/dist/config-admin/discover.js +101 -6
- package/dist/config-admin/env.d.ts +11 -0
- package/dist/config-admin/env.js +41 -0
- package/dist/config-admin/error-copy.d.ts +106 -0
- package/dist/config-admin/error-copy.js +287 -0
- package/dist/config-admin/i18n.d.ts +21 -0
- package/dist/config-admin/i18n.js +19 -0
- package/dist/config-admin/index.d.ts +6 -2
- package/dist/config-admin/index.js +3 -1
- package/dist/config-admin/model-presets.d.ts +14 -0
- package/dist/config-admin/model-presets.js +595 -70
- package/dist/config-admin/onboarding-apply.d.ts +71 -0
- package/dist/config-admin/onboarding-apply.js +235 -0
- package/dist/config-admin/onboarding.d.ts +154 -0
- package/dist/config-admin/onboarding.js +270 -0
- package/dist/config-admin/redact.d.ts +42 -9
- package/dist/config-admin/redact.js +69 -5
- package/dist/config-schema/agent.d.ts +5 -1
- package/dist/config-schema/agent.js +20 -2
- package/dist/config-schema/browser.d.ts +62 -0
- package/dist/config-schema/browser.js +89 -0
- package/dist/config-schema/context.d.ts +7 -2
- package/dist/config-schema/context.js +6 -3
- package/dist/config-schema/engine.d.ts +86 -7
- package/dist/config-schema/engine.js +9 -2
- package/dist/config-schema/governance.d.ts +12 -1
- package/dist/config-schema/governance.js +10 -2
- package/dist/config-schema/models.d.ts +12 -8
- package/dist/config-schema/models.js +16 -1
- package/dist/config-schema/run.d.ts +4 -0
- package/dist/config-schema/run.js +10 -0
- package/dist/config-schema/shared.d.ts +1 -0
- package/dist/config-schema/shared.js +4 -2
- package/dist/config-schema/substrate.d.ts +5 -0
- package/dist/config-schema/substrate.js +8 -0
- package/dist/config.d.ts +116 -10
- package/dist/config.js +109 -13
- package/dist/file-mode.d.ts +67 -0
- package/dist/file-mode.js +182 -0
- package/dist/fork-child.d.ts +82 -0
- package/dist/fork-child.js +123 -0
- package/dist/harness/activation/delegated-run.d.ts +42 -0
- package/dist/harness/activation/delegated-run.js +71 -0
- package/dist/harness/activation/dispatcher.js +4 -0
- package/dist/harness/activation/index.d.ts +1 -0
- package/dist/harness/activation/run-backend.d.ts +92 -0
- package/dist/harness/activation/run-backend.js +16 -0
- package/dist/harness/activation/run-protocol.d.ts +392 -0
- package/dist/harness/activation/run-protocol.js +19 -0
- package/dist/harness/activation/runtime.d.ts +33 -0
- package/dist/harness/activation/runtime.js +119 -28
- package/dist/harness/activation/types.d.ts +19 -2
- package/dist/harness/agent/builder.d.ts +12 -0
- package/dist/harness/agent/builder.js +78 -22
- package/dist/harness/agent/config-bridge.d.ts +10 -1
- package/dist/harness/agent/config-bridge.js +15 -3
- package/dist/harness/agent/registered-tool-adapter.d.ts +27 -0
- package/dist/harness/agent/registered-tool-adapter.js +67 -0
- package/dist/harness/agent/wire-agent-builder.d.ts +2 -0
- package/dist/harness/agent/wire-agent-builder.js +9 -2
- package/dist/harness/capabilities/document/backends/plain.js +2 -1
- package/dist/harness/capabilities/document/legacy/factory.js +3 -2
- package/dist/harness/collaboration/autonomous-subsystem/audit/reader.d.ts +17 -0
- package/dist/harness/collaboration/autonomous-subsystem/audit/reader.js +66 -36
- package/dist/harness/collaboration/autonomous-subsystem/audit/writer.d.ts +6 -2
- package/dist/harness/collaboration/autonomous-subsystem/audit/writer.js +27 -7
- package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +13 -0
- package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -0
- package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +11 -0
- package/dist/harness/collaboration/autonomous-subsystem/runtime.js +17 -0
- package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +13 -3
- package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +48 -39
- package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -0
- package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +4 -0
- package/dist/harness/collaboration/delegation/child-run.d.ts +9 -0
- package/dist/harness/collaboration/delegation/child-run.js +34 -2
- package/dist/harness/collaboration/delegation/registry-types.d.ts +2 -0
- package/dist/harness/collaboration/delegation/service.d.ts +9 -4
- package/dist/harness/collaboration/delegation/service.js +33 -12
- package/dist/harness/collaboration/delegation/store.d.ts +2 -0
- package/dist/harness/collaboration/delegation/store.js +1 -0
- package/dist/harness/collaboration/delegation/types.d.ts +11 -0
- package/dist/harness/collaboration/delegation/wiring.d.ts +2 -0
- package/dist/harness/collaboration/delegation/wiring.js +1 -0
- package/dist/harness/context/capabilities/compact/engine.d.ts +44 -5
- package/dist/harness/context/capabilities/compact/engine.js +127 -39
- package/dist/harness/context/capabilities/compact/index.d.ts +2 -1
- package/dist/harness/context/capabilities/compact/index.js +1 -1
- package/dist/harness/context/capabilities/compact/types.d.ts +59 -9
- package/dist/harness/context/capabilities/summary/gate.d.ts +19 -2
- package/dist/harness/context/capabilities/summary/gate.js +53 -6
- package/dist/harness/context/capabilities/summary/registry.js +20 -0
- package/dist/harness/context/capabilities/summary/tool-binding.js +16 -12
- package/dist/harness/context/capabilities/summary/tool-bindings.d.ts +13 -0
- package/dist/harness/context/capabilities/summary/tool-bindings.js +22 -0
- package/dist/harness/context/capabilities/summary/types.d.ts +16 -0
- package/dist/harness/context/constitution/default-agents.md +85 -0
- package/dist/harness/context/context-size-ledger.js +8 -1
- package/dist/harness/context/default-context-engine.d.ts +100 -6
- package/dist/harness/context/default-context-engine.js +382 -89
- package/dist/harness/context/index.d.ts +2 -1
- package/dist/harness/context/index.js +1 -0
- package/dist/harness/context/layer-health.d.ts +4 -0
- package/dist/harness/context/layer-health.js +4 -0
- package/dist/harness/context/layer-types.d.ts +57 -0
- package/dist/harness/context/layer-types.js +73 -1
- package/dist/harness/context/layers.d.ts +3 -0
- package/dist/harness/context/layers.js +13 -6
- package/dist/harness/context/prefix-fingerprint.d.ts +46 -0
- package/dist/harness/context/prefix-fingerprint.js +52 -0
- package/dist/harness/context/summarize.js +18 -0
- package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
- package/dist/harness/context/system-prompt-assembler.js +5 -2
- package/dist/harness/context/tool-result-aging.d.ts +104 -16
- package/dist/harness/context/tool-result-aging.js +211 -57
- package/dist/harness/context/types.d.ts +71 -4
- package/dist/harness/context/types.js +25 -1
- package/dist/harness/extension/execution-environment/effect-policy.d.ts +4 -3
- package/dist/harness/extension/execution-environment/effect-policy.js +2 -2
- package/dist/harness/extension/execution-environment/privileged-exec.js +4 -1
- package/dist/harness/extension/execution-environment/workspace.js +1 -1
- package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +27 -1
- package/dist/harness/extension/plugin-ecosystem/channel-types.js +11 -2
- package/dist/harness/extension/plugin-ecosystem/client-tools/registry.d.ts +12 -0
- package/dist/harness/extension/plugin-ecosystem/client-tools/registry.js +25 -0
- package/dist/harness/extension/plugin-ecosystem/commands/builtin.js +28 -1
- package/dist/harness/extension/plugin-ecosystem/index.d.ts +1 -0
- package/dist/harness/extension/plugin-ecosystem/index.js +1 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +168 -1
- package/dist/harness/extension/plugin-ecosystem/plugins/api.js +156 -15
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.d.ts +95 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.js +170 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.d.ts +178 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.js +314 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +40 -5
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +45 -26
- package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +1 -1
- package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +11 -1
- package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +42 -76
- package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +30 -1
- package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +46 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +9 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +19 -14
- package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +3 -1
- package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +1 -1
- package/dist/harness/extension/plugin-ecosystem/tools/browser-types.d.ts +333 -0
- package/dist/harness/extension/plugin-ecosystem/tools/browser-types.js +16 -0
- package/dist/harness/extension/plugin-ecosystem/tools/browser.d.ts +64 -0
- package/dist/harness/extension/plugin-ecosystem/tools/browser.js +692 -0
- package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +0 -37
- package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +108 -4
- package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -0
- package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +34 -0
- package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +0 -6
- package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +57 -4
- package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +81 -13
- package/dist/harness/extension/plugin-ecosystem/tools/http.js +5 -0
- package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +13 -7
- package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +126 -14
- package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +1 -1
- package/dist/harness/extension/plugin-ecosystem/tools/platform.js +44 -5
- package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +10 -24
- package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +7 -0
- package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -0
- package/dist/harness/governance/credentials/db.d.ts +9 -0
- package/dist/harness/governance/credentials/db.js +122 -31
- package/dist/harness/governance/credentials/store.d.ts +68 -7
- package/dist/harness/governance/credentials/store.js +177 -64
- package/dist/harness/governance/credentials/types.d.ts +13 -2
- package/dist/harness/governance/index.d.ts +1 -0
- package/dist/harness/governance/index.js +1 -0
- package/dist/harness/governance/registry/db.d.ts +32 -0
- package/dist/harness/governance/registry/db.js +142 -0
- package/dist/harness/governance/registry/index.d.ts +9 -0
- package/dist/harness/governance/registry/index.js +9 -0
- package/dist/harness/governance/registry/service.d.ts +381 -0
- package/dist/harness/governance/registry/service.js +825 -0
- package/dist/harness/governance/registry/types.d.ts +77 -0
- package/dist/harness/governance/registry/types.js +7 -0
- package/dist/harness/governance/security/default-security-guard.d.ts +3 -0
- package/dist/harness/governance/security/default-security-guard.js +12 -1
- package/dist/harness/governance/security/risk-evaluator.d.ts +13 -3
- package/dist/harness/governance/security/risk-evaluator.js +307 -21
- package/dist/harness/governance/security/shell-parser-treesitter.js +12 -4
- package/dist/harness/governance/session-acl/tool-rights.d.ts +1 -0
- package/dist/harness/index.d.ts +5 -3
- package/dist/harness/index.js +2 -2
- package/dist/harness/knowledge/boot-config.d.ts +2 -0
- package/dist/harness/knowledge/boot-config.js +2 -0
- package/dist/harness/knowledge/client.d.ts +53 -7
- package/dist/harness/knowledge/client.js +77 -20
- package/dist/harness/knowledge/db.d.ts +16 -0
- package/dist/harness/knowledge/db.js +107 -41
- package/dist/harness/knowledge/engine-thread.js +5 -7
- package/dist/harness/knowledge/grounding.js +4 -1
- package/dist/harness/knowledge/http-app.d.ts +15 -0
- package/dist/harness/knowledge/http-app.js +82 -21
- package/dist/harness/knowledge/http-bridge.d.ts +15 -0
- package/dist/harness/knowledge/http-bridge.js +19 -0
- package/dist/harness/knowledge/knowledge-serve-child.js +2 -3
- package/dist/harness/knowledge/query-service.d.ts +12 -2
- package/dist/harness/knowledge/query-service.js +75 -41
- package/dist/harness/knowledge/query-worker-client.d.ts +5 -1
- package/dist/harness/knowledge/query-worker-client.js +4 -1
- package/dist/harness/knowledge/query-worker.js +5 -3
- package/dist/harness/knowledge/read-http.d.ts +2 -0
- package/dist/harness/knowledge/read-http.js +9 -2
- package/dist/harness/knowledge/retriever.d.ts +1 -1
- package/dist/harness/knowledge/retriever.js +1 -2
- package/dist/harness/knowledge/serve.d.ts +6 -1
- package/dist/harness/knowledge/serve.js +5 -6
- package/dist/harness/knowledge/source-store.d.ts +101 -5
- package/dist/harness/knowledge/source-store.js +297 -71
- package/dist/harness/knowledge/start-service-process.d.ts +27 -8
- package/dist/harness/knowledge/start-service-process.js +49 -90
- package/dist/harness/knowledge/tenant-gate.d.ts +81 -0
- package/dist/harness/knowledge/tenant-gate.js +167 -0
- package/dist/harness/knowledge/writer-service.d.ts +18 -2
- package/dist/harness/knowledge/writer-service.js +80 -16
- package/dist/harness/knowledge/writer-worker-client.d.ts +9 -2
- package/dist/harness/knowledge/writer-worker-client.js +20 -3
- package/dist/harness/knowledge/writer-worker.js +11 -4
- package/dist/harness/memory/backfill-trigger.d.ts +10 -3
- package/dist/harness/memory/backfill-trigger.js +19 -19
- package/dist/harness/memory/cognition-seeds.d.ts +45 -0
- package/dist/harness/memory/cognition-seeds.js +67 -0
- package/dist/harness/memory/cognition.d.ts +12 -3
- package/dist/harness/memory/cognition.js +55 -35
- package/dist/harness/memory/conceptualizer.d.ts +11 -1
- package/dist/harness/memory/conceptualizer.js +10 -1
- package/dist/harness/memory/context-slice.d.ts +42 -0
- package/dist/harness/memory/context-slice.js +197 -0
- package/dist/harness/memory/health-probe.d.ts +8 -2
- package/dist/harness/memory/health-probe.js +10 -13
- package/dist/harness/memory/index.d.ts +5 -1
- package/dist/harness/memory/index.js +3 -1
- package/dist/harness/memory/sqlite/agent-db.d.ts +1 -0
- package/dist/harness/memory/sqlite/agent-db.js +9 -8
- package/dist/harness/memory/sqlite/cognition-store.d.ts +26 -3
- package/dist/harness/memory/sqlite/cognition-store.js +103 -45
- package/dist/harness/memory/sqlite/memory-store.js +4 -0
- package/dist/harness/memory/sqlite/sqlite-vec.d.ts +24 -1
- package/dist/harness/memory/sqlite/sqlite-vec.js +37 -1
- package/dist/harness/memory/types.d.ts +18 -2
- package/dist/harness/observability/observer/hub.d.ts +10 -0
- package/dist/harness/observability/observer/hub.js +95 -2
- package/dist/harness/run/agent/agent.js +3 -2
- package/dist/harness/run/concurrency/tool-validator.js +4 -3
- package/dist/harness/run/reliability/run-agent.d.ts +22 -0
- package/dist/harness/run/reliability/run-agent.js +79 -10
- package/dist/harness/run/run-host.d.ts +302 -0
- package/dist/harness/run/run-host.js +978 -0
- package/dist/harness/run/run-scope.d.ts +11 -0
- package/dist/harness/run/run-scope.js +19 -1
- package/dist/harness/run/runner.d.ts +149 -22
- package/dist/harness/run/runner.js +352 -35
- package/dist/harness/session/in-memory-store.js +13 -1
- package/dist/harness/session/schedules/service.d.ts +10 -2
- package/dist/harness/session/schedules/service.js +13 -2
- package/dist/harness/session/tasks/tools.js +12 -0
- package/dist/harness/session/types.d.ts +10 -14
- package/dist/harness/shared/events/agent-event-map.d.ts +29 -0
- package/dist/harness/shared/types/agent-definition.d.ts +6 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +2 -1
- package/dist/integration/agent-runtime/channel-message-source.d.ts +3 -1
- package/dist/integration/agent-runtime/channel-message-source.js +4 -3
- package/dist/integration/browser/camoufox.d.ts +40 -0
- package/dist/integration/browser/camoufox.js +80 -0
- package/dist/integration/browser/index.d.ts +91 -0
- package/dist/integration/browser/index.js +110 -0
- package/dist/integration/browser/install.d.ts +47 -0
- package/dist/integration/browser/install.js +214 -0
- package/dist/integration/browser/playwright.d.ts +224 -0
- package/dist/integration/browser/playwright.js +925 -0
- package/dist/integration/browser/service.d.ts +41 -0
- package/dist/integration/browser/service.js +181 -0
- package/dist/integration/browser/stealth.d.ts +42 -0
- package/dist/integration/browser/stealth.js +104 -0
- package/dist/integration/providers/anthropic-message-normalize.d.ts +20 -0
- package/dist/integration/providers/anthropic-message-normalize.js +48 -0
- package/dist/integration/providers/anthropic.js +27 -2
- package/dist/integration/providers/fetch-timeout.d.ts +17 -0
- package/dist/integration/providers/fetch-timeout.js +24 -0
- package/dist/integration/providers/openai.d.ts +8 -0
- package/dist/integration/providers/openai.js +41 -1
- package/dist/integration/providers/wire-dump-diff.js +2 -1
- package/dist/integration/providers/wire-dump.d.ts +56 -2
- package/dist/integration/providers/wire-dump.js +119 -6
- package/dist/integration/storage/archive-manager.d.ts +14 -2
- package/dist/integration/storage/archive-manager.js +24 -8
- package/dist/integration/storage/atomic-tmp.d.ts +12 -0
- package/dist/integration/storage/atomic-tmp.js +36 -0
- package/dist/integration/storage/jsonl.d.ts +9 -0
- package/dist/integration/storage/jsonl.js +137 -38
- package/dist/integration/storage/session-index.d.ts +5 -0
- package/dist/integration/storage/session-index.js +25 -4
- package/dist/integration/tools/assemble.d.ts +50 -0
- package/dist/integration/tools/assemble.js +137 -0
- package/dist/paths.d.ts +18 -0
- package/dist/paths.js +36 -0
- package/dist/subsystems/cognition-steward/conceptualize/config.yaml +3 -1
- package/dist/subsystems/cognition-steward/conceptualize/handler.js +74 -5
- package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +3 -2
- package/dist/subsystems/cognition-steward/consolidate/config.yaml +11 -2
- package/dist/subsystems/cognition-steward/consolidate/handler.d.ts +6 -3
- package/dist/subsystems/cognition-steward/consolidate/handler.js +266 -28
- package/dist/subsystems/memory-steward/backfill/handler.js +3 -2
- package/dist/subsystems/memory-steward/govern/config.yaml +6 -1
- package/dist/subsystems/wisdom-steward/attribute/config.yaml +5 -1
- package/dist/subsystems/wisdom-steward/formation/config.yaml +3 -0
- package/dist/subsystems/wisdom-steward/govern/config.yaml +6 -1
- package/package.json +5 -3
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host-owned contribution instance tracking for factory-backed kinds
|
|
3
|
+
* (providers, channels). Not exported through the author SDK; authors reach it
|
|
4
|
+
* only through `PluginApi.getContributionInstance`.
|
|
5
|
+
*
|
|
6
|
+
* Lifecycle model: an instance is born when the Host **accepts** the factory
|
|
7
|
+
* product (post-validation, i.e. exactly what the Host routes to) and dies by
|
|
8
|
+
* one of two triggers:
|
|
9
|
+
* - physical: the Host calls its lifecycle method (`stop()` for channels,
|
|
10
|
+
* `dispose()` for providers) — recorded when the call is *requested*,
|
|
11
|
+
* regardless of outcome, because the Host will not revive it either way;
|
|
12
|
+
* - logical: a newer instance is accepted for the same contribution key and
|
|
13
|
+
* label (config hot-reload replace). The superseded instance may still serve
|
|
14
|
+
* draining in-flight work; it is simply no longer returned by lookup.
|
|
15
|
+
*
|
|
16
|
+
* Storage follows the staging pattern: one table per PluginApi, created by the
|
|
17
|
+
* host loader, so a plugin can only ever see instances of its own
|
|
18
|
+
* contributions.
|
|
19
|
+
*/
|
|
20
|
+
import type { PluginApi } from './api.js';
|
|
21
|
+
/** Contribution kinds whose entries are factories producing runtime instances. */
|
|
22
|
+
export type ContributionInstanceKind = 'provider' | 'channel';
|
|
23
|
+
/** The instance method the Host calls to retire the instance. */
|
|
24
|
+
export type RetirementMethod = 'stop' | 'dispose';
|
|
25
|
+
export interface ContributionInstanceEntry {
|
|
26
|
+
readonly kind: ContributionInstanceKind;
|
|
27
|
+
/** The contribution key (provider/channel id). */
|
|
28
|
+
readonly key: string;
|
|
29
|
+
/** Config identity of this instantiation (provider config key; channel label). */
|
|
30
|
+
label: string;
|
|
31
|
+
readonly instance: object;
|
|
32
|
+
state: 'live' | 'retired';
|
|
33
|
+
/** Entries this acceptance superseded — restored when the acceptance is rolled back. */
|
|
34
|
+
superseded: ContributionInstanceEntry[];
|
|
35
|
+
}
|
|
36
|
+
/** Called only by the host when constructing an author API. */
|
|
37
|
+
export declare function createInstanceTable(api: PluginApi): ContributionInstanceTable;
|
|
38
|
+
/** Read the host-owned instance table of one author API. */
|
|
39
|
+
export declare function readInstanceTable(api: PluginApi): ContributionInstanceTable;
|
|
40
|
+
export declare class ContributionInstanceTable {
|
|
41
|
+
private entries;
|
|
42
|
+
/**
|
|
43
|
+
* Record one Host-accepted instance and wrap its retirement method so the
|
|
44
|
+
* entry retires together with the instance. Wrapping happens here — the
|
|
45
|
+
* single registration path — so every Host teardown call site is covered
|
|
46
|
+
* without explicit retire calls.
|
|
47
|
+
*
|
|
48
|
+
* Acceptance semantics:
|
|
49
|
+
* - a newer instance for the same (kind, key, label) supersedes the previous
|
|
50
|
+
* one (config hot-reload replace); the superseded entry is marked retired;
|
|
51
|
+
* - re-accepting the *same* object (singleton factories) refreshes its label
|
|
52
|
+
* instead of double-registering it;
|
|
53
|
+
* - an instance that cannot be tracked is **not registered**: a non-object
|
|
54
|
+
* product, a frozen/sealed object whose retirement method cannot be
|
|
55
|
+
* wrapped, or (channels) a product without `stop` — in every case the
|
|
56
|
+
* Host's own contract validation is the authority that reports the broken
|
|
57
|
+
* adapter, and this method never invents methods it does not own.
|
|
58
|
+
*
|
|
59
|
+
* @param opts - Instance identity and retirement wiring
|
|
60
|
+
* @returns Whether the instance was registered (tracked)
|
|
61
|
+
*/
|
|
62
|
+
attach(opts: {
|
|
63
|
+
kind: ContributionInstanceKind;
|
|
64
|
+
key: string;
|
|
65
|
+
label: string;
|
|
66
|
+
instance: object;
|
|
67
|
+
retireMethod: RetirementMethod;
|
|
68
|
+
defineRetire: boolean;
|
|
69
|
+
}): boolean;
|
|
70
|
+
/**
|
|
71
|
+
* Every recorded entry for one contribution key (live and retired).
|
|
72
|
+
*
|
|
73
|
+
* @param kind - Contribution kind
|
|
74
|
+
* @param key - Contribution key
|
|
75
|
+
* @returns Matching entries in instantiation order
|
|
76
|
+
*/
|
|
77
|
+
find(kind: ContributionInstanceKind, key: string): readonly ContributionInstanceEntry[];
|
|
78
|
+
/**
|
|
79
|
+
* Logical retirement by instance identity — called by the Host when it
|
|
80
|
+
* stops routing to an instance (removal, hot-reload replace, config reset).
|
|
81
|
+
* Idempotent; the wrapped lifecycle method remains the physical backstop.
|
|
82
|
+
*
|
|
83
|
+
* @param instance - The instance object the Host stopped routing to
|
|
84
|
+
*/
|
|
85
|
+
retireByInstance(instance: object): void;
|
|
86
|
+
/**
|
|
87
|
+
* Roll back an acceptance of an instance that was validated but never
|
|
88
|
+
* installed (the Host aborted before routing to it). Removes its entry and
|
|
89
|
+
* resurrects the entries it superseded, so "live" again matches what the
|
|
90
|
+
* Host serves. No-op once the entry is not the current live one.
|
|
91
|
+
*
|
|
92
|
+
* @param instance - The accepted-but-never-installed instance
|
|
93
|
+
*/
|
|
94
|
+
discardByInstance(instance: object): void;
|
|
95
|
+
}
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host-owned contribution instance tracking for factory-backed kinds
|
|
3
|
+
* (providers, channels). Not exported through the author SDK; authors reach it
|
|
4
|
+
* only through `PluginApi.getContributionInstance`.
|
|
5
|
+
*
|
|
6
|
+
* Lifecycle model: an instance is born when the Host **accepts** the factory
|
|
7
|
+
* product (post-validation, i.e. exactly what the Host routes to) and dies by
|
|
8
|
+
* one of two triggers:
|
|
9
|
+
* - physical: the Host calls its lifecycle method (`stop()` for channels,
|
|
10
|
+
* `dispose()` for providers) — recorded when the call is *requested*,
|
|
11
|
+
* regardless of outcome, because the Host will not revive it either way;
|
|
12
|
+
* - logical: a newer instance is accepted for the same contribution key and
|
|
13
|
+
* label (config hot-reload replace). The superseded instance may still serve
|
|
14
|
+
* draining in-flight work; it is simply no longer returned by lookup.
|
|
15
|
+
*
|
|
16
|
+
* Storage follows the staging pattern: one table per PluginApi, created by the
|
|
17
|
+
* host loader, so a plugin can only ever see instances of its own
|
|
18
|
+
* contributions.
|
|
19
|
+
*/
|
|
20
|
+
const tables = new WeakMap();
|
|
21
|
+
/** Called only by the host when constructing an author API. */
|
|
22
|
+
export function createInstanceTable(api) {
|
|
23
|
+
const table = new ContributionInstanceTable();
|
|
24
|
+
tables.set(api, table);
|
|
25
|
+
return table;
|
|
26
|
+
}
|
|
27
|
+
/** Read the host-owned instance table of one author API. */
|
|
28
|
+
export function readInstanceTable(api) {
|
|
29
|
+
const table = tables.get(api);
|
|
30
|
+
if (!table)
|
|
31
|
+
throw new Error('PluginApi was not created by the host loader');
|
|
32
|
+
return table;
|
|
33
|
+
}
|
|
34
|
+
export class ContributionInstanceTable {
|
|
35
|
+
entries = [];
|
|
36
|
+
/**
|
|
37
|
+
* Record one Host-accepted instance and wrap its retirement method so the
|
|
38
|
+
* entry retires together with the instance. Wrapping happens here — the
|
|
39
|
+
* single registration path — so every Host teardown call site is covered
|
|
40
|
+
* without explicit retire calls.
|
|
41
|
+
*
|
|
42
|
+
* Acceptance semantics:
|
|
43
|
+
* - a newer instance for the same (kind, key, label) supersedes the previous
|
|
44
|
+
* one (config hot-reload replace); the superseded entry is marked retired;
|
|
45
|
+
* - re-accepting the *same* object (singleton factories) refreshes its label
|
|
46
|
+
* instead of double-registering it;
|
|
47
|
+
* - an instance that cannot be tracked is **not registered**: a non-object
|
|
48
|
+
* product, a frozen/sealed object whose retirement method cannot be
|
|
49
|
+
* wrapped, or (channels) a product without `stop` — in every case the
|
|
50
|
+
* Host's own contract validation is the authority that reports the broken
|
|
51
|
+
* adapter, and this method never invents methods it does not own.
|
|
52
|
+
*
|
|
53
|
+
* @param opts - Instance identity and retirement wiring
|
|
54
|
+
* @returns Whether the instance was registered (tracked)
|
|
55
|
+
*/
|
|
56
|
+
attach(opts) {
|
|
57
|
+
const target = opts.instance;
|
|
58
|
+
// Callables are valid contract objects; only primitives/null are not.
|
|
59
|
+
if (typeof target !== 'object' && typeof target !== 'function')
|
|
60
|
+
return false;
|
|
61
|
+
if (target === null || target === undefined)
|
|
62
|
+
return false;
|
|
63
|
+
const same = this.entries.find((entry) => entry.kind === opts.kind && entry.key === opts.key && entry.instance === target);
|
|
64
|
+
if (same) {
|
|
65
|
+
// Re-acceptance (e.g. a singleton factory product that was retired and
|
|
66
|
+
// is being served again): the instance is live again as of now.
|
|
67
|
+
same.label = opts.label;
|
|
68
|
+
same.state = 'live';
|
|
69
|
+
return true;
|
|
70
|
+
}
|
|
71
|
+
const original = target[opts.retireMethod];
|
|
72
|
+
const entry = {
|
|
73
|
+
kind: opts.kind,
|
|
74
|
+
key: opts.key,
|
|
75
|
+
label: opts.label,
|
|
76
|
+
instance: target,
|
|
77
|
+
state: 'live',
|
|
78
|
+
superseded: [],
|
|
79
|
+
};
|
|
80
|
+
const retire = () => {
|
|
81
|
+
entry.state = 'retired';
|
|
82
|
+
};
|
|
83
|
+
if (typeof original === 'function') {
|
|
84
|
+
try {
|
|
85
|
+
target[opts.retireMethod] = function (...args) {
|
|
86
|
+
retire();
|
|
87
|
+
return original.apply(target, args);
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
catch {
|
|
91
|
+
// Frozen/sealed instance: retirement cannot be tracked. Leaving it
|
|
92
|
+
// unregistered keeps lookup honest ("never instantiated") instead of
|
|
93
|
+
// handing out an instance the Host has already stopped.
|
|
94
|
+
return false;
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
else if (opts.defineRetire) {
|
|
98
|
+
try {
|
|
99
|
+
target[opts.retireMethod] = retire;
|
|
100
|
+
}
|
|
101
|
+
catch {
|
|
102
|
+
return false;
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
else {
|
|
106
|
+
// Missing mandatory lifecycle method: a broken adapter. The Host's
|
|
107
|
+
// contract validation reports it; never patch `stop` here or that check
|
|
108
|
+
// would stop being honest. Untracked for the same reason as frozen.
|
|
109
|
+
return false;
|
|
110
|
+
}
|
|
111
|
+
// Logical retirement of the superseded instance (recorded for rollback),
|
|
112
|
+
// then prune retired tombstones to one per (kind, key) — lookup only
|
|
113
|
+
// distinguishes "was retired" from "never instantiated", so one tombstone
|
|
114
|
+
// is enough. Pruned tombstones stay reachable through `superseded`.
|
|
115
|
+
for (const prior of this.entries) {
|
|
116
|
+
if (prior.kind === opts.kind && prior.key === opts.key && prior.label === opts.label && prior.state === 'live') {
|
|
117
|
+
prior.state = 'retired';
|
|
118
|
+
entry.superseded.push(prior);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
const retired = this.entries.filter((e) => e.kind === opts.kind && e.key === opts.key && e.state === 'retired');
|
|
122
|
+
for (const tomb of retired.slice(0, -1)) {
|
|
123
|
+
this.entries.splice(this.entries.indexOf(tomb), 1);
|
|
124
|
+
}
|
|
125
|
+
this.entries.push(entry);
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Every recorded entry for one contribution key (live and retired).
|
|
130
|
+
*
|
|
131
|
+
* @param kind - Contribution kind
|
|
132
|
+
* @param key - Contribution key
|
|
133
|
+
* @returns Matching entries in instantiation order
|
|
134
|
+
*/
|
|
135
|
+
find(kind, key) {
|
|
136
|
+
return this.entries.filter((entry) => entry.kind === kind && entry.key === key);
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Logical retirement by instance identity — called by the Host when it
|
|
140
|
+
* stops routing to an instance (removal, hot-reload replace, config reset).
|
|
141
|
+
* Idempotent; the wrapped lifecycle method remains the physical backstop.
|
|
142
|
+
*
|
|
143
|
+
* @param instance - The instance object the Host stopped routing to
|
|
144
|
+
*/
|
|
145
|
+
retireByInstance(instance) {
|
|
146
|
+
for (const entry of this.entries) {
|
|
147
|
+
if (entry.instance === instance)
|
|
148
|
+
entry.state = 'retired';
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Roll back an acceptance of an instance that was validated but never
|
|
153
|
+
* installed (the Host aborted before routing to it). Removes its entry and
|
|
154
|
+
* resurrects the entries it superseded, so "live" again matches what the
|
|
155
|
+
* Host serves. No-op once the entry is not the current live one.
|
|
156
|
+
*
|
|
157
|
+
* @param instance - The accepted-but-never-installed instance
|
|
158
|
+
*/
|
|
159
|
+
discardByInstance(instance) {
|
|
160
|
+
const entry = this.entries.find((e) => e.instance === instance);
|
|
161
|
+
if (!entry || entry.state !== 'live')
|
|
162
|
+
return;
|
|
163
|
+
this.entries.splice(this.entries.indexOf(entry), 1);
|
|
164
|
+
for (const prior of entry.superseded) {
|
|
165
|
+
prior.state = 'live';
|
|
166
|
+
if (!this.entries.includes(prior))
|
|
167
|
+
this.entries.push(prior);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Declarative contribution-kind table — the single source of truth for the
|
|
3
|
+
* plugin contribution pipeline semantics: staging uniqueness, reserved ids,
|
|
4
|
+
* publish ownership, manifest claims, manifest uniqueness and manifest↔
|
|
5
|
+
* registration reconciliation.
|
|
6
|
+
*
|
|
7
|
+
* Adding a contribution kind = one descriptor here + the typed surfaces
|
|
8
|
+
* (PluginApi.registerXxx signature, staging slot, record type/getter, manifest
|
|
9
|
+
* schema field). The staging write path (`push`, via `stageContribution`) and
|
|
10
|
+
* the staged-entry read path (`forEachStaged`, which pairs entries with their
|
|
11
|
+
* keys) both live on the descriptor, so the key↔entry pairing and the
|
|
12
|
+
* uniqueness checks cannot be bypassed or forgotten per kind.
|
|
13
|
+
*
|
|
14
|
+
* Hooks are the deliberate semantic exception (multi-handler per name, no
|
|
15
|
+
* cross-plugin ownership), but their staging write path — priority-sorted Map
|
|
16
|
+
* insert — is also owned here (`hooks.push`), not by `PluginApi.on`.
|
|
17
|
+
*/
|
|
18
|
+
import type { ContributionInstanceTable } from './contribution-instances.js';
|
|
19
|
+
import type { OrderedHookEntry, PluginChannelRegistration, PluginCommandRegistration, PluginProviderRegistration, PluginToolContribution } from './api.js';
|
|
20
|
+
import type { HookServiceRegistration } from '../hooks/types.js';
|
|
21
|
+
import type { PluginManifest } from './manifest.js';
|
|
22
|
+
import type { StagedContributions } from './staging.js';
|
|
23
|
+
/** Field name shared by the manifest `contributes` block and the staging slot. */
|
|
24
|
+
export type ContributionField = 'tools' | 'commands' | 'hooks' | 'services' | 'providers' | 'channels';
|
|
25
|
+
/**
|
|
26
|
+
* Published-record slots. Records are uniformly `{ pluginId, ...entry }`
|
|
27
|
+
* (hooks entries already carry `pluginId`, so they are stored verbatim). The
|
|
28
|
+
* registry's typed getters return these slots; their declared record types are
|
|
29
|
+
* structurally identical, so drift is caught at compile time.
|
|
30
|
+
*/
|
|
31
|
+
export interface ContributionSink {
|
|
32
|
+
tools: ({
|
|
33
|
+
pluginId: string;
|
|
34
|
+
} & PluginToolContribution)[];
|
|
35
|
+
commands: ({
|
|
36
|
+
pluginId: string;
|
|
37
|
+
} & PluginCommandRegistration)[];
|
|
38
|
+
hooks: OrderedHookEntry[];
|
|
39
|
+
services: ({
|
|
40
|
+
pluginId: string;
|
|
41
|
+
} & HookServiceRegistration)[];
|
|
42
|
+
providers: ({
|
|
43
|
+
pluginId: string;
|
|
44
|
+
} & PluginProviderRegistration)[];
|
|
45
|
+
channels: ({
|
|
46
|
+
pluginId: string;
|
|
47
|
+
} & PluginChannelRegistration)[];
|
|
48
|
+
}
|
|
49
|
+
/** Host-private hook that factory-backed records carry (see record.acceptInstance). */
|
|
50
|
+
export interface ContributionInstanceHostHook {
|
|
51
|
+
/**
|
|
52
|
+
* Register the Host-accepted instance (birth) with its config identity.
|
|
53
|
+
*
|
|
54
|
+
* @param instance - The accepted factory product
|
|
55
|
+
* @param label - Config identity of this instantiation
|
|
56
|
+
* @returns Whether the instance is retirement-trackable; false means it was
|
|
57
|
+
* not registered (frozen/sealed) and the Host should surface the
|
|
58
|
+
* degradation — lookup will report it as never instantiated
|
|
59
|
+
*/
|
|
60
|
+
acceptInstance(instance: object, label: string): boolean;
|
|
61
|
+
}
|
|
62
|
+
export interface ContributionKind<TEntry extends object> {
|
|
63
|
+
/** Manifest `contributes.<field>` / staging slot name. */
|
|
64
|
+
readonly field: ContributionField;
|
|
65
|
+
/**
|
|
66
|
+
* Singular label used in diagnostics and ownership keys ("provider"). The
|
|
67
|
+
* ownership key prefix (`tool:`, `provider:`, …) IS this label — changing it
|
|
68
|
+
* changes conflict identity, so treat labels as stable identifiers.
|
|
69
|
+
*/
|
|
70
|
+
readonly label: string;
|
|
71
|
+
/** Whether one key may be owned by only one plugin (hooks chain across plugins). */
|
|
72
|
+
readonly globallyUnique: boolean;
|
|
73
|
+
/** Whether one plugin may stage the same key only once (hooks allow many handlers). */
|
|
74
|
+
readonly perPluginUnique: boolean;
|
|
75
|
+
/** Ids plugins may never claim (built-in adapters). */
|
|
76
|
+
readonly reservedIds: readonly string[];
|
|
77
|
+
/** Unique key of one staged entry. */
|
|
78
|
+
keyOf(entry: TEntry): string;
|
|
79
|
+
/** Keys declared in the manifest `contributes` block (raw, unnormalized). */
|
|
80
|
+
declaredKeys(manifest: PluginManifest): string[];
|
|
81
|
+
/**
|
|
82
|
+
* Iterate staged entries paired with their keys — the read side's single
|
|
83
|
+
* path. The pairing is computed inside the descriptor, so consumers cannot
|
|
84
|
+
* observe a key without its entry or vice versa.
|
|
85
|
+
*/
|
|
86
|
+
forEachStaged(slot: StagedContributions, visit: (key: string, entry: TEntry) => void): void;
|
|
87
|
+
/** Stage one entry — the write side's single path (hooks: priority-sorted Map insert). */
|
|
88
|
+
push(slot: StagedContributions, entry: TEntry): void;
|
|
89
|
+
/** Append one published record to the registry sink. */
|
|
90
|
+
collect(sink: ContributionSink, pluginId: string, entry: TEntry): void;
|
|
91
|
+
/**
|
|
92
|
+
* Factory-backed kinds only: extend the staged entry with the host-private
|
|
93
|
+
* `acceptInstance` hook so the Host can register the instance it accepted
|
|
94
|
+
* (birth) and the table can track its retirement. The wiring lives here,
|
|
95
|
+
* like `push`, so a new factory kind cannot silently produce untracked
|
|
96
|
+
* instances — the return type makes the hook mandatory at compile time.
|
|
97
|
+
*/
|
|
98
|
+
bindInstances?(entry: TEntry, instances: ContributionInstanceTable): TEntry & ContributionInstanceHostHook;
|
|
99
|
+
/** Kind-specific manifest checks beyond per-kind key uniqueness. */
|
|
100
|
+
assertManifestExtras?(manifest: PluginManifest): void;
|
|
101
|
+
/** Kind-specific manifest↔registration reconciliation beyond key matching. */
|
|
102
|
+
reconcileExtra?(manifest: PluginManifest, slot: StagedContributions): void;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Every contribution kind in manifest-schema order. Iteration order is
|
|
106
|
+
* observable in first-failure diagnostics and record ordering — keep it aligned
|
|
107
|
+
* with the `contributes` schema field order.
|
|
108
|
+
*/
|
|
109
|
+
export declare const CONTRIBUTION_KINDS: readonly ContributionKind<object>[];
|
|
110
|
+
/** Typed staging slots for the author-facing register methods. */
|
|
111
|
+
export declare const TOOL_KIND: ContributionKind<PluginToolContribution>;
|
|
112
|
+
export declare const COMMAND_KIND: ContributionKind<PluginCommandRegistration>;
|
|
113
|
+
export declare const HOOK_KIND: ContributionKind<OrderedHookEntry>;
|
|
114
|
+
export declare const SERVICE_KIND: ContributionKind<HookServiceRegistration>;
|
|
115
|
+
export declare const PROVIDER_KIND: ContributionKind<PluginProviderRegistration>;
|
|
116
|
+
export declare const CHANNEL_KIND: ContributionKind<PluginChannelRegistration>;
|
|
117
|
+
/**
|
|
118
|
+
* Reject a manifest key list containing duplicates.
|
|
119
|
+
*
|
|
120
|
+
* @param values - Declared contribution keys
|
|
121
|
+
* @param field - Manifest field path for the error message
|
|
122
|
+
*/
|
|
123
|
+
export declare function assertUnique(values: readonly string[], field: string): void;
|
|
124
|
+
/**
|
|
125
|
+
* Enforce per-kind key uniqueness of the manifest `contributes` block, plus
|
|
126
|
+
* kind-specific manifest checks.
|
|
127
|
+
*
|
|
128
|
+
* @param manifest - Plugin manifest
|
|
129
|
+
* @throws Error naming the first duplicated key
|
|
130
|
+
*/
|
|
131
|
+
export declare function assertManifestKeysUnique(manifest: PluginManifest): void;
|
|
132
|
+
/**
|
|
133
|
+
* Reject a contribution key a plugin may never claim (built-in adapters).
|
|
134
|
+
*
|
|
135
|
+
* @param pluginId - Staging plugin
|
|
136
|
+
* @param kind - Contribution kind being staged
|
|
137
|
+
* @param key - Normalized contribution key
|
|
138
|
+
*/
|
|
139
|
+
export declare function assertClaimable(pluginId: string, kind: ContributionKind<object>, key: string): void;
|
|
140
|
+
/**
|
|
141
|
+
* Reject a duplicate key staged twice by one plugin.
|
|
142
|
+
*
|
|
143
|
+
* @param pluginId - Staging plugin
|
|
144
|
+
* @param kind - Contribution kind being staged
|
|
145
|
+
* @param slot - The plugin's staging area
|
|
146
|
+
* @param key - Normalized contribution key
|
|
147
|
+
*/
|
|
148
|
+
export declare function assertStagingKeyFree(pluginId: string, kind: ContributionKind<object>, slot: StagedContributions, key: string): void;
|
|
149
|
+
/**
|
|
150
|
+
* The staging write path shared by every register method: reserved-id and
|
|
151
|
+
* per-plugin uniqueness checks, then the kind's own staging insert.
|
|
152
|
+
*
|
|
153
|
+
* @param pluginId - Staging plugin
|
|
154
|
+
* @param kind - Contribution kind being staged
|
|
155
|
+
* @param slot - The plugin's staging area
|
|
156
|
+
* @param entry - Contribution entry to stage
|
|
157
|
+
*/
|
|
158
|
+
export declare function stageContribution<TEntry extends object>(pluginId: string, kind: ContributionKind<TEntry>, slot: StagedContributions, entry: TEntry): void;
|
|
159
|
+
/**
|
|
160
|
+
* Manifest-side ownership claim strings ("provider:openai-compat") used by the
|
|
161
|
+
* loader's cross-plugin conflict detection. Kinds without cross-plugin
|
|
162
|
+
* ownership (hooks) declare no claims.
|
|
163
|
+
*
|
|
164
|
+
* @param kind - Contribution kind
|
|
165
|
+
* @param manifest - Candidate manifest
|
|
166
|
+
* @returns Claim strings for every declared key of the kind
|
|
167
|
+
*/
|
|
168
|
+
export declare function declaredClaims(kind: ContributionKind<object>, manifest: PluginManifest): string[];
|
|
169
|
+
/**
|
|
170
|
+
* Reconcile the manifest `contributes` block against what the plugin actually
|
|
171
|
+
* staged: both directions must match exactly, then kind-specific checks run.
|
|
172
|
+
*
|
|
173
|
+
* @param kind - Contribution kind
|
|
174
|
+
* @param manifest - Plugin manifest
|
|
175
|
+
* @param slot - The plugin's staging area
|
|
176
|
+
* @throws Error naming the first mismatched key
|
|
177
|
+
*/
|
|
178
|
+
export declare function assertManifestCoverage(kind: ContributionKind<object>, manifest: PluginManifest, slot: StagedContributions): void;
|