Skip to content

Commit d972aa9

Browse files
committed
feat(core): tool execute hooks, session instructions, synthetic endpoint
- V2 tool execute hooks: add `ctx.tool.execute.before/after` plugin API, core ToolHooks service, and registry wiring so hosted/local tool calls run registered before/after hooks; provider-executed calls are excluded. - Session synthetic endpoint: add `POST /api/session/:sessionID/synthetic` with text/description/metadata plus regenerated Promise/Effect/JS client surfaces. - SessionInstructions service: read tool discovers nearby AGENTS.md walking up to the Location root (exclusive) and injects them as durable synthetic instructions, with lazy history dedup of prior claims. - to-llm-message: stop forwarding synthetic message metadata to the model so bookkeeping annotations stay model-hidden. - schema changelog entry for synthetic metadata and the metadata leak fix.
1 parent d544ab4 commit d972aa9

25 files changed

Lines changed: 893 additions & 116 deletions

File tree

‎packages/client/src/generated-effect/client.ts‎

Lines changed: 65 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -164,23 +164,36 @@ const Endpoint4_9 = (raw: RawClient["server.session"]) => (input: Endpoint4_9Inp
164164
payload: { id: input["id"], skill: input["skill"], resume: input["resume"] },
165165
}).pipe(Effect.mapError(mapClientError))
166166

167-
type Endpoint4_10Request = Parameters<RawClient["server.session"]["session.compact"]>[0]
168-
type Endpoint4_10Input = { readonly sessionID: Endpoint4_10Request["params"]["sessionID"] }
167+
type Endpoint4_10Request = Parameters<RawClient["server.session"]["session.synthetic"]>[0]
168+
type Endpoint4_10Input = {
169+
readonly sessionID: Endpoint4_10Request["params"]["sessionID"]
170+
readonly text: Endpoint4_10Request["payload"]["text"]
171+
readonly description?: Endpoint4_10Request["payload"]["description"]
172+
readonly metadata?: Endpoint4_10Request["payload"]["metadata"]
173+
}
169174
const Endpoint4_10 = (raw: RawClient["server.session"]) => (input: Endpoint4_10Input) =>
170-
raw["session.compact"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
175+
raw["session.synthetic"]({
176+
params: { sessionID: input["sessionID"] },
177+
payload: { text: input["text"], description: input["description"], metadata: input["metadata"] },
178+
}).pipe(Effect.mapError(mapClientError))
171179

172-
type Endpoint4_11Request = Parameters<RawClient["server.session"]["session.wait"]>[0]
180+
type Endpoint4_11Request = Parameters<RawClient["server.session"]["session.compact"]>[0]
173181
type Endpoint4_11Input = { readonly sessionID: Endpoint4_11Request["params"]["sessionID"] }
174182
const Endpoint4_11 = (raw: RawClient["server.session"]) => (input: Endpoint4_11Input) =>
183+
raw["session.compact"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
184+
185+
type Endpoint4_12Request = Parameters<RawClient["server.session"]["session.wait"]>[0]
186+
type Endpoint4_12Input = { readonly sessionID: Endpoint4_12Request["params"]["sessionID"] }
187+
const Endpoint4_12 = (raw: RawClient["server.session"]) => (input: Endpoint4_12Input) =>
175188
raw["session.wait"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
176189

177-
type Endpoint4_12Request = Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
178-
type Endpoint4_12Input = {
179-
readonly sessionID: Endpoint4_12Request["params"]["sessionID"]
180-
readonly messageID: Endpoint4_12Request["payload"]["messageID"]
181-
readonly files?: Endpoint4_12Request["payload"]["files"]
190+
type Endpoint4_13Request = Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
191+
type Endpoint4_13Input = {
192+
readonly sessionID: Endpoint4_13Request["params"]["sessionID"]
193+
readonly messageID: Endpoint4_13Request["payload"]["messageID"]
194+
readonly files?: Endpoint4_13Request["payload"]["files"]
182195
}
183-
const Endpoint4_12 = (raw: RawClient["server.session"]) => (input: Endpoint4_12Input) =>
196+
const Endpoint4_13 = (raw: RawClient["server.session"]) => (input: Endpoint4_13Input) =>
184197
raw["session.revert.stage"]({
185198
params: { sessionID: input["sessionID"] },
186199
payload: { messageID: input["messageID"], files: input["files"] },
@@ -189,65 +202,65 @@ const Endpoint4_12 = (raw: RawClient["server.session"]) => (input: Endpoint4_12I
189202
Effect.map((value) => value.data),
190203
)
191204

192-
type Endpoint4_13Request = Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
193-
type Endpoint4_13Input = { readonly sessionID: Endpoint4_13Request["params"]["sessionID"] }
194-
const Endpoint4_13 = (raw: RawClient["server.session"]) => (input: Endpoint4_13Input) =>
195-
raw["session.revert.clear"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
196-
197-
type Endpoint4_14Request = Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
205+
type Endpoint4_14Request = Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
198206
type Endpoint4_14Input = { readonly sessionID: Endpoint4_14Request["params"]["sessionID"] }
199207
const Endpoint4_14 = (raw: RawClient["server.session"]) => (input: Endpoint4_14Input) =>
200-
raw["session.revert.commit"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
208+
raw["session.revert.clear"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
201209

202-
type Endpoint4_15Request = Parameters<RawClient["server.session"]["session.context"]>[0]
210+
type Endpoint4_15Request = Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
203211
type Endpoint4_15Input = { readonly sessionID: Endpoint4_15Request["params"]["sessionID"] }
204212
const Endpoint4_15 = (raw: RawClient["server.session"]) => (input: Endpoint4_15Input) =>
213+
raw["session.revert.commit"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
214+
215+
type Endpoint4_16Request = Parameters<RawClient["server.session"]["session.context"]>[0]
216+
type Endpoint4_16Input = { readonly sessionID: Endpoint4_16Request["params"]["sessionID"] }
217+
const Endpoint4_16 = (raw: RawClient["server.session"]) => (input: Endpoint4_16Input) =>
205218
raw["session.context"]({ params: { sessionID: input["sessionID"] } }).pipe(
206219
Effect.mapError(mapClientError),
207220
Effect.map((value) => value.data),
208221
)
209222

210-
type Endpoint4_16Request = Parameters<RawClient["server.session"]["session.history"]>[0]
211-
type Endpoint4_16Input = {
212-
readonly sessionID: Endpoint4_16Request["params"]["sessionID"]
213-
readonly limit?: Endpoint4_16Request["query"]["limit"]
214-
readonly after?: Endpoint4_16Request["query"]["after"]
223+
type Endpoint4_17Request = Parameters<RawClient["server.session"]["session.history"]>[0]
224+
type Endpoint4_17Input = {
225+
readonly sessionID: Endpoint4_17Request["params"]["sessionID"]
226+
readonly limit?: Endpoint4_17Request["query"]["limit"]
227+
readonly after?: Endpoint4_17Request["query"]["after"]
215228
}
216-
const Endpoint4_16 = (raw: RawClient["server.session"]) => (input: Endpoint4_16Input) =>
229+
const Endpoint4_17 = (raw: RawClient["server.session"]) => (input: Endpoint4_17Input) =>
217230
raw["session.history"]({
218231
params: { sessionID: input["sessionID"] },
219232
query: { limit: input["limit"], after: input["after"] },
220233
}).pipe(Effect.mapError(mapClientError))
221234

222-
type Endpoint4_17Request = Parameters<RawClient["server.session"]["session.events"]>[0]
223-
type Endpoint4_17Input = {
224-
readonly sessionID: Endpoint4_17Request["params"]["sessionID"]
225-
readonly after?: Endpoint4_17Request["query"]["after"]
235+
type Endpoint4_18Request = Parameters<RawClient["server.session"]["session.events"]>[0]
236+
type Endpoint4_18Input = {
237+
readonly sessionID: Endpoint4_18Request["params"]["sessionID"]
238+
readonly after?: Endpoint4_18Request["query"]["after"]
226239
}
227-
const Endpoint4_17 = (raw: RawClient["server.session"]) => (input: Endpoint4_17Input) =>
240+
const Endpoint4_18 = (raw: RawClient["server.session"]) => (input: Endpoint4_18Input) =>
228241
Stream.unwrap(
229242
raw["session.events"]({ params: { sessionID: input["sessionID"] }, query: { after: input["after"] } }).pipe(
230243
Effect.mapError(mapClientError),
231244
Effect.map((stream) => stream.pipe(Stream.mapError(mapClientError))),
232245
),
233246
)
234247

235-
type Endpoint4_18Request = Parameters<RawClient["server.session"]["session.interrupt"]>[0]
236-
type Endpoint4_18Input = { readonly sessionID: Endpoint4_18Request["params"]["sessionID"] }
237-
const Endpoint4_18 = (raw: RawClient["server.session"]) => (input: Endpoint4_18Input) =>
238-
raw["session.interrupt"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
239-
240-
type Endpoint4_19Request = Parameters<RawClient["server.session"]["session.background"]>[0]
248+
type Endpoint4_19Request = Parameters<RawClient["server.session"]["session.interrupt"]>[0]
241249
type Endpoint4_19Input = { readonly sessionID: Endpoint4_19Request["params"]["sessionID"] }
242250
const Endpoint4_19 = (raw: RawClient["server.session"]) => (input: Endpoint4_19Input) =>
251+
raw["session.interrupt"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
252+
253+
type Endpoint4_20Request = Parameters<RawClient["server.session"]["session.background"]>[0]
254+
type Endpoint4_20Input = { readonly sessionID: Endpoint4_20Request["params"]["sessionID"] }
255+
const Endpoint4_20 = (raw: RawClient["server.session"]) => (input: Endpoint4_20Input) =>
243256
raw["session.background"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
244257

245-
type Endpoint4_20Request = Parameters<RawClient["server.session"]["session.message"]>[0]
246-
type Endpoint4_20Input = {
247-
readonly sessionID: Endpoint4_20Request["params"]["sessionID"]
248-
readonly messageID: Endpoint4_20Request["params"]["messageID"]
258+
type Endpoint4_21Request = Parameters<RawClient["server.session"]["session.message"]>[0]
259+
type Endpoint4_21Input = {
260+
readonly sessionID: Endpoint4_21Request["params"]["sessionID"]
261+
readonly messageID: Endpoint4_21Request["params"]["messageID"]
249262
}
250-
const Endpoint4_20 = (raw: RawClient["server.session"]) => (input: Endpoint4_20Input) =>
263+
const Endpoint4_21 = (raw: RawClient["server.session"]) => (input: Endpoint4_21Input) =>
251264
raw["session.message"]({ params: { sessionID: input["sessionID"], messageID: input["messageID"] } }).pipe(
252265
Effect.mapError(mapClientError),
253266
Effect.map((value) => value.data),
@@ -264,17 +277,18 @@ const adaptGroup4 = (raw: RawClient["server.session"]) => ({
264277
rename: Endpoint4_7(raw),
265278
prompt: Endpoint4_8(raw),
266279
skill: Endpoint4_9(raw),
267-
compact: Endpoint4_10(raw),
268-
wait: Endpoint4_11(raw),
269-
revertStage: Endpoint4_12(raw),
270-
revertClear: Endpoint4_13(raw),
271-
revertCommit: Endpoint4_14(raw),
272-
context: Endpoint4_15(raw),
273-
history: Endpoint4_16(raw),
274-
events: Endpoint4_17(raw),
275-
interrupt: Endpoint4_18(raw),
276-
background: Endpoint4_19(raw),
277-
message: Endpoint4_20(raw),
280+
synthetic: Endpoint4_10(raw),
281+
compact: Endpoint4_11(raw),
282+
wait: Endpoint4_12(raw),
283+
revertStage: Endpoint4_13(raw),
284+
revertClear: Endpoint4_14(raw),
285+
revertCommit: Endpoint4_15(raw),
286+
context: Endpoint4_16(raw),
287+
history: Endpoint4_17(raw),
288+
events: Endpoint4_18(raw),
289+
interrupt: Endpoint4_19(raw),
290+
background: Endpoint4_20(raw),
291+
message: Endpoint4_21(raw),
278292
})
279293

280294
type Endpoint5_0Request = Parameters<RawClient["server.message"]["session.messages"]>[0]

‎packages/client/src/generated/client.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ import type {
2525
SessionPromptOutput,
2626
SessionSkillInput,
2727
SessionSkillOutput,
28+
SessionSyntheticInput,
29+
SessionSyntheticOutput,
2830
SessionCompactInput,
2931
SessionCompactOutput,
3032
SessionWaitInput,
@@ -461,6 +463,18 @@ export function make(options: ClientOptions) {
461463
},
462464
requestOptions,
463465
),
466+
synthetic: (input: SessionSyntheticInput, requestOptions?: RequestOptions) =>
467+
request<SessionSyntheticOutput>(
468+
{
469+
method: "POST",
470+
path: `/api/session/${encodeURIComponent(input.sessionID)}/synthetic`,
471+
body: { text: input["text"], description: input["description"], metadata: input["metadata"] },
472+
successStatus: 204,
473+
declaredStatuses: [404, 400, 401],
474+
empty: true,
475+
},
476+
requestOptions,
477+
),
464478
compact: (input: SessionCompactInput, requestOptions?: RequestOptions) =>
465479
request<SessionCompactOutput>(
466480
{

‎packages/client/src/generated/types.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -584,6 +584,27 @@ export type SessionSkillInput = {
584584

585585
export type SessionSkillOutput = void
586586

587+
export type SessionSyntheticInput = {
588+
readonly sessionID: { readonly sessionID: string }["sessionID"]
589+
readonly text: {
590+
readonly text: string
591+
readonly description?: string | null
592+
readonly metadata?: { readonly [x: string]: JsonValue }
593+
}["text"]
594+
readonly description?: {
595+
readonly text: string
596+
readonly description?: string | null
597+
readonly metadata?: { readonly [x: string]: JsonValue }
598+
}["description"]
599+
readonly metadata?: {
600+
readonly text: string
601+
readonly description?: string | null
602+
readonly metadata?: { readonly [x: string]: JsonValue }
603+
}["metadata"]
604+
}
605+
606+
export type SessionSyntheticOutput = void
607+
587608
export type SessionCompactInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
588609

589610
export type SessionCompactOutput = void
@@ -934,6 +955,7 @@ export type SessionHistoryOutput = {
934955
readonly messageID: string
935956
readonly text: string
936957
readonly description?: string
958+
readonly metadata?: { readonly [x: string]: JsonValue }
937959
}
938960
}
939961
| {
@@ -1428,6 +1450,7 @@ export type SessionEventsOutput =
14281450
readonly messageID: string
14291451
readonly text: string
14301452
readonly description?: string
1453+
readonly metadata?: { readonly [x: string]: unknown }
14311454
}
14321455
}
14331456
| {
@@ -3530,6 +3553,7 @@ export type EventSubscribeOutput =
35303553
readonly messageID: string
35313554
readonly text: string
35323555
readonly description?: string
3556+
readonly metadata?: { readonly [x: string]: unknown }
35333557
}
35343558
}
35353559
| {

‎packages/core/src/location-services.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ import { SkillGuidance } from "./skill/guidance"
3838
import { Snapshot } from "./snapshot"
3939
import { SystemContextBuiltIns } from "./system-context/builtins"
4040
import { SystemContextRegistry } from "./system-context/registry"
41+
import { SessionInstructions } from "./session/instructions"
4142
import { BuiltInTools } from "./tool/builtins"
4243
import { McpTool } from "./tool/mcp"
4344
import { ReadToolFileSystem } from "./tool/read-filesystem"
@@ -85,6 +86,7 @@ export const locationServices = LayerNode.group([
8586
ReadToolFileSystem.node,
8687
BuiltInTools.node,
8788
McpTool.node,
89+
SessionInstructions.node,
8890
SessionRunnerModel.node,
8991
SessionCompaction.node,
9092
SessionTitle.node,

‎packages/core/src/plugin.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import { Reference } from "./reference"
1818
import { SkillV2 } from "./skill"
1919
import { State } from "./state"
2020
import { ToolRegistry } from "./tool/registry"
21+
import { ToolHooks } from "./tool/hooks"
2122

2223
export const ID = Plugin.ID
2324
export type ID = typeof ID.Type
@@ -165,6 +166,7 @@ export const node = makeLocationNode({
165166
Reference.node,
166167
SkillV2.node,
167168
ToolRegistry.toolsNode,
169+
ToolHooks.node,
168170
PluginRuntime.node,
169171
],
170172
})

‎packages/core/src/plugin/host.ts‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import { Reference } from "../reference"
1717
import { AbsolutePath, type DeepMutable } from "../schema"
1818
import { SkillV2 } from "../skill"
1919
import { Tools } from "../tool/tools"
20+
import { ToolHooks } from "../tool/hooks"
2021
import { WorkspaceV2 } from "../workspace"
2122

2223
const mutable = <T>(value: T) => value as DeepMutable<T>
@@ -31,6 +32,7 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: PluginV2.Int
3132
const reference = yield* Reference.Service
3233
const skill = yield* SkillV2.Service
3334
const tools = yield* Tools.Service
35+
const toolHooks = yield* ToolHooks.Service
3436
const runtime = yield* PluginRuntime.Service
3537
const locationInfo = () =>
3638
new Location.Info({
@@ -247,6 +249,47 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: PluginV2.Int
247249
},
248250
tool: {
249251
register: (input) => tools.register(input),
252+
execute: {
253+
before: (callback) =>
254+
toolHooks.hook.before((event) => {
255+
const output = {
256+
tool: event.tool,
257+
sessionID: event.sessionID,
258+
agent: event.agent,
259+
assistantMessageID: event.assistantMessageID,
260+
toolCallID: event.toolCallID,
261+
input: event.input,
262+
}
263+
const result = callback(output)
264+
return Effect.suspend(() => (Effect.isEffect(result) ? result : Effect.void)).pipe(
265+
Effect.tap(() => Effect.sync(() => (event.input = output.input))),
266+
)
267+
}),
268+
after: (callback) =>
269+
toolHooks.hook.after((event) => {
270+
const output = {
271+
tool: event.tool,
272+
sessionID: event.sessionID,
273+
agent: event.agent,
274+
assistantMessageID: event.assistantMessageID,
275+
toolCallID: event.toolCallID,
276+
input: event.input,
277+
result: event.result,
278+
output: event.output,
279+
outputPaths: event.outputPaths,
280+
}
281+
const result = callback(output)
282+
return Effect.suspend(() => (Effect.isEffect(result) ? result : Effect.void)).pipe(
283+
Effect.tap(() =>
284+
Effect.sync(() => {
285+
event.result = output.result
286+
event.output = output.output
287+
event.outputPaths = output.outputPaths
288+
}),
289+
),
290+
)
291+
}),
292+
},
250293
},
251294
session: {
252295
create: (input) =>

‎packages/core/src/session.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,7 @@ export interface Interface {
199199
sessionID: SessionSchema.ID
200200
text: string
201201
description?: string
202+
metadata?: Record<string, unknown>
202203
}) => Effect.Effect<void, NotFoundError>
203204
readonly revert: {
204205
readonly stage: (input: {
@@ -547,6 +548,7 @@ const layer = Layer.effect(
547548
timestamp: yield* DateTime.now,
548549
text: input.text,
549550
description: input.description,
551+
metadata: input.metadata,
550552
})
551553
yield* execution.resume(input.sessionID).pipe(Effect.ignore, Effect.forkIn(scope, { startImmediately: true }), Effect.asVoid)
552554
}),

0 commit comments

Comments
 (0)