@octopi-agent/engine 0.98.4 → 0.102.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/config-schema/agent.d.ts +35 -5
- package/dist/config-schema/agent.js +24 -4
- package/dist/config-schema/context.d.ts +6 -36
- package/dist/config-schema/context.js +4 -28
- package/dist/config-schema/engine.d.ts +57 -160
- package/dist/config-schema/engine.js +1 -5
- package/dist/config-schema/governance.d.ts +8 -1
- package/dist/config-schema/governance.js +8 -1
- package/dist/config-schema/models.d.ts +2 -8
- package/dist/config-schema/models.js +0 -2
- package/dist/config-schema/run.d.ts +2 -2
- package/dist/config-schema/run.js +2 -2
- package/dist/config-schema/shared.d.ts +0 -3
- package/dist/config-schema/shared.js +0 -2
- package/dist/config-schema/substrate.d.ts +14 -88
- package/dist/config-schema/substrate.js +22 -107
- package/dist/config.d.ts +45 -113
- package/dist/config.js +8 -2
- package/dist/harness/activation/dispatcher.js +7 -0
- package/dist/harness/activation/inbox.d.ts +3 -3
- package/dist/harness/activation/inbox.js +3 -3
- package/dist/harness/activation/runtime.js +13 -5
- package/dist/harness/activation/types.d.ts +2 -2
- package/dist/harness/agent/builder.d.ts +24 -3
- package/dist/harness/agent/builder.js +131 -27
- package/dist/harness/agent/config-bridge.js +9 -2
- package/dist/harness/agent/config-integrity.js +19 -2
- package/dist/harness/agent/wire-agent-builder.d.ts +11 -3
- package/dist/harness/agent/wire-agent-builder.js +26 -7
- package/dist/harness/capabilities/document/factory.d.ts +5 -0
- package/dist/harness/capabilities/document/factory.js +1 -0
- package/dist/harness/capabilities/document/port.js +6 -3
- package/dist/harness/capabilities/document/types.d.ts +5 -0
- package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -1
- package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +1 -1
- package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +2 -2
- package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
- package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
- package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
- package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
- package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
- package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +1 -1
- package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +3 -3
- package/dist/harness/collaboration/delegation/child-run.d.ts +1 -1
- package/dist/harness/collaboration/delegation/child-run.js +4 -4
- package/dist/harness/collaboration/delegation/index.d.ts +1 -1
- package/dist/harness/collaboration/delegation/index.js +1 -1
- package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
- package/dist/harness/collaboration/delegation/notifier.js +8 -1
- package/dist/harness/collaboration/delegation/service.d.ts +2 -0
- package/dist/harness/collaboration/delegation/service.js +2 -1
- package/dist/harness/collaboration/delegation/store.d.ts +2 -0
- package/dist/harness/collaboration/delegation/store.js +2 -1
- package/dist/harness/collaboration/delegation/types.d.ts +23 -2
- package/dist/harness/collaboration/delegation/types.js +22 -0
- package/dist/harness/collaboration/delegation/wiring.js +11 -1
- package/dist/harness/context/budget-allocator.d.ts +26 -18
- package/dist/harness/context/budget-allocator.js +67 -32
- package/dist/harness/context/capabilities/compact/engine.d.ts +0 -6
- package/dist/harness/context/capabilities/compact/engine.js +169 -121
- package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
- package/dist/harness/context/capabilities/compact/handover.js +7 -5
- package/dist/harness/context/capabilities/compact/index.d.ts +5 -1
- package/dist/harness/context/capabilities/compact/index.js +4 -0
- package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
- package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
- package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
- package/dist/harness/context/capabilities/compact/messages.js +91 -0
- package/dist/harness/context/capabilities/compact/types.d.ts +76 -11
- package/dist/harness/context/capabilities/compact/types.js +11 -1
- package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
- package/dist/harness/context/capabilities/compact/view-split.js +72 -0
- package/dist/harness/context/capabilities/summary/port.js +0 -1
- package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
- package/dist/harness/context/capabilities/summary/resolver.js +1 -6
- package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
- package/dist/harness/context/capabilities/summary/types.d.ts +3 -6
- package/dist/harness/context/context-size-ledger.d.ts +143 -0
- package/dist/harness/context/context-size-ledger.js +236 -0
- package/dist/harness/context/default-context-engine.d.ts +195 -119
- package/dist/harness/context/default-context-engine.js +1241 -743
- package/dist/harness/context/index.d.ts +2 -2
- package/dist/harness/context/index.js +1 -1
- package/dist/harness/context/layer-types.d.ts +15 -0
- package/dist/harness/context/layer-types.js +14 -1
- package/dist/harness/context/layers.d.ts +14 -15
- package/dist/harness/context/layers.js +41 -11
- package/dist/harness/context/message-selector.d.ts +10 -8
- package/dist/harness/context/message-selector.js +49 -27
- package/dist/harness/context/summarize.d.ts +2 -2
- package/dist/harness/context/summarize.js +9 -2
- package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
- package/dist/harness/context/system-prompt-assembler.js +2 -1
- package/dist/harness/context/token-constants.d.ts +8 -6
- package/dist/harness/context/token-constants.js +8 -7
- package/dist/harness/context/token-estimate-fns.d.ts +37 -27
- package/dist/harness/context/token-estimate-fns.js +85 -66
- package/dist/harness/context/token-estimator.d.ts +27 -12
- package/dist/harness/context/token-estimator.js +120 -66
- package/dist/harness/context/token-segments.d.ts +88 -0
- package/dist/harness/context/token-segments.js +103 -0
- package/dist/harness/context/tool-result-aging.d.ts +6 -1
- package/dist/harness/context/tool-result-aging.js +16 -5
- package/dist/harness/context/tool-result-body.js +2 -0
- package/dist/harness/context/transform/anchors.d.ts +66 -0
- package/dist/harness/context/transform/anchors.js +125 -0
- package/dist/harness/context/transform/fold.d.ts +56 -0
- package/dist/harness/context/transform/fold.js +135 -0
- package/dist/harness/context/transform/migrate.d.ts +41 -0
- package/dist/harness/context/transform/migrate.js +69 -0
- package/dist/harness/context/transform/types.d.ts +129 -0
- package/dist/harness/context/transform/types.js +19 -0
- package/dist/harness/context/turn-envelope.d.ts +6 -3
- package/dist/harness/context/types.d.ts +127 -117
- package/dist/harness/extension/execution-environment/ops-audit.d.ts +1 -1
- package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
- package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
- package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +1 -1
- package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
- package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
- package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
- package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
- package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
- package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
- package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
- package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
- package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
- package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +83 -249
- package/dist/harness/extension/plugin-ecosystem/plugins/api.js +88 -214
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +43 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +61 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
- package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
- package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
- package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
- package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +50 -117
- package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +316 -285
- package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +23 -490
- package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +85 -353
- package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +41 -223
- package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +138 -19
- package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +15 -0
- package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
- package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
- package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
- package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
- package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
- package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -8
- package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
- package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
- package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
- package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +11 -2
- package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
- package/dist/harness/governance/accounting/usage-ledger.js +23 -1
- package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
- package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
- package/dist/harness/governance/security/capability-enforcer.js +1 -2
- package/dist/harness/index.d.ts +12 -12
- package/dist/harness/index.js +7 -7
- package/dist/harness/knowledge/boot-config.d.ts +55 -0
- package/dist/harness/knowledge/boot-config.js +50 -0
- package/dist/harness/knowledge/catalog-types.d.ts +2 -0
- package/dist/harness/knowledge/client.d.ts +24 -2
- package/dist/harness/knowledge/client.js +19 -5
- package/dist/harness/knowledge/db.js +5 -0
- package/dist/harness/knowledge/describe-sample.d.ts +23 -0
- package/dist/harness/knowledge/describe-sample.js +58 -0
- package/dist/harness/knowledge/describe.d.ts +8 -0
- package/dist/harness/knowledge/describe.js +18 -2
- package/dist/harness/knowledge/engine-thread.js +6 -0
- package/dist/harness/knowledge/grounding.js +3 -1
- package/dist/harness/knowledge/http-app.js +35 -4
- package/dist/harness/knowledge/http-params.d.ts +18 -0
- package/dist/harness/knowledge/http-params.js +24 -0
- package/dist/harness/knowledge/index.d.ts +2 -0
- package/dist/harness/knowledge/index.js +1 -0
- package/dist/harness/knowledge/knowledge-serve-child.js +3 -0
- package/dist/harness/knowledge/purge.js +5 -2
- package/dist/harness/knowledge/query-service.d.ts +13 -2
- package/dist/harness/knowledge/query-service.js +4 -2
- package/dist/harness/knowledge/query-worker-client.d.ts +9 -1
- package/dist/harness/knowledge/query-worker-client.js +4 -2
- package/dist/harness/knowledge/query-worker.js +4 -2
- package/dist/harness/knowledge/read-http.js +5 -1
- package/dist/harness/knowledge/serve.d.ts +8 -7
- package/dist/harness/knowledge/serve.js +9 -0
- package/dist/harness/knowledge/source-store.js +26 -3
- package/dist/harness/knowledge/start-service-process.d.ts +15 -7
- package/dist/harness/knowledge/start-service-process.js +21 -9
- package/dist/harness/knowledge/types.d.ts +7 -0
- package/dist/harness/knowledge/writer-service.d.ts +37 -9
- package/dist/harness/knowledge/writer-service.js +120 -14
- package/dist/harness/knowledge/writer-worker-client.d.ts +10 -9
- package/dist/harness/knowledge/writer-worker-client.js +20 -2
- package/dist/harness/knowledge/writer-worker.js +9 -1
- package/dist/harness/memory/sqlite/wisdom-store.js +35 -10
- package/dist/harness/memory/types.d.ts +6 -4
- package/dist/harness/memory/wisdom-formation.d.ts +14 -3
- package/dist/harness/memory/wisdom-formation.js +85 -22
- package/dist/harness/memory/wisdom-gates.d.ts +14 -0
- package/dist/harness/memory/wisdom-gates.js +59 -19
- package/dist/harness/memory/wisdom.js +9 -0
- package/dist/harness/observability/observer/hub.js +25 -15
- package/dist/harness/observability/observer/types.d.ts +10 -6
- package/dist/harness/run/agent/agent.d.ts +40 -21
- package/dist/harness/run/agent/agent.js +66 -13
- package/dist/harness/run/agent/index.d.ts +1 -1
- package/dist/harness/run/budget/budget.d.ts +28 -10
- package/dist/harness/run/budget/budget.js +38 -15
- package/dist/harness/run/model/index.d.ts +3 -1
- package/dist/harness/run/model/index.js +2 -1
- package/dist/harness/run/model/resolver.d.ts +4 -1
- package/dist/harness/run/model/resolver.js +36 -2
- package/dist/harness/run/model/run-scope.d.ts +2 -0
- package/dist/harness/run/model/run-scope.js +7 -0
- package/dist/harness/run/model/types.d.ts +22 -5
- package/dist/harness/run/model/types.js +3 -2
- package/dist/harness/run/model/window-truth.d.ts +37 -0
- package/dist/harness/run/model/window-truth.js +39 -0
- package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
- package/dist/harness/run/reliability/context-length-feedback.js +128 -0
- package/dist/harness/run/reliability/harness-events.d.ts +3 -3
- package/dist/harness/run/reliability/model-error-policy.js +4 -0
- package/dist/harness/run/reliability/run-agent.d.ts +10 -4
- package/dist/harness/run/reliability/run-agent.js +137 -53
- package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
- package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
- package/dist/harness/run/run-guard/default-run-guard.js +8 -8
- package/dist/harness/run/run-scope.d.ts +37 -4
- package/dist/harness/run/runner.d.ts +44 -29
- package/dist/harness/run/runner.js +320 -102
- package/dist/harness/session/attachments/index.d.ts +1 -0
- package/dist/harness/session/attachments/index.js +1 -0
- package/dist/harness/session/attachments/inject.d.ts +21 -10
- package/dist/harness/session/attachments/inject.js +76 -24
- package/dist/harness/session/attachments/recall-index.d.ts +70 -0
- package/dist/harness/session/attachments/recall-index.js +219 -0
- package/dist/harness/session/attachments/service.d.ts +21 -0
- package/dist/harness/session/attachments/service.js +258 -139
- package/dist/harness/session/attachments/types.d.ts +6 -0
- package/dist/harness/session/transform-store.d.ts +136 -0
- package/dist/harness/session/transform-store.js +302 -0
- package/dist/harness/session/types.d.ts +2 -2
- package/dist/harness/shared/events/agent-event-map.d.ts +46 -13
- package/dist/harness/shared/events/agent-event-map.js +3 -2
- package/dist/harness/shared/events/scenario-events.d.ts +6 -6
- package/dist/harness/shared/types/agent-definition.d.ts +1 -2
- package/dist/index.d.ts +14 -17
- package/dist/index.js +7 -9
- package/dist/integration/observability/metrics.d.ts +6 -6
- package/dist/integration/observability/metrics.js +13 -13
- package/dist/integration/observability/observer-bridge.js +2 -2
- package/dist/integration/observability/trace-collector.d.ts +5 -5
- package/dist/integration/observability/trace-collector.js +34 -35
- package/dist/integration/observability/trace-events.d.ts +3 -3
- package/dist/integration/observability/trace-events.js +3 -3
- package/dist/integration/providers/anthropic.js +14 -1
- package/dist/integration/providers/openai.js +7 -1
- package/dist/integration/providers/usage.d.ts +1 -1
- package/dist/integration/providers/wire-dump.d.ts +1 -1
- package/dist/integration/storage/archive-manager.d.ts +6 -0
- package/dist/integration/storage/archive-manager.js +10 -0
- package/dist/integration/storage/jsonl.d.ts +1 -1
- package/dist/integration/storage/jsonl.js +18 -16
- package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
- package/dist/subsystems/wisdom-steward/formation/config.yaml +1 -0
- package/dist/subsystems/wisdom-steward/formation/handler.js +27 -5
- package/package.json +11 -14
- package/dist/harness/context/hybrid-compressor.d.ts +0 -41
- package/dist/harness/context/hybrid-compressor.js +0 -159
- package/dist/harness/context/llm-summarizer.d.ts +0 -46
- package/dist/harness/context/llm-summarizer.js +0 -249
- package/dist/harness/context/smart-router.d.ts +0 -75
- package/dist/harness/context/smart-router.js +0 -118
- package/dist/harness/context/truncate-compressor.d.ts +0 -28
- package/dist/harness/context/truncate-compressor.js +0 -107
- package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
- package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
- package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
- package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
- package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
- package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { CompactEngine, CompactOptions, CompactOutcome } from '../../../context/capabilities/compact/index.js';
|
|
2
|
+
import type { ExtensionHookPort } from './types.js';
|
|
3
|
+
/** Keep Hook admission outside compaction algorithms and the E4 state transition. */
|
|
4
|
+
export declare class HookedCompactEngine implements CompactEngine {
|
|
5
|
+
private readonly inner;
|
|
6
|
+
private readonly port;
|
|
7
|
+
private readonly identity;
|
|
8
|
+
constructor(inner: CompactEngine, port: ExtensionHookPort, identity: {
|
|
9
|
+
sessionId: string;
|
|
10
|
+
agentId?: string;
|
|
11
|
+
});
|
|
12
|
+
/** Text compaction is not a Session compaction event. */
|
|
13
|
+
compactText(text: string, options?: CompactOptions): Promise<CompactOutcome>;
|
|
14
|
+
/** Vote before any summary work; observe the actual success/degraded/fresh result. */
|
|
15
|
+
compactMessages(messages: Parameters<CompactEngine['compactMessages']>[0], options: CompactOptions): Promise<CompactOutcome>;
|
|
16
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { getRunScope } from '../../../run/run-scope.js';
|
|
2
|
+
import { HeuristicTokenEstimator } from '../../../context/token-estimator.js';
|
|
3
|
+
/** Keep Hook admission outside compaction algorithms and the E4 state transition. */
|
|
4
|
+
export class HookedCompactEngine {
|
|
5
|
+
inner;
|
|
6
|
+
port;
|
|
7
|
+
identity;
|
|
8
|
+
constructor(inner, port, identity) {
|
|
9
|
+
this.inner = inner;
|
|
10
|
+
this.port = port;
|
|
11
|
+
this.identity = identity;
|
|
12
|
+
}
|
|
13
|
+
/** Text compaction is not a Session compaction event. */
|
|
14
|
+
compactText(text, options) {
|
|
15
|
+
return this.inner.compactText(text, options);
|
|
16
|
+
}
|
|
17
|
+
/** Vote before any summary work; observe the actual success/degraded/fresh result. */
|
|
18
|
+
async compactMessages(messages, options) {
|
|
19
|
+
const scope = getRunScope();
|
|
20
|
+
const event = {
|
|
21
|
+
// Explicit caller identity wins: a manual compaction must not be attributed
|
|
22
|
+
// to whatever Run happens to hold the async context.
|
|
23
|
+
sessionId: options.sessionId ?? scope?.sessionId ?? this.identity.sessionId,
|
|
24
|
+
agentId: options.agentId ?? scope?.agentId ?? this.identity.agentId ?? 'default',
|
|
25
|
+
...(scope?.runId === undefined ? {} : { runId: scope.runId }),
|
|
26
|
+
...(scope?.principal === undefined ? {} : { principal: scope.principal }),
|
|
27
|
+
...(options.signal === undefined ? {} : { signal: options.signal }),
|
|
28
|
+
mode: options.mode ?? 'auto',
|
|
29
|
+
previousSummary: options.previousSummary,
|
|
30
|
+
};
|
|
31
|
+
const vote = await this.port.vote('before_compaction', event);
|
|
32
|
+
if (vote.decision !== 'allow') {
|
|
33
|
+
return {
|
|
34
|
+
ok: true,
|
|
35
|
+
summary: options.previousSummary,
|
|
36
|
+
compacted: false,
|
|
37
|
+
reason: `denied:${vote.reason ?? 'before_compaction'}`,
|
|
38
|
+
tokensBefore: options.estimator?.estimateMessages(messages)
|
|
39
|
+
?? new HeuristicTokenEstimator().estimateMessages(messages),
|
|
40
|
+
summarizeAttempted: false,
|
|
41
|
+
fresh: false,
|
|
42
|
+
view: [...messages],
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
try {
|
|
46
|
+
const outcome = await this.inner.compactMessages(messages, options);
|
|
47
|
+
await this.port.observe('after_compaction', {
|
|
48
|
+
...event,
|
|
49
|
+
coveredMessageCount: options.foldRange?.replacedCount,
|
|
50
|
+
compacted: outcome.compacted,
|
|
51
|
+
fresh: outcome.fresh,
|
|
52
|
+
reason: outcome.reason,
|
|
53
|
+
});
|
|
54
|
+
return outcome;
|
|
55
|
+
}
|
|
56
|
+
catch (error) {
|
|
57
|
+
await this.port.observe('after_compaction', {
|
|
58
|
+
...event,
|
|
59
|
+
compacted: false,
|
|
60
|
+
fresh: false,
|
|
61
|
+
error: error instanceof Error ? error.message : String(error),
|
|
62
|
+
});
|
|
63
|
+
throw error;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { PluginHookAdapter, HookDeniedError, requireHookApproval } from './adapter.js';
|
|
2
|
+
export type { HookExecutionHost, RegisteredHook } from './adapter.js';
|
|
3
|
+
export { HookAuditJournal } from './journal.js';
|
|
4
|
+
export type { ExtensionHookContext, ExtensionHookHandler, ExtensionHookMap, ExtensionHookPort, HookAuditRecord, HookCollectResult, HookContribution, HookEvent, HookIterationEvent, HookIterationTransform, HookModelSelection, HookResult, HookSemantics, HookServiceRegistration, HookToolApproval, HookToolEvent, HookTransformResult, HookVote, } from './types.js';
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { LLMMessage } from '@octopi-agent/core/interfaces/model-provider.js';
|
|
2
|
+
/**
|
|
3
|
+
* Build a Run/Iteration-only view. The authoritative turn_start remains byte-frozen.
|
|
4
|
+
* No system role is added and plugin content cannot masquerade as a user stimulus.
|
|
5
|
+
*/
|
|
6
|
+
export declare function projectPluginIterationSnapshot(messages: LLMMessage[], contributions: readonly {
|
|
7
|
+
pluginId: string;
|
|
8
|
+
text: string;
|
|
9
|
+
}[], tokenBudget: number): Promise<LLMMessage[]>;
|
|
10
|
+
/** Apply the configured token budget before the snapshot reaches a model request. */
|
|
11
|
+
export declare function iterationSnapshotTokenBudget(configured: number | undefined, contextWindow: number | undefined): number;
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { formatTurnContextXml, formatTurnStartContent, joinSlotXml, parseTurnEnvelope, } from '../../../context/turn-envelope.js';
|
|
2
|
+
import { PluginRuntimeSnapshotLayer } from '../../../context/layers.js';
|
|
3
|
+
/**
|
|
4
|
+
* Build a Run/Iteration-only view. The authoritative turn_start remains byte-frozen.
|
|
5
|
+
* No system role is added and plugin content cannot masquerade as a user stimulus.
|
|
6
|
+
*/
|
|
7
|
+
export async function projectPluginIterationSnapshot(messages, contributions, tokenBudget) {
|
|
8
|
+
if (contributions.length === 0)
|
|
9
|
+
return messages;
|
|
10
|
+
const layer = new PluginRuntimeSnapshotLayer(contributions.map(({ pluginId, text }) => ({ pluginId, value: { text } })));
|
|
11
|
+
const projected = await layer.assemble({
|
|
12
|
+
sessionId: 'run',
|
|
13
|
+
messages: [],
|
|
14
|
+
tokenBudget: Math.max(1, tokenBudget),
|
|
15
|
+
systemBudget: 0,
|
|
16
|
+
});
|
|
17
|
+
if (!projected)
|
|
18
|
+
return messages;
|
|
19
|
+
const index = messages.findLastIndex((message) => parseTurnEnvelope(message.content) !== null);
|
|
20
|
+
if (index < 0)
|
|
21
|
+
throw new Error('before_iteration snapshot requires a current turn_start envelope');
|
|
22
|
+
const original = messages[index];
|
|
23
|
+
const parsed = parseTurnEnvelope(original.content);
|
|
24
|
+
if (!parsed.turnId || !parsed.at || !parsed.hasUserMessage) {
|
|
25
|
+
throw new Error('before_iteration snapshot cannot rewrite an incomplete turn envelope');
|
|
26
|
+
}
|
|
27
|
+
const slots = parsed.slots.map((slot) => ({ tag: slot.tag, body: slot.body }));
|
|
28
|
+
const runtime = slots.find((slot) => slot.tag === 'runtime_snapshot');
|
|
29
|
+
if (runtime)
|
|
30
|
+
runtime.body = [runtime.body, projected.text].filter(Boolean).join('\n\n');
|
|
31
|
+
else
|
|
32
|
+
slots.unshift({ tag: 'runtime_snapshot', body: projected.text });
|
|
33
|
+
const content = formatTurnStartContent({
|
|
34
|
+
turnId: parsed.turnId,
|
|
35
|
+
at: parsed.at,
|
|
36
|
+
turnContextXml: formatTurnContextXml({ turnId: parsed.turnId, slotsXml: joinSlotXml(slots) }),
|
|
37
|
+
userText: parsed.userText,
|
|
38
|
+
});
|
|
39
|
+
const copy = { ...original };
|
|
40
|
+
if (typeof original.content === 'string' || original.content == null)
|
|
41
|
+
copy.content = content;
|
|
42
|
+
else if (Array.isArray(original.content)) {
|
|
43
|
+
copy.content = [
|
|
44
|
+
{ type: 'text', text: content },
|
|
45
|
+
...original.content.filter((block) => block.type !== 'text'),
|
|
46
|
+
];
|
|
47
|
+
}
|
|
48
|
+
return [...messages.slice(0, index), copy, ...messages.slice(index + 1)];
|
|
49
|
+
}
|
|
50
|
+
/** Apply the configured token budget before the snapshot reaches a model request. */
|
|
51
|
+
export function iterationSnapshotTokenBudget(configured, contextWindow) {
|
|
52
|
+
const cap = Math.max(1, Math.floor((contextWindow ?? 8192) * 0.1));
|
|
53
|
+
return Math.max(1, Math.min(configured ?? 4096, cap));
|
|
54
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { HookAuditRecord } from './types.js';
|
|
2
|
+
/** Append-only hook audit; not a tamper-evident ledger or a sandbox. */
|
|
3
|
+
export declare class HookAuditJournal {
|
|
4
|
+
private readonly rootDir;
|
|
5
|
+
private tail;
|
|
6
|
+
constructor(rootDir: () => string);
|
|
7
|
+
/** Serialize appends per journal instance and surface write failures to the Host. */
|
|
8
|
+
append(record: HookAuditRecord): Promise<void>;
|
|
9
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { appendFile, mkdir } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
/** Append-only hook audit; not a tamper-evident ledger or a sandbox. */
|
|
4
|
+
export class HookAuditJournal {
|
|
5
|
+
rootDir;
|
|
6
|
+
tail = Promise.resolve();
|
|
7
|
+
constructor(rootDir) {
|
|
8
|
+
this.rootDir = rootDir;
|
|
9
|
+
}
|
|
10
|
+
/** Serialize appends per journal instance and surface write failures to the Host. */
|
|
11
|
+
append(record) {
|
|
12
|
+
const task = this.tail.then(async () => {
|
|
13
|
+
const directory = join(this.rootDir(), 'hooks');
|
|
14
|
+
await mkdir(directory, { recursive: true });
|
|
15
|
+
const day = new Date().toISOString().slice(0, 10);
|
|
16
|
+
const entry = { timestamp: Date.now(), ...record };
|
|
17
|
+
await appendFile(join(directory, `${day}.jsonl`), `${JSON.stringify(entry)}\n`, 'utf8');
|
|
18
|
+
});
|
|
19
|
+
this.tail = task.catch(() => undefined);
|
|
20
|
+
return task;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
declare const terminalMarker: unique symbol;
|
|
2
|
+
/** A Host-controlled extension failure must not enter the model transport retry policy. */
|
|
3
|
+
export declare class ExtensionTerminalError extends Error {
|
|
4
|
+
readonly cause: unknown;
|
|
5
|
+
readonly [terminalMarker] = true;
|
|
6
|
+
constructor(cause: unknown);
|
|
7
|
+
}
|
|
8
|
+
/** This is a Host/reliability policy, not a Core or Plugin contract. */
|
|
9
|
+
export declare function shouldAbortWithoutRetry(error: unknown): boolean;
|
|
10
|
+
/** Restore the extension failure to the normal Agent error-event surface. */
|
|
11
|
+
export declare function unwrapExtensionTerminalError(error: unknown): unknown;
|
|
12
|
+
export {};
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
const terminalMarker = Symbol('octopi.extension-terminal');
|
|
2
|
+
/** A Host-controlled extension failure must not enter the model transport retry policy. */
|
|
3
|
+
export class ExtensionTerminalError extends Error {
|
|
4
|
+
cause;
|
|
5
|
+
[terminalMarker] = true;
|
|
6
|
+
constructor(cause) {
|
|
7
|
+
super(cause instanceof Error ? cause.message : String(cause));
|
|
8
|
+
this.cause = cause;
|
|
9
|
+
this.name = 'ExtensionTerminalError';
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
/** This is a Host/reliability policy, not a Core or Plugin contract. */
|
|
13
|
+
export function shouldAbortWithoutRetry(error) {
|
|
14
|
+
return typeof error === 'object' && error !== null && terminalMarker in error;
|
|
15
|
+
}
|
|
16
|
+
/** Restore the extension failure to the normal Agent error-event surface. */
|
|
17
|
+
export function unwrapExtensionTerminalError(error) {
|
|
18
|
+
return error instanceof ExtensionTerminalError ? error.cause : error;
|
|
19
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { AgentContext, AgentLoopConfig, BeforeToolCallContext } from '@octopi-agent/core/loop/types.js';
|
|
2
|
+
import type { RunScope } from '../../../run/run-scope.js';
|
|
3
|
+
import type { HarnessLoopEvent } from '../../../run/reliability/harness-events.js';
|
|
4
|
+
import type { ExtensionHookPort } from './types.js';
|
|
5
|
+
export interface AgentExtensionHookIntegration {
|
|
6
|
+
prepareToolArguments: AgentLoopConfig['prepareToolArguments'];
|
|
7
|
+
onToolCallComplete: AgentLoopConfig['onToolCallComplete'];
|
|
8
|
+
beforeStep: AgentLoopConfig['beforeStep'];
|
|
9
|
+
onStepComplete: AgentLoopConfig['onStepComplete'];
|
|
10
|
+
}
|
|
11
|
+
/** Per-Run mutable projections shared with Core's existing config callbacks. */
|
|
12
|
+
export declare class AgentExtensionHookState {
|
|
13
|
+
private readonly port;
|
|
14
|
+
private readonly scope;
|
|
15
|
+
readonly originalToolParams: WeakMap<import("@octopi-agent/core").ToolCall, Readonly<Record<string, unknown>>>;
|
|
16
|
+
private iterationSnapshots;
|
|
17
|
+
private readonly originalOnStepComplete;
|
|
18
|
+
private readonly originalBeforeStep;
|
|
19
|
+
private readonly originalTransformLlmMessages;
|
|
20
|
+
constructor(port: ExtensionHookPort, scope: () => RunScope, config: AgentLoopConfig);
|
|
21
|
+
/** Project only the normalized Provider request, never the Run's message workspace. */
|
|
22
|
+
transformLlmMessages(messages: import('@octopi-agent/core/interfaces/model-provider.js').LLMMessage[]): Promise<import('@octopi-agent/core/interfaces/model-provider.js').LLMMessage[]>;
|
|
23
|
+
callbacks(): AgentExtensionHookIntegration;
|
|
24
|
+
private context;
|
|
25
|
+
private prepareToolArguments;
|
|
26
|
+
private onToolCallComplete;
|
|
27
|
+
private beforeStep;
|
|
28
|
+
private prepareStep;
|
|
29
|
+
private onStepComplete;
|
|
30
|
+
}
|
|
31
|
+
/** Enriches Loop config with per-Run hook callbacks; no plugin type enters Core. */
|
|
32
|
+
export declare function integrateAgentHooks(port: ExtensionHookPort | undefined, config: AgentLoopConfig, scope: () => RunScope): AgentExtensionHookState | undefined;
|
|
33
|
+
/** Host Run-level Vote/Override/Observe, outside the reliability loop. */
|
|
34
|
+
export declare function withAgentRunHooks(port: ExtensionHookPort | undefined, scope: RunScope, context: AgentContext, signal: AbortSignal | undefined, gen: AsyncGenerator<HarnessLoopEvent>): AsyncGenerator<HarnessLoopEvent>;
|
|
35
|
+
/** Build the Host Run tool Vote after SecurityGuard and before raw execution. */
|
|
36
|
+
export declare function voteAgentToolCall(port: ExtensionHookPort | undefined, ctx: BeforeToolCallContext, originalParams: WeakMap<BeforeToolCallContext['toolCall'], Readonly<Record<string, unknown>>>, signal?: AbortSignal): Promise<import('@octopi-agent/core/loop/types.js').BeforeToolCallResult | undefined>;
|
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
import { getTextContent } from '@octopi-agent/core/types.js';
|
|
2
|
+
import { getRunScope } from '../../../run/run-scope.js';
|
|
3
|
+
import { HookDeniedError } from './adapter.js';
|
|
4
|
+
import { ExtensionTerminalError, shouldAbortWithoutRetry, unwrapExtensionTerminalError } from './policy-error.js';
|
|
5
|
+
/** Per-Run mutable projections shared with Core's existing config callbacks. */
|
|
6
|
+
export class AgentExtensionHookState {
|
|
7
|
+
port;
|
|
8
|
+
scope;
|
|
9
|
+
originalToolParams = new WeakMap();
|
|
10
|
+
iterationSnapshots = new Map();
|
|
11
|
+
originalOnStepComplete;
|
|
12
|
+
originalBeforeStep;
|
|
13
|
+
originalTransformLlmMessages;
|
|
14
|
+
constructor(port, scope, config) {
|
|
15
|
+
this.port = port;
|
|
16
|
+
this.scope = scope;
|
|
17
|
+
this.originalOnStepComplete = config.onStepComplete;
|
|
18
|
+
this.originalBeforeStep = config.beforeStep;
|
|
19
|
+
this.originalTransformLlmMessages = config.transformLlmMessages;
|
|
20
|
+
}
|
|
21
|
+
/** Project only the normalized Provider request, never the Run's message workspace. */
|
|
22
|
+
async transformLlmMessages(messages) {
|
|
23
|
+
const index = Math.max(0, (this.scope().iteration ?? 1) - 1);
|
|
24
|
+
const snapshot = this.iterationSnapshots.get(index);
|
|
25
|
+
const current = this.originalTransformLlmMessages
|
|
26
|
+
? await this.originalTransformLlmMessages(messages)
|
|
27
|
+
: messages;
|
|
28
|
+
if (!snapshot)
|
|
29
|
+
return current;
|
|
30
|
+
const { projectPluginIterationSnapshot } = await import('./iteration-snapshot.js');
|
|
31
|
+
return projectPluginIterationSnapshot(current, snapshot.contributions, snapshot.tokenBudget);
|
|
32
|
+
}
|
|
33
|
+
callbacks() {
|
|
34
|
+
return {
|
|
35
|
+
prepareToolArguments: async (ctx, signal) => this.prepareToolArguments(ctx, signal),
|
|
36
|
+
onToolCallComplete: async (ctx) => this.onToolCallComplete(ctx),
|
|
37
|
+
beforeStep: async (ctx) => this.beforeStep(ctx),
|
|
38
|
+
onStepComplete: async (ctx) => {
|
|
39
|
+
// Finalize first: empty-reply/planning detection, step summaries, events and
|
|
40
|
+
// persistence must all see the finalized reply — not the raw model output.
|
|
41
|
+
await this.onStepComplete(ctx);
|
|
42
|
+
await this.originalOnStepComplete?.(ctx);
|
|
43
|
+
},
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
context(signal) {
|
|
47
|
+
const scope = this.scope();
|
|
48
|
+
return {
|
|
49
|
+
sessionId: scope.sessionId,
|
|
50
|
+
agentId: scope.agentId,
|
|
51
|
+
...(scope.runId === undefined ? {} : { runId: scope.runId }),
|
|
52
|
+
...(scope.principal === undefined ? {} : { principal: scope.principal }),
|
|
53
|
+
...(signal === undefined ? {} : { signal }),
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
async prepareToolArguments(ctx, signal) {
|
|
57
|
+
// No registered handler → nothing to attribute; skip event construction and
|
|
58
|
+
// the Run-identity requirement (direct Agent.run() must keep working idle).
|
|
59
|
+
if (!this.port.hasHooks('before_tool_call'))
|
|
60
|
+
return ctx.args;
|
|
61
|
+
const scope = this.scope();
|
|
62
|
+
if (!scope.runId)
|
|
63
|
+
throw new Error('before_tool_call requires a Host Run identity');
|
|
64
|
+
if (ctx.args === null || typeof ctx.args !== 'object' || Array.isArray(ctx.args))
|
|
65
|
+
return ctx.args;
|
|
66
|
+
const original = ctx.args;
|
|
67
|
+
const result = await this.port.transformBeforeToolCall({
|
|
68
|
+
...this.context(signal),
|
|
69
|
+
runId: scope.runId,
|
|
70
|
+
toolName: ctx.toolCall.name,
|
|
71
|
+
call: ctx.toolCall,
|
|
72
|
+
params: original,
|
|
73
|
+
});
|
|
74
|
+
this.originalToolParams.set(ctx.toolCall, { ...original });
|
|
75
|
+
const value = result.value;
|
|
76
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value)) {
|
|
77
|
+
// Fail-closed for this call: tool validation, SecurityGuard and audit all
|
|
78
|
+
// inspect a plain parameter record; a non-record transform hides the payload.
|
|
79
|
+
throw new Error('before_tool_call transform must return a plain object of parameters');
|
|
80
|
+
}
|
|
81
|
+
return value;
|
|
82
|
+
}
|
|
83
|
+
async onToolCallComplete(ctx) {
|
|
84
|
+
if (!this.port.hasHooks('after_tool_call'))
|
|
85
|
+
return;
|
|
86
|
+
const scope = this.scope();
|
|
87
|
+
if (!scope.runId)
|
|
88
|
+
return;
|
|
89
|
+
const params = (ctx.args ?? {});
|
|
90
|
+
await this.port.observe('after_tool_call', {
|
|
91
|
+
...this.context(),
|
|
92
|
+
runId: scope.runId,
|
|
93
|
+
call: ctx.toolCall,
|
|
94
|
+
originalParams: this.originalToolParams.get(ctx.toolCall) ?? params,
|
|
95
|
+
params,
|
|
96
|
+
result: ctx.result,
|
|
97
|
+
...(ctx.result.isError ? { error: getTextContent(String(ctx.result.content ?? '')) } : {}),
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
async beforeStep(ctx) {
|
|
101
|
+
try {
|
|
102
|
+
return await this.prepareStep(ctx);
|
|
103
|
+
}
|
|
104
|
+
catch (error) {
|
|
105
|
+
throw new ExtensionTerminalError(error);
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
async prepareStep(ctx) {
|
|
109
|
+
const originalUpdate = await this.originalBeforeStep?.(ctx);
|
|
110
|
+
const scope = this.scope();
|
|
111
|
+
// Iteration bookkeeping also serves after_iteration observations: keep it
|
|
112
|
+
// outside the before_iteration short-circuit or the counter stays at 0.
|
|
113
|
+
scope.iteration = ctx.iteration + 1;
|
|
114
|
+
if (!this.port.hasHooks('before_iteration'))
|
|
115
|
+
return originalUpdate;
|
|
116
|
+
const currentModel = scope.resolvedModel;
|
|
117
|
+
if (!scope.runId || !currentModel)
|
|
118
|
+
throw new Error('before_iteration requires a resolved Host model and Run identity');
|
|
119
|
+
const result = await this.port.beforeIteration({
|
|
120
|
+
...this.context(),
|
|
121
|
+
runId: scope.runId,
|
|
122
|
+
iteration: ctx.iteration,
|
|
123
|
+
messages: ctx.context.messages,
|
|
124
|
+
model: { provider: currentModel.providerName, model: currentModel.modelName },
|
|
125
|
+
thinking: scope.thinkingLevel,
|
|
126
|
+
});
|
|
127
|
+
if (result.vote.decision !== 'allow') {
|
|
128
|
+
throw new HookDeniedError(result.vote, 'before_iteration');
|
|
129
|
+
}
|
|
130
|
+
let resolved = currentModel;
|
|
131
|
+
if (result.transform.model) {
|
|
132
|
+
if (!scope.resolveConfiguredModel) {
|
|
133
|
+
throw new Error('before_iteration model Transform has no Host model resolver');
|
|
134
|
+
}
|
|
135
|
+
const next = await scope.resolveConfiguredModel(result.transform.model);
|
|
136
|
+
if (!next)
|
|
137
|
+
throw new Error(`before_iteration selected an unconfigured model: ${result.transform.model.provider}/${result.transform.model.model}`);
|
|
138
|
+
resolved = next;
|
|
139
|
+
}
|
|
140
|
+
scope.resolvedModel = resolved;
|
|
141
|
+
// Consensus transform: undefined means "no opinion", never "clear".
|
|
142
|
+
if (result.transform.thinking !== undefined)
|
|
143
|
+
scope.thinkingLevel = result.transform.thinking;
|
|
144
|
+
if (resolved !== currentModel) {
|
|
145
|
+
const { updateResolvedModel } = await import('../../../run/model/run-scope.js');
|
|
146
|
+
updateResolvedModel(resolved);
|
|
147
|
+
}
|
|
148
|
+
if (result.transform.snapshot !== undefined) {
|
|
149
|
+
this.iterationSnapshots.set(ctx.iteration, {
|
|
150
|
+
contributions: result.snapshotContributions.map((contribution) => ({
|
|
151
|
+
pluginId: contribution.pluginId,
|
|
152
|
+
text: contribution.value,
|
|
153
|
+
})),
|
|
154
|
+
tokenBudget: Math.max(1, Math.min(scope.extensionSnapshotBudgetTokens ?? 4096, Math.floor((resolved.contextWindow ?? 8192) * 0.1))),
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
else {
|
|
158
|
+
this.iterationSnapshots.delete(ctx.iteration);
|
|
159
|
+
}
|
|
160
|
+
return {
|
|
161
|
+
...originalUpdate,
|
|
162
|
+
...(resolved === currentModel ? {} : { model: resolved.provider }),
|
|
163
|
+
...(result.transform.thinking === undefined ? {} : { thinkingLevel: result.transform.thinking }),
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
async onStepComplete(ctx) {
|
|
167
|
+
const wantsFinalize = this.port.hasHooks('before_agent_finalize');
|
|
168
|
+
const wantsObserve = this.port.hasHooks('after_iteration');
|
|
169
|
+
if (!wantsFinalize && !wantsObserve)
|
|
170
|
+
return;
|
|
171
|
+
const scope = this.scope();
|
|
172
|
+
// Finalize needs only the Run identity; after_iteration additionally reports
|
|
173
|
+
// the resolved model — separate gates so a missing model never silently
|
|
174
|
+
// swallows a registered finalize.
|
|
175
|
+
if (!scope.runId)
|
|
176
|
+
return;
|
|
177
|
+
if (wantsFinalize && !ctx.message.toolCalls?.length) {
|
|
178
|
+
const transformed = await this.port.transform('before_agent_finalize', {
|
|
179
|
+
...this.context(),
|
|
180
|
+
runId: scope.runId,
|
|
181
|
+
reply: ctx.message,
|
|
182
|
+
}, ctx.message);
|
|
183
|
+
const next = transformed.value;
|
|
184
|
+
if (ctx.context.messages.lastIndexOf(ctx.message) < 0) {
|
|
185
|
+
throw new Error('before_agent_finalize candidate is absent from RunScope messages');
|
|
186
|
+
}
|
|
187
|
+
// Mutate in place only: the message store slot, the event copy and the loop's
|
|
188
|
+
// message must stay one identity. Replacing the slot with the plugin's object
|
|
189
|
+
// forks persistence from events and drops timestamp/metadata on the stored side.
|
|
190
|
+
Object.assign(ctx.message, next);
|
|
191
|
+
}
|
|
192
|
+
if (!wantsObserve || !scope.resolvedModel)
|
|
193
|
+
return;
|
|
194
|
+
await this.port.observe('after_iteration', {
|
|
195
|
+
...this.context(),
|
|
196
|
+
runId: scope.runId,
|
|
197
|
+
iteration: Math.max(0, (scope.iteration ?? 1) - 1),
|
|
198
|
+
messages: ctx.context.messages,
|
|
199
|
+
model: { provider: scope.resolvedModel.providerName, model: scope.resolvedModel.modelName },
|
|
200
|
+
...(scope.thinkingLevel === undefined ? {} : { thinking: scope.thinkingLevel }),
|
|
201
|
+
assistantMessage: ctx.context.messages.find((message) => message === ctx.message) ?? ctx.message,
|
|
202
|
+
toolResults: ctx.toolResults,
|
|
203
|
+
});
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
/** Enriches Loop config with per-Run hook callbacks; no plugin type enters Core. */
|
|
207
|
+
export function integrateAgentHooks(port, config, scope) {
|
|
208
|
+
if (!port)
|
|
209
|
+
return undefined;
|
|
210
|
+
return new AgentExtensionHookState(port, scope, config);
|
|
211
|
+
}
|
|
212
|
+
/** Host Run-level Vote/Override/Observe, outside the reliability loop. */
|
|
213
|
+
export async function* withAgentRunHooks(port, scope, context, signal, gen) {
|
|
214
|
+
if (!port) {
|
|
215
|
+
yield* gen;
|
|
216
|
+
return;
|
|
217
|
+
}
|
|
218
|
+
const startedAt = Date.now();
|
|
219
|
+
const runId = scope.runId ?? `unidentified:${scope.sessionId}:${scope.agentId}`;
|
|
220
|
+
const base = {
|
|
221
|
+
sessionId: scope.sessionId,
|
|
222
|
+
agentId: scope.agentId,
|
|
223
|
+
runId,
|
|
224
|
+
...(scope.principal === undefined ? {} : { principal: scope.principal }),
|
|
225
|
+
...(signal === undefined ? {} : { signal }),
|
|
226
|
+
};
|
|
227
|
+
let reason = 'completed';
|
|
228
|
+
let success = true;
|
|
229
|
+
let failure;
|
|
230
|
+
let iterations = 0;
|
|
231
|
+
try {
|
|
232
|
+
const prompt = scope.prompt ?? getTextContent([...context.messages].reverse().find((message) => message.role === 'user')?.content ?? '');
|
|
233
|
+
const runEvent = { ...base, runId, prompt, messages: context.messages };
|
|
234
|
+
const vote = await port.vote('before_agent_run', runEvent);
|
|
235
|
+
if (vote.decision !== 'allow')
|
|
236
|
+
throw new HookDeniedError(vote, 'before_agent_run');
|
|
237
|
+
const override = await port.override('before_agent_reply', runEvent);
|
|
238
|
+
if (override) {
|
|
239
|
+
const finalized = await port.transform('before_agent_finalize', { ...base, runId, reply: override }, override);
|
|
240
|
+
const reply = {
|
|
241
|
+
...finalized.value,
|
|
242
|
+
agentId: finalized.value.agentId ?? scope.agentId,
|
|
243
|
+
timestamp: finalized.value.timestamp ?? Date.now(),
|
|
244
|
+
};
|
|
245
|
+
context.messages.push(reply);
|
|
246
|
+
yield { type: 'agent_start', timestamp: Date.now() };
|
|
247
|
+
yield { type: 'step_start', timestamp: Date.now() };
|
|
248
|
+
yield { type: 'assistant_message', message: reply, timestamp: Date.now() };
|
|
249
|
+
yield { type: 'step_end', hasToolCalls: false, phase: 'final' };
|
|
250
|
+
iterations = 1;
|
|
251
|
+
yield { type: 'agent_end', reason: 'completed', timestamp: Date.now() };
|
|
252
|
+
}
|
|
253
|
+
else {
|
|
254
|
+
for await (const event of gen) {
|
|
255
|
+
if (event.type === 'agent_end') {
|
|
256
|
+
const terminal = shouldAbortWithoutRetry(event.error);
|
|
257
|
+
// failure first: the denied remap below must see the unwrapped cause.
|
|
258
|
+
failure = terminal ? unwrapExtensionTerminalError(event.error) : event.error;
|
|
259
|
+
reason = failure instanceof HookDeniedError && event.reason === 'error' ? 'denied' : event.reason;
|
|
260
|
+
success = isSuccessfulRunEnd(reason);
|
|
261
|
+
if (terminal) {
|
|
262
|
+
yield { ...event, error: failure };
|
|
263
|
+
break;
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
if (event.type === 'step_end')
|
|
267
|
+
iterations += 1;
|
|
268
|
+
yield event;
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
catch (error) {
|
|
273
|
+
failure = unwrapExtensionTerminalError(error);
|
|
274
|
+
reason = failure instanceof HookDeniedError ? 'denied' : 'error';
|
|
275
|
+
success = isSuccessfulRunEnd(reason);
|
|
276
|
+
yield { type: 'agent_end', reason: 'error', timestamp: Date.now(), error: failure };
|
|
277
|
+
}
|
|
278
|
+
finally {
|
|
279
|
+
const messages = context.messages;
|
|
280
|
+
await port.observe('loop_end', {
|
|
281
|
+
...base,
|
|
282
|
+
runId,
|
|
283
|
+
messages,
|
|
284
|
+
durationMs: Date.now() - startedAt,
|
|
285
|
+
reason,
|
|
286
|
+
success,
|
|
287
|
+
...(failure === undefined ? {} : { error: failure instanceof Error ? failure.message : String(failure) }),
|
|
288
|
+
iterations,
|
|
289
|
+
response: getTextContent([...messages].reverse().find((message) => message.role === 'assistant' && !message.toolCalls?.length)?.content ?? ''),
|
|
290
|
+
});
|
|
291
|
+
await observeRunEnd(port, base, messages, startedAt, reason, success, failure instanceof Error ? failure.message : typeof failure === 'string' ? failure : undefined);
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
/**
|
|
295
|
+
* Single success formula for loop_end and agent_end observations: clean terminal
|
|
296
|
+
* ends (completed / should_stop) succeed; aborted / error / denied do not. The
|
|
297
|
+
* Runner treats only `error` as a failed Run and `should_stop` as an intentional
|
|
298
|
+
* stop, so a clean stop is not a failure. `reason` always carries the exact cause.
|
|
299
|
+
*/
|
|
300
|
+
function isSuccessfulRunEnd(reason) {
|
|
301
|
+
return reason === 'completed' || reason === 'should_stop';
|
|
302
|
+
}
|
|
303
|
+
async function observeRunEnd(port, base, messages, startedAt, reason, success, error) {
|
|
304
|
+
await port.observe('agent_end', {
|
|
305
|
+
...base,
|
|
306
|
+
runId: base.runId ?? 'unknown',
|
|
307
|
+
messages,
|
|
308
|
+
durationMs: Date.now() - startedAt,
|
|
309
|
+
reason,
|
|
310
|
+
success,
|
|
311
|
+
...(error === undefined ? {} : { error }),
|
|
312
|
+
});
|
|
313
|
+
}
|
|
314
|
+
/** Build the Host Run tool Vote after SecurityGuard and before raw execution. */
|
|
315
|
+
export async function voteAgentToolCall(port, ctx, originalParams, signal) {
|
|
316
|
+
if (!port || ctx.args === null || typeof ctx.args !== 'object' || Array.isArray(ctx.args))
|
|
317
|
+
return undefined;
|
|
318
|
+
const scope = getRunScope();
|
|
319
|
+
if (!scope?.runId)
|
|
320
|
+
throw new Error('before_tool_call Vote requires a Host Run identity');
|
|
321
|
+
const event = {
|
|
322
|
+
sessionId: scope.sessionId,
|
|
323
|
+
agentId: scope.agentId,
|
|
324
|
+
runId: scope.runId,
|
|
325
|
+
...(scope.principal === undefined ? {} : { principal: scope.principal }),
|
|
326
|
+
...(signal === undefined ? {} : { signal }),
|
|
327
|
+
toolName: ctx.toolCall.name,
|
|
328
|
+
call: ctx.toolCall,
|
|
329
|
+
params: ctx.args,
|
|
330
|
+
};
|
|
331
|
+
const vote = await port.voteBeforeToolCall(event, originalParams.get(ctx.toolCall) ?? event.params);
|
|
332
|
+
if (vote.decision === 'allow')
|
|
333
|
+
return undefined;
|
|
334
|
+
return {
|
|
335
|
+
block: true,
|
|
336
|
+
reason: vote.reason ?? `Plugin hook denied ${ctx.toolCall.name}`,
|
|
337
|
+
};
|
|
338
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { PluginServiceRecord } from '../plugins/contribution-registry.js';
|
|
2
|
+
import type { HookAuditRecord } from './types.js';
|
|
3
|
+
export interface PluginServiceAudit {
|
|
4
|
+
append(record: HookAuditRecord): Promise<void>;
|
|
5
|
+
}
|
|
6
|
+
/** Host-owned service lifecycle. Registration alone has no background side effect. */
|
|
7
|
+
export declare class PluginServiceSupervisor {
|
|
8
|
+
private readonly onFailure;
|
|
9
|
+
private readonly audit?;
|
|
10
|
+
private started;
|
|
11
|
+
private starting;
|
|
12
|
+
private stopping;
|
|
13
|
+
constructor(onFailure: (service: PluginServiceRecord, error: unknown) => void, audit?: PluginServiceAudit | undefined);
|
|
14
|
+
/** Start in registration order; required failures roll back previously started services. */
|
|
15
|
+
start(services: readonly PluginServiceRecord[]): Promise<void>;
|
|
16
|
+
/** Stop only actually-started services, in reverse order; report all failures. */
|
|
17
|
+
stop(services: readonly PluginServiceRecord[]): Promise<void>;
|
|
18
|
+
/** Best-effort cleanup for a service that failed mid-start; never masks the start failure. */
|
|
19
|
+
private stopOne;
|
|
20
|
+
private key;
|
|
21
|
+
private message;
|
|
22
|
+
private record;
|
|
23
|
+
private invoke;
|
|
24
|
+
}
|