Typing tool call execute parameters.
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 52/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- api, developer-experience
Research direction
Start by locating AgentConfig.tools, AgentTool, and the public AgentTool re-export in the runtime package, then inspect the generated declaration noted at entity-stream-db-…d.ts:847. Compare the current typing behavior with the reported TypeBox example and add focused type-check coverage; done means the selected public API infers tool parameters without per-tool casts and preserves the intended generic declarations.
Written by the indexing model from the issue text.
Description
I have a tool definition in my example code that requires params: unknown and then casting to the real type:
import { Type, type Static } from '@sinclair/typebox'
const taskParameters = Type.Object({
task: Type.String({ description: `The task for the assistant.` }),
})
type TaskParams = Static<typeof taskParameters>
function createSpawnAssistantTool(ctx: HandlerContext) {
return {
name: `spawn_assistant`,
label: `Spawn Assistant`,
description: `Spawn an assistant sub-agent to perform a task.`,
parameters: taskParameters,
execute: async (_toolCallId: string, params: unknown) => {
const { task } = params as TaskParams
...
},
...
}
}
My initial reaction reading the code was "why can't the type of params be inferred from the parameters: taskParameters". I asked Claude and this was his verdict:
P1 — the tools array fixes the schema generic at its default. AgentConfig.tools is typed Array<AgentTool$1>
(entity-stream-db-…d.ts:847), and AgentTool's execute is (id, params: Static<TParameters>, …). With TParameters left at its
default TSchema, Static<TSchema> is unknown. So every execute slot demands params: unknown, and strictFunctionTypes checks
function params contravariantly — only a supertype of unknown (i.e. unknown or any) is accepted. TaskParams is a subtype, so it's
rejected. That's your error verbatim.
P2 — the public AgentTool export isn't even generic. The rolled-up .d.ts has type AgentTool$1 = AgentTool (line 841) and
re-exports AgentTool$1 as AgentTool. That alias collapses the type params to their defaults, so importing AgentTool from
@electric-ax/agents-runtime and writing AgentTool<typeof taskParameters> fails with "Type 'AgentTool$1' is not generic." (I hit
this directly.) It's almost certainly a dts-bundler artifact (the $1 rename), not intentional — a consumer can't parameterize the
tool type at all through the public name.
Runtime-side fixes
Fix A — one token, unblocks typed execute with zero call-site changes. Widen the array element to any:
interface AgentConfig {
tools: Array<AgentTool<any>> // was Array<AgentTool>
}
Static<any> is any, and any params are bivariant, so your original execute: async (_id, params: TaskParams) => … slots in with no
cast. Verified. This is also exactly what pi-agent-core already does for Agent.tools and AgentContext.tools (both
AgentTool<any>[]), so it's consistency, not a hack. Trade-off: any won't flag a wrong param shape — but that's no worse than the
cast you have now.
Fix B — best DX + actual soundness: ship a defineTool helper. TypeScript won't infer a type parameter across the fields of a bare
object literal, so the only way to get parameters → execute(params) inference is a wrapper call:
export function defineTool<P extends TSchema, D = unknown>(def: AgentTool<P, D>): AgentTool<P, D> {
return def
}
Then params is inferred from parameters — no annotation, no cast. Consuming the result still needs Fix A (or making the config
generic over a tuple, <const T extends readonly AgentTool<any>[]>). This is the Vercel AI SDK tool() pattern. Verified (params
inferred to { task: string }, proven narrowed not any).
Fix P2 regardless: re-export the generic properly, e.g. export type { AgentTool } from '@mariozechner/pi-agent-core', so the name
keeps its parameters for downstream code. Fix A alone resolves your error without this; P2 only bites consumers who want to name
AgentTool<Schema> themselves.
Without touching the runtime
Write your own structural helper — it doesn't reference the runtime's (non-generic) AgentTool, so P2 doesn't block it, and the
single cast is hidden in one place instead of one per tool:
import type { AgentTool } from '@electric-ax/agents-runtime'
import { type Static, type TSchema } from '@sinclair/typebox'
function tool<P extends TSchema>(def: {
name: string
label: string
description: string
parameters: P
execute: (id: string, params: Static<P>, signal?: AbortSignal) => Promise<{
content: Array<{ type: `text`; text: string }>
details?: unknown
terminate?: boolean
}>
}): AgentTool {
return def as unknown as AgentTool
}
const spawnAssistant = tool({
parameters: taskParameters,
execute: async (_id, params) => { // params: { task: string }, inferred
const { task } = params
...
},
// name/label/description...
})
Verified against the real runtime types — it slots straight into AgentConfig['tools']. The downside is you hand-maintain that
structural shape to match the runtime's AgentToolResult.
Bottom line
- Smallest real library fix for the error you hit: Array<AgentTool> → Array<AgentTool<any>> in AgentConfig.
- Proper library fix: that plus a generic defineTool helper plus fixing the non-generic re-export (P2).
- For this example specifically, the inline params as TaskParams you've already got is the clearest thing for a reader — the helper only pays off across many tools. Worth filing P1/P2 against the runtime though, since P2 in particular looks like an unintended packaging regression.
Does this make sense? Should we:
- update
Array<AgentTool>toArray<AgentTool<any>>in AgentConfig? - define a generic
defineToolhelper - fix the non-generic re-export
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 399
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryOpen
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valuePossibly taken @Tyagiquamar claimed this 19 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Possibly taken @mohanedmoh claimed this 37 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4826 · 1 comment ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakePossibly taken @adityavkk claimed this 133 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
electric-sql/electric#4687 ·
-
Listen IP addressOpenfeature request triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
electric-sql/electric#4150 · 1 comment ·
All issues in electric-sql/electric
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
"code source" and "numerique.gouv" links: "new window" mention duplicated in the accessible nameOpenaccessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
numerique-gouv/lasuite-landingpage#315 ·
Maintainers usually reply within 1 day
-
needs:triage
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
HyeokjaeChoi/vaultme#585 ·
Maintainers usually reply within 1 day
-
enhancement priority/P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
beettlle/pi-smart-router#200 ·