@senpi-ai/runtime 3.0.178 → 3.0.188

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/dist/actions/close-position/close-position.action.d.ts.map +1 -1
  2. package/dist/actions/close-position/close-position.action.js +6 -1
  3. package/dist/actions/close-position/close-position.action.js.map +1 -1
  4. package/dist/actions/llm-decision/openclaw-llm-decision.d.ts +8 -0
  5. package/dist/actions/llm-decision/openclaw-llm-decision.d.ts.map +1 -1
  6. package/dist/actions/llm-decision/openclaw-llm-decision.js +56 -1
  7. package/dist/actions/llm-decision/openclaw-llm-decision.js.map +1 -1
  8. package/dist/actions/position-tracker/position-tracker.action.d.ts.map +1 -1
  9. package/dist/actions/position-tracker/position-tracker.action.js +1 -0
  10. package/dist/actions/position-tracker/position-tracker.action.js.map +1 -1
  11. package/dist/approvals/approval-store.d.ts +37 -7
  12. package/dist/approvals/approval-store.d.ts.map +1 -1
  13. package/dist/approvals/approval-store.js +127 -23
  14. package/dist/approvals/approval-store.js.map +1 -1
  15. package/dist/approvals/telemetry.d.ts +28 -3
  16. package/dist/approvals/telemetry.d.ts.map +1 -1
  17. package/dist/approvals/telemetry.js +8 -4
  18. package/dist/approvals/telemetry.js.map +1 -1
  19. package/dist/approvals/tool-approval-gate.d.ts +85 -0
  20. package/dist/approvals/tool-approval-gate.d.ts.map +1 -1
  21. package/dist/approvals/tool-approval-gate.js +197 -15
  22. package/dist/approvals/tool-approval-gate.js.map +1 -1
  23. package/dist/approvals/turn-context.d.ts +296 -0
  24. package/dist/approvals/turn-context.d.ts.map +1 -0
  25. package/dist/approvals/turn-context.js +594 -0
  26. package/dist/approvals/turn-context.js.map +1 -0
  27. package/dist/cli/guide-commands.d.ts.map +1 -1
  28. package/dist/cli/guide-commands.js +18 -3
  29. package/dist/cli/guide-commands.js.map +1 -1
  30. package/dist/cli/senpi-commands.d.ts.map +1 -1
  31. package/dist/cli/senpi-commands.js +80 -5
  32. package/dist/cli/senpi-commands.js.map +1 -1
  33. package/dist/deploy/job.d.ts +32 -0
  34. package/dist/deploy/job.d.ts.map +1 -1
  35. package/dist/deploy/job.js +72 -7
  36. package/dist/deploy/job.js.map +1 -1
  37. package/dist/deploy/register.d.ts +12 -0
  38. package/dist/deploy/register.d.ts.map +1 -1
  39. package/dist/deploy/register.js +85 -2
  40. package/dist/deploy/register.js.map +1 -1
  41. package/dist/dsl/events/build-closed-event.d.ts +11 -0
  42. package/dist/dsl/events/build-closed-event.d.ts.map +1 -1
  43. package/dist/dsl/events/build-closed-event.js +13 -0
  44. package/dist/dsl/events/build-closed-event.js.map +1 -1
  45. package/dist/dsl/events/handlers.d.ts.map +1 -1
  46. package/dist/dsl/events/handlers.js +9 -5
  47. package/dist/dsl/events/handlers.js.map +1 -1
  48. package/dist/dsl/monitor/dsl-failure-events.d.ts +38 -2
  49. package/dist/dsl/monitor/dsl-failure-events.d.ts.map +1 -1
  50. package/dist/dsl/monitor/dsl-failure-events.js +67 -4
  51. package/dist/dsl/monitor/dsl-failure-events.js.map +1 -1
  52. package/dist/dsl/monitor/process-one-position.d.ts.map +1 -1
  53. package/dist/dsl/monitor/process-one-position.js +37 -9
  54. package/dist/dsl/monitor/process-one-position.js.map +1 -1
  55. package/dist/host/openclaw-host.d.ts +138 -0
  56. package/dist/host/openclaw-host.d.ts.map +1 -0
  57. package/dist/host/openclaw-host.js +177 -0
  58. package/dist/host/openclaw-host.js.map +1 -0
  59. package/dist/host/plugin-logger.d.ts +99 -0
  60. package/dist/host/plugin-logger.d.ts.map +1 -0
  61. package/dist/host/plugin-logger.js +142 -0
  62. package/dist/host/plugin-logger.js.map +1 -0
  63. package/dist/index.d.ts +57 -7
  64. package/dist/index.d.ts.map +1 -1
  65. package/dist/index.js +719 -162
  66. package/dist/index.js.map +1 -1
  67. package/dist/prompt/session-context-seed-hook.d.ts +7 -0
  68. package/dist/prompt/session-context-seed-hook.d.ts.map +1 -1
  69. package/dist/prompt/session-context-seed-hook.js +1 -1
  70. package/dist/prompt/session-context-seed-hook.js.map +1 -1
  71. package/dist/prompt/skill-router-hook.d.ts +24 -0
  72. package/dist/prompt/skill-router-hook.d.ts.map +1 -0
  73. package/dist/prompt/skill-router-hook.js +381 -0
  74. package/dist/prompt/skill-router-hook.js.map +1 -0
  75. package/dist/runtime/auto-update/coordinator.d.ts +220 -0
  76. package/dist/runtime/auto-update/coordinator.d.ts.map +1 -1
  77. package/dist/runtime/auto-update/coordinator.js +715 -22
  78. package/dist/runtime/auto-update/coordinator.js.map +1 -1
  79. package/dist/runtime/auto-update/gateway-restart.d.ts +60 -1
  80. package/dist/runtime/auto-update/gateway-restart.d.ts.map +1 -1
  81. package/dist/runtime/auto-update/gateway-restart.js +95 -21
  82. package/dist/runtime/auto-update/gateway-restart.js.map +1 -1
  83. package/dist/runtime/auto-update/idle-gate.d.ts +175 -0
  84. package/dist/runtime/auto-update/idle-gate.d.ts.map +1 -0
  85. package/dist/runtime/auto-update/idle-gate.js +229 -0
  86. package/dist/runtime/auto-update/idle-gate.js.map +1 -0
  87. package/dist/runtime/auto-update/install-results.d.ts +130 -0
  88. package/dist/runtime/auto-update/install-results.d.ts.map +1 -0
  89. package/dist/runtime/auto-update/install-results.js +264 -0
  90. package/dist/runtime/auto-update/install-results.js.map +1 -0
  91. package/dist/runtime/auto-update/money-call-tracker.d.ts +36 -0
  92. package/dist/runtime/auto-update/money-call-tracker.d.ts.map +1 -0
  93. package/dist/runtime/auto-update/money-call-tracker.js +129 -0
  94. package/dist/runtime/auto-update/money-call-tracker.js.map +1 -0
  95. package/dist/runtime/auto-update/register-idle-gate.d.ts +70 -0
  96. package/dist/runtime/auto-update/register-idle-gate.d.ts.map +1 -0
  97. package/dist/runtime/auto-update/register-idle-gate.js +127 -0
  98. package/dist/runtime/auto-update/register-idle-gate.js.map +1 -0
  99. package/dist/runtime/auto-update/run-update-command.d.ts +13 -0
  100. package/dist/runtime/auto-update/run-update-command.d.ts.map +1 -1
  101. package/dist/runtime/auto-update/run-update-command.js +18 -0
  102. package/dist/runtime/auto-update/run-update-command.js.map +1 -1
  103. package/dist/runtime/auto-update/state-store.d.ts +14 -1
  104. package/dist/runtime/auto-update/state-store.d.ts.map +1 -1
  105. package/dist/runtime/auto-update/state-store.js +37 -3
  106. package/dist/runtime/auto-update/state-store.js.map +1 -1
  107. package/dist/runtime/auto-update/types.d.ts +52 -0
  108. package/dist/runtime/auto-update/types.d.ts.map +1 -1
  109. package/dist/runtime/auto-update/types.js.map +1 -1
  110. package/dist/runtime/auto-update/update-marker.d.ts +95 -0
  111. package/dist/runtime/auto-update/update-marker.d.ts.map +1 -0
  112. package/dist/runtime/auto-update/update-marker.js +185 -0
  113. package/dist/runtime/auto-update/update-marker.js.map +1 -0
  114. package/dist/runtime/auto-update/update-schedule.d.ts +67 -0
  115. package/dist/runtime/auto-update/update-schedule.d.ts.map +1 -0
  116. package/dist/runtime/auto-update/update-schedule.js +91 -0
  117. package/dist/runtime/auto-update/update-schedule.js.map +1 -0
  118. package/dist/runtime/decision-errors.d.ts +7 -0
  119. package/dist/runtime/decision-errors.d.ts.map +1 -1
  120. package/dist/runtime/decision-errors.js +15 -0
  121. package/dist/runtime/decision-errors.js.map +1 -1
  122. package/dist/runtime/process-state.d.ts +168 -0
  123. package/dist/runtime/process-state.d.ts.map +1 -0
  124. package/dist/runtime/process-state.js +81 -0
  125. package/dist/runtime/process-state.js.map +1 -0
  126. package/dist/runtime/reconcile-state.d.ts.map +1 -1
  127. package/dist/runtime/reconcile-state.js +21 -4
  128. package/dist/runtime/reconcile-state.js.map +1 -1
  129. package/dist/runtime/strategy-registry.d.ts +16 -0
  130. package/dist/runtime/strategy-registry.d.ts.map +1 -1
  131. package/dist/runtime/strategy-registry.js +7 -3
  132. package/dist/runtime/strategy-registry.js.map +1 -1
  133. package/dist/runtime/update-apply-deps.d.ts +5 -3
  134. package/dist/runtime/update-apply-deps.d.ts.map +1 -1
  135. package/dist/runtime/update-apply-deps.js +15 -3
  136. package/dist/runtime/update-apply-deps.js.map +1 -1
  137. package/dist/senpi/client.d.ts +29 -0
  138. package/dist/senpi/client.d.ts.map +1 -1
  139. package/dist/senpi/client.js +71 -2
  140. package/dist/senpi/client.js.map +1 -1
  141. package/dist/skill-router/catalog.d.ts +30 -0
  142. package/dist/skill-router/catalog.d.ts.map +1 -0
  143. package/dist/skill-router/catalog.js +131 -0
  144. package/dist/skill-router/catalog.js.map +1 -0
  145. package/dist/skill-router/classify-client.d.ts +80 -0
  146. package/dist/skill-router/classify-client.d.ts.map +1 -0
  147. package/dist/skill-router/classify-client.js +283 -0
  148. package/dist/skill-router/classify-client.js.map +1 -0
  149. package/dist/skill-router/prompt.d.ts +36 -0
  150. package/dist/skill-router/prompt.d.ts.map +1 -0
  151. package/dist/skill-router/prompt.js +318 -0
  152. package/dist/skill-router/prompt.js.map +1 -0
  153. package/dist/skill-router/resolve.d.ts +41 -0
  154. package/dist/skill-router/resolve.d.ts.map +1 -0
  155. package/dist/skill-router/resolve.js +43 -0
  156. package/dist/skill-router/resolve.js.map +1 -0
  157. package/dist/skills-manager/version-manager.d.ts +14 -0
  158. package/dist/skills-manager/version-manager.d.ts.map +1 -1
  159. package/dist/skills-manager/version-manager.js +31 -3
  160. package/dist/skills-manager/version-manager.js.map +1 -1
  161. package/dist/strategy/strategy-state.d.ts +11 -3
  162. package/dist/strategy/strategy-state.d.ts.map +1 -1
  163. package/dist/strategy/strategy-state.js +18 -8
  164. package/dist/strategy/strategy-state.js.map +1 -1
  165. package/dist/telemetry/event-builders.d.ts +4 -2
  166. package/dist/telemetry/event-builders.d.ts.map +1 -1
  167. package/dist/telemetry/event-builders.js +4 -2
  168. package/dist/telemetry/event-builders.js.map +1 -1
  169. package/dist/telemetry/metrics.d.ts +15 -1
  170. package/dist/telemetry/metrics.d.ts.map +1 -1
  171. package/dist/telemetry/metrics.js +25 -1
  172. package/dist/telemetry/metrics.js.map +1 -1
  173. package/dist/telemetry/otel-sdk.d.ts +12 -0
  174. package/dist/telemetry/otel-sdk.d.ts.map +1 -1
  175. package/dist/telemetry/otel-sdk.js +47 -1
  176. package/dist/telemetry/otel-sdk.js.map +1 -1
  177. package/dist/telemetry/spans/span-hooks.d.ts +18 -1
  178. package/dist/telemetry/spans/span-hooks.d.ts.map +1 -1
  179. package/dist/telemetry/spans/span-hooks.js +315 -96
  180. package/dist/telemetry/spans/span-hooks.js.map +1 -1
  181. package/dist/telemetry/tool-plane.d.ts +2 -0
  182. package/dist/telemetry/tool-plane.d.ts.map +1 -1
  183. package/dist/telemetry/tool-plane.js +1 -0
  184. package/dist/telemetry/tool-plane.js.map +1 -1
  185. package/dist/test-setup.js +7 -1
  186. package/dist/test-setup.js.map +1 -1
  187. package/dist/tool-surface/crib-cache.d.ts +21 -0
  188. package/dist/tool-surface/crib-cache.d.ts.map +1 -0
  189. package/dist/tool-surface/crib-cache.js +54 -0
  190. package/dist/tool-surface/crib-cache.js.map +1 -0
  191. package/dist/tool-surface/crib-hook.d.ts +78 -0
  192. package/dist/tool-surface/crib-hook.d.ts.map +1 -0
  193. package/dist/tool-surface/crib-hook.js +225 -0
  194. package/dist/tool-surface/crib-hook.js.map +1 -0
  195. package/dist/tool-surface/crib-sheet.d.ts +56 -0
  196. package/dist/tool-surface/crib-sheet.d.ts.map +1 -0
  197. package/dist/tool-surface/crib-sheet.js +129 -0
  198. package/dist/tool-surface/crib-sheet.js.map +1 -0
  199. package/dist/tool-surface/mcp-tool-source.d.ts +64 -0
  200. package/dist/tool-surface/mcp-tool-source.d.ts.map +1 -0
  201. package/dist/tool-surface/mcp-tool-source.js +189 -0
  202. package/dist/tool-surface/mcp-tool-source.js.map +1 -0
  203. package/dist/utils/event-catalog.d.ts +228 -6
  204. package/dist/utils/event-catalog.d.ts.map +1 -1
  205. package/dist/utils/event-catalog.js +32 -0
  206. package/dist/utils/event-catalog.js.map +1 -1
  207. package/dist/widgets/tool.d.ts +9 -0
  208. package/dist/widgets/tool.d.ts.map +1 -1
  209. package/dist/widgets/tool.js +1 -0
  210. package/dist/widgets/tool.js.map +1 -1
  211. package/openclaw.plugin.json +11 -1
  212. package/package.json +5 -2
@@ -0,0 +1,296 @@
1
+ /**
2
+ * Which kind of turn a tool call belongs to: a direct user chat, a cron run, a
3
+ * heartbeat, or another run (R6, D13, D15).
4
+ *
5
+ * The tool hooks' context carries no run trigger on any host
6
+ * (`PluginHookToolContext`, `openclaw-worktrees/v2026.10.10/src/plugins/hook-types.ts:526-548`),
7
+ * but `before_prompt_build`'s agent context does (`trigger`, same field on
8
+ * 5.7, 5.12 and 10.x), and both carry the run id. The tracker records
9
+ * `runId → {sessionKey, kind}` at prompt build and keeps it for the life of the
10
+ * run, so the approval gate can read the turn kind of the call it is gating.
11
+ * `agent_end` does not end that: 10.x fires it per attempt, not per run.
12
+ *
13
+ * On 10.x `before_prompt_build` is a conversation hook: without
14
+ * `plugins.entries.runtime.hooks.allowConversationAccess` nothing is recorded
15
+ * and every lookup reads `unknown` ({@link turnClassificationAvailable} says so
16
+ * at boot).
17
+ */
18
+ /** Low-cardinality turn kind, as stamped on approval telemetry (`senpi.turn.kind`). */
19
+ export type TurnKind = "chat" | "cron" | "heartbeat" | "other" | "unknown";
20
+ /** What the gate learns about the turn of one tool call. */
21
+ export interface TurnContext {
22
+ /** The run's session key (the tool context's, when the run is unknown). */
23
+ sessionKey?: string;
24
+ kind: TurnKind;
25
+ }
26
+ /** The read side the approval gate takes. */
27
+ export interface TurnContextReader {
28
+ lookup(params: {
29
+ runId?: unknown;
30
+ sessionKey?: unknown;
31
+ }): TurnContext;
32
+ }
33
+ /**
34
+ * Maps a bare host run trigger to a {@link TurnKind}: `user` is a chat;
35
+ * `cron` and `heartbeat` are scheduled runs; any other trigger (`event`,
36
+ * `memory`, `manual`, `overflow`) is `other`; a missing one is `unknown`. The
37
+ * tracker uses it only after the run's provenance has been checked: a
38
+ * `user` trigger alone does not make a run a chat (see {@link TurnContextTracker}).
39
+ */
40
+ export declare function turnKindOf(trigger: unknown): TurnKind;
41
+ /**
42
+ * A session the host creates for a spawned child: `agent:<id>:subagent:<uuid>`
43
+ * (10.10 `src/agents/spawn-plan.ts:64-65`, `:subagent:incognito-…`
44
+ * at `subagent-spawn-child-plan.ts:96`; 5.12/5.7 `subagent-spawn.ts:829/821`)
45
+ * or an ACP child `agent:<id>:acp:<uuid>`.
46
+ */
47
+ export declare function isChildSession(sessionKey: string | undefined): boolean;
48
+ /**
49
+ * How long a `sessions_send` / `sessions_spawn` call stays matchable to the
50
+ * run it starts (the send's target run, the spawned child). That run normally
51
+ * starts within seconds; a target busy with another run queues the message,
52
+ * so the window is generous. Past it, the origin run is unidentified and the
53
+ * started run is not chat.
54
+ */
55
+ export declare const SESSIONS_SEND_MATCH_WINDOW_MS: number;
56
+ /**
57
+ * Recent runs by id, bounded, plus what each session's last run was and which
58
+ * kind each spawned child session inherited.
59
+ *
60
+ * Classification (D15: only a run positively identified as a direct chat turn
61
+ * is `chat`; anything not resolvable is not chat), from the
62
+ * `before_prompt_build` context (10.10 `attempt-prompt-build.ts:150-159`:
63
+ * `runId`, `jobId`, `sessionKey`, `trigger`, `inputProvenance`; 5.7/5.12 carry
64
+ * `runId`, `sessionKey`, `trigger` only, `attempt.ts:2563-2574` / `:2948-2959`):
65
+ *
66
+ * 1. `trigger` `cron` / `heartbeat` → that kind.
67
+ * 2. A `sessions_send` target (`inputProvenance` `inter_session` with
68
+ * `sourceTool: "sessions_send"`, 10.10 `sessions-send-tool.ts:470-476`) →
69
+ * the kind of the run that SENT it. The provenance names only the source
70
+ * session, not the sending run, so the sending run is identified from the
71
+ * `sessions_send` call itself: {@link onToolCall} records the calling run's
72
+ * kind with its source session and its named target at `before_tool_call`.
73
+ * A target run consumes the oldest pending send from `sourceSessionKey`
74
+ * whose target is the run's own session, inside
75
+ * {@link SESSIONS_SEND_MATCH_WINDOW_MS}. {@link onToolResult} drops a send
76
+ * whose result says no run was started for it (an error, a `steered` or
77
+ * unstarted `queued` delivery) or that it already finished, and gives a
78
+ * send addressed by `label` / `agentId` its resolved target. Until that
79
+ * result arrives (in wait mode the target run starts while the call is
80
+ * still open), such a send matches a run in any session of the named
81
+ * agent (any agent for a bare label), and only when no send with an exact
82
+ * target matches; candidates of different kinds still read `other`.
83
+ * The reply-back run is recognised too (10.10 `sessions-send-tool.a2a.ts:100,201-208`).
84
+ * It runs in the REQUESTER session, with the target as `sourceSessionKey`
85
+ * and `sourceTool: "sessions_send"`. It takes the kind of the send whose
86
+ * target run started (an open exchange, requester → target). It never
87
+ * takes the requester session's own pending sends.
88
+ * No match, an unclassified sender, or several candidates of different
89
+ * kinds (two runs sending at once; a forward send and a reply-back that
90
+ * could both explain the run) leave the origin unidentified → `other`. A
91
+ * later run on the source session (a chat starting after a heartbeat sent)
92
+ * never changes the answer.
93
+ * Other `inter_session` sources (subagent announce, exec-approval
94
+ * follow-up, `bash-tools.exec-approval-followup.ts:338-342`) → the kind of
95
+ * the `sourceSessionKey` session's last run; `other` when that is unknown.
96
+ * 3. A child session (`subagent:` / `acp:`) → the kind of the run that
97
+ * spawned it. `subagent_spawned` names only the requester session (10.10
98
+ * `subagent-spawn-lifecycle.ts:67-71`: ctx `requesterSessionKey`,
99
+ * `childSessionKey`), so the spawning run is identified the same way as a
100
+ * `sessions_send` sender: {@link onToolCall} records the run's kind at its
101
+ * `sessions_spawn` call (`sessions-spawn-tool.ts:355`), and
102
+ * `subagent_spawned` consumes the oldest pending spawn from the requester
103
+ * session, with the same window and ambiguity rules. Unmatched → `other`.
104
+ * 10.10 hard-codes `trigger: "user"` for these runs
105
+ * (`attempt-execution.ts:362`), and fires `subagent_spawned` after the
106
+ * gateway accepted the child (`subagent-spawn.ts:667`), so a child
107
+ * classified first reads `other` until its origin arrives.
108
+ * 4. `trigger` `event` or `inputProvenance.kind === "internal_system"` (a
109
+ * continuation after background work, `session-event-context.ts:86`;
110
+ * neither carries the originating run) → `other`.
111
+ * 5. A `jobId`, or a `cron:` session, with a non-cron trigger → `other`.
112
+ * 6. `trigger` `user` with no provenance or `external_user` provenance (a
113
+ * webchat `chat.send` turn: `reply-turn-kind.ts:18-24`,
114
+ * `chat-send-user-turn.ts:206`) → `chat`.
115
+ * 7. Any other trigger → `other`; none → `unknown`.
116
+ *
117
+ * Known limit: a gateway `agent` call with no provenance on a main session
118
+ * key (an operator `openclaw agent` run) reads as chat; nothing in the
119
+ * context tells it apart from a webchat turn.
120
+ */
121
+ export declare class TurnContextTracker implements TurnContextReader {
122
+ private readonly maxRuns;
123
+ private readonly now;
124
+ private readonly runs;
125
+ private readonly latestBySession;
126
+ /** The kind of each session's last classified run; kept past `agent_end`, for inheritance. */
127
+ private readonly lastKindBySession;
128
+ /** Child session key → the kind it inherited from its requester. */
129
+ private readonly childOrigins;
130
+ /** `sessions_send` / `sessions_spawn` calls waiting for the run they start, oldest first. */
131
+ private origins;
132
+ /** Sends whose target run started, waiting for their reply-back run, oldest first. */
133
+ private exchanges;
134
+ /** Runs recorded since this tracker started; see {@link runsRecorded}. */
135
+ private recorded;
136
+ /**
137
+ * @param maxRuns - Runs kept at once, ended ones included (see {@link onRunEnd}); the oldest
138
+ * is dropped past it. A later call of a dropped run reads `unknown`; a retry classifies anew.
139
+ * @param now - Clock for the `sessions_send` match window.
140
+ */
141
+ constructor(maxRuns?: number, now?: () => number);
142
+ /**
143
+ * Records a `sessions_send` or `sessions_spawn` call from a `before_tool_call`
144
+ * event/context: the calling run's kind (`unknown` when that run was never
145
+ * classified), its session keys (the call's and the run's own), and for a
146
+ * send the target it names (`params.sessionKey`; a `label` or `agentId`
147
+ * marks it unresolved until the result names it). Any other tool, or
148
+ * malformed input, is ignored.
149
+ */
150
+ onToolCall(event: unknown, ctx: unknown): void;
151
+ /**
152
+ * Reads a `sessions_send` / `sessions_spawn` result from an `after_tool_call`
153
+ * event: drops the pending call when the result says it started no run to
154
+ * match (a failed spawn; for a send, {@link sendStartedNoRunToMatch}), and
155
+ * gives a send its resolved target session. Unknown calls, other tools and
156
+ * unreadable results are ignored.
157
+ */
158
+ onToolResult(event: unknown, ctx: unknown): void;
159
+ /**
160
+ * Records a run from a `before_prompt_build` agent context. Malformed input
161
+ * is ignored. A run is classified once: 10.x fires the hook again for each
162
+ * retry attempt of the same run (after compaction, a model or auth
163
+ * failover), after an `agent_end` for the attempt before it, and by then the
164
+ * origin call or exchange that classified it is consumed, so re-classifying
165
+ * would turn a chat-originated run into `other`. The first answer stands,
166
+ * whatever it was; a scheduled run stays scheduled. Host run ids are fresh per
167
+ * run, so a retained id only ever comes back as a retry (10.10 cron
168
+ * `isolated-agent/run.ts:142`, follow-ups `followup-turn-admission.ts:305`,
169
+ * replies `agent-runner-execution.ts:703`). A caller-supplied id (a `chat.send`
170
+ * or announce idempotency key) names one message; reused, it keeps its first answer.
171
+ */
172
+ onPromptBuild(ctx: unknown): void;
173
+ /**
174
+ * Records a spawned child's origin from a `subagent_spawned` context/event:
175
+ * the kind of the run whose `sessions_spawn` call is pending in the requester
176
+ * session (consumed), or `other` when none matches. Malformed input is ignored.
177
+ */
178
+ onSubagentSpawned(ctx: unknown, event?: unknown): void;
179
+ /** How many runs `before_prompt_build` has recorded since this tracker started. */
180
+ get runsRecorded(): number;
181
+ /**
182
+ * An attempt ended (`agent_end`). The run's entry stays: 10.10 fires this per
183
+ * attempt with no retry guard (`run/attempt-finalize.ts:305-308`), a retry keeps
184
+ * the run id, and the hook is fire-and-forget, so it can even land after the
185
+ * retry's prompt build. `maxRuns` bounds the entries. Only the run's claim on
186
+ * its session goes, so a call with no run id never reads a run that ended
187
+ * (`unknown`, which the gate refuses).
188
+ */
189
+ onRunEnd(runId: unknown): void;
190
+ /**
191
+ * The turn of a tool call: by run id, else by the session's latest recorded
192
+ * run, else `unknown` with the given session key.
193
+ */
194
+ lookup(params: {
195
+ runId?: unknown;
196
+ sessionKey?: unknown;
197
+ }): TurnContext;
198
+ private classify;
199
+ /** Drops origin calls and exchanges older than the match window. */
200
+ private prune;
201
+ /** One kind from several candidates: theirs when all agree and it is known, else `other`. */
202
+ private static agreed;
203
+ /**
204
+ * The pending `tool` call from `source` (for a send: aimed at `target`)
205
+ * that started this run, consumed, with the kind the candidates agree on;
206
+ * `undefined` when none matches.
207
+ */
208
+ private takeOrigin;
209
+ /**
210
+ * The kind of a run whose provenance says `sessions_send` from `source`, in
211
+ * `sessionKey`: either a target run (a pending send from `source` aimed at
212
+ * this session) or a reply-back run (an open exchange from this session to
213
+ * `source`). Both possible with different kinds, or neither → `other`.
214
+ */
215
+ private sendOriginKind;
216
+ /** A session's last classified run kind, or `other` when it is unknown (not resolvable is not chat). */
217
+ private kindOfSession;
218
+ /** Drops a run for good: the eviction past `maxRuns`. */
219
+ private forget;
220
+ /** Stops `runId` being its session's latest run; a newer run in that session is left alone. */
221
+ private releaseSession;
222
+ }
223
+ /**
224
+ * Whether this host lets the runtime classify the run a gated call belongs to:
225
+ * one boot-time fact, never decided per run (D15). Both halves must hold.
226
+ *
227
+ * 1. **The host links a tool call to its run.** The gate reads the run id that
228
+ * `before_tool_call` carries. 5.12 and 5.7 add the bundle-MCP tools (every
229
+ * `senpi__` tool) unwrapped and split them with no hook context (5.12
230
+ * `pi-embedded-runner/run/attempt.ts:1228-1235,1275,1737`; 5.7
231
+ * `attempt.ts:1035,1081`), so `pi-tool-definition-adapter.ts:240-244` runs the
232
+ * hook with no ctx and the call arrives with no run id or session key
233
+ * (`pi-tools.before-tool-call.ts:525-534,594-600`). Every `senpi__` call would
234
+ * read `unknown`, so a 5.x host is never available, whatever its config.
235
+ * The first tag that links is 2026.6.1 (`splitSdkTools` passes
236
+ * `catalogToolHookContext`, which carries `runId`). Since 9.5 the bundle
237
+ * tools are also wrapped up front (`attempt-bundle-tools.ts:204` on 10.10).
238
+ * The runtime gates on the modern host (>= 2026.8.1), which includes that.
239
+ * 2. **The conversation hooks register.** The tracker is fed by
240
+ * `before_prompt_build`, a conversation hook on 10.x. A non-bundled plugin's
241
+ * registration is dropped with only a warn diagnostic unless
242
+ * `plugins.entries.<id>.hooks.allowConversationAccess` is `true` (10.10
243
+ * `registry-registrars-tools-hooks.ts:53-63,404-417`,
244
+ * `hook-policy-decisions.ts:10-16`). `allowPromptInjection: false` drops it
245
+ * too (5.12 `registry.ts:2288-2296`).
246
+ *
247
+ * @param config - The whole OpenClaw config the plugin was registered with (`api.config`).
248
+ * @returns `reason` for status surfaces. `configFix` only when a config change
249
+ * would make it available; a host-version limit has none.
250
+ */
251
+ export declare function turnClassificationAvailable(params: {
252
+ modernHost: boolean;
253
+ config: unknown;
254
+ pluginId: string;
255
+ }): {
256
+ available: boolean;
257
+ reason?: string;
258
+ configFix?: string;
259
+ };
260
+ /**
261
+ * The approval gate's host fact as status surfaces show it (`senpi.getHealthStatus` →
262
+ * `approvals`, `openclaw senpi status`). `unavailable` means every run is asked as before
263
+ * this release, scheduled runs included: a box config to fix, or (on 5.x) a host limit.
264
+ * `hostLimit` marks the 5.x case: nothing on the box can change it, so `senpi status`
265
+ * does not print it as a warning. On `available`, `unclassifiedBlocks` counts gated calls blocked
266
+ * since the gateway started because their run was not classified, against `runsRecorded`: a box
267
+ * whose hooks stopped seeing its runs refuses every chat trade while still reading `available`.
268
+ */
269
+ export type ApprovalsHostStatus = {
270
+ turnClassification: "available";
271
+ runsRecorded?: number;
272
+ unclassifiedBlocks?: number;
273
+ lastUnclassifiedBlockAt?: string;
274
+ } | {
275
+ turnClassification: "unavailable";
276
+ reason?: string;
277
+ hostLimit?: true;
278
+ };
279
+ /**
280
+ * Feeds `tracker` from `before_prompt_build` (records; returns nothing, so the
281
+ * prompt is untouched), `subagent_spawned` (a child's origin; not a
282
+ * conversation hook on any host), `before_tool_call` / `after_tool_call`
283
+ * (observe `sessions_send` and `sessions_spawn` calls and their results only,
284
+ * to identify the run that started a target or a child; return nothing, so
285
+ * they decide nothing) and `agent_end` (the run stops being its session's latest; refused
286
+ * without conversation access, where nothing is recorded anyway). Handlers never throw.
287
+ */
288
+ export declare function registerTurnContextHooks(params: {
289
+ api: {
290
+ on(hookName: string, handler: (...args: unknown[]) => unknown, opts?: {
291
+ priority?: number;
292
+ }): void;
293
+ };
294
+ tracker: TurnContextTracker;
295
+ }): void;
296
+ //# sourceMappingURL=turn-context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../../src/approvals/turn-context.ts"],"names":[],"mappings":"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"}