@ottimis/jack-provider-sdk 0.1.0 → 0.2.0
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/backend.d.ts +38 -12
- package/dist/backend.d.ts.map +1 -1
- package/dist/provider.d.ts +135 -55
- package/dist/provider.d.ts.map +1 -1
- package/package.json +5 -3
- package/src/backend.ts +28 -12
- package/src/provider.ts +145 -44
package/dist/backend.d.ts
CHANGED
|
@@ -48,10 +48,28 @@ export type AgentSystemPrompt = string | {
|
|
|
48
48
|
append?: string;
|
|
49
49
|
};
|
|
50
50
|
/**
|
|
51
|
-
* MCP server configuration
|
|
52
|
-
*
|
|
51
|
+
* MCP server configuration handed to the provider via
|
|
52
|
+
* {@link AgentQueryOptions.mcpServers}. Mirrors the official MCP wire
|
|
53
|
+
* format (the same shape Anthropic, OpenAI, and Google all consume).
|
|
54
|
+
*
|
|
55
|
+
* Replaces the legacy opaque `AgentMcpServerConfig = unknown` so the
|
|
56
|
+
* type system enforces the contract end-to-end and the host can inspect
|
|
57
|
+
* the bag for telemetry / preview without double-translating.
|
|
53
58
|
*/
|
|
54
|
-
export type
|
|
59
|
+
export type McpServerSpec = {
|
|
60
|
+
type: 'stdio';
|
|
61
|
+
command: string;
|
|
62
|
+
args?: string[];
|
|
63
|
+
env?: Record<string, string>;
|
|
64
|
+
} | {
|
|
65
|
+
type: 'http';
|
|
66
|
+
url: string;
|
|
67
|
+
headers?: Record<string, string>;
|
|
68
|
+
} | {
|
|
69
|
+
type: 'sse';
|
|
70
|
+
url: string;
|
|
71
|
+
headers?: Record<string, string>;
|
|
72
|
+
};
|
|
55
73
|
/** Reasoning-effort knob. Provider-validated; not all providers honor every value. */
|
|
56
74
|
export type AgentEffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
57
75
|
/**
|
|
@@ -132,7 +150,7 @@ export type AgentQueryOptions = {
|
|
|
132
150
|
* knowledge sources).
|
|
133
151
|
*/
|
|
134
152
|
additionalDirectories?: string[];
|
|
135
|
-
mcpServers?: Record<string,
|
|
153
|
+
mcpServers?: Record<string, McpServerSpec>;
|
|
136
154
|
resume?: string;
|
|
137
155
|
/**
|
|
138
156
|
* Initial model for the spawn. Live switches use
|
|
@@ -198,16 +216,24 @@ export interface AgentSession extends AsyncIterable<NormalizedMessage> {
|
|
|
198
216
|
*/
|
|
199
217
|
setModel(model?: string): Promise<void>;
|
|
200
218
|
/**
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
219
|
+
* Switch the reasoning-effort tier live, without respawning the child
|
|
220
|
+
* process. Pass `undefined` to clear any override and let the provider
|
|
221
|
+
* fall back to its default. Gated by `CapabilityMatrix.liveEffortSwitch`
|
|
222
|
+
* — providers without live switching declare `false` and the renderer
|
|
223
|
+
* hides the inline Effort dropdown.
|
|
224
|
+
*
|
|
225
|
+
* Replaces the legacy `applyFlagSettings({ effortLevel })` bag — Claude
|
|
226
|
+
* was the only producer and Codex/Gemini both threw `UNSUPPORTED`. The
|
|
227
|
+
* host now calls this method by name and the type system tells the
|
|
228
|
+
* provider author exactly what to wire.
|
|
204
229
|
*/
|
|
205
|
-
|
|
230
|
+
setEffortLevel(effort: AgentEffortLevel | undefined): Promise<void>;
|
|
206
231
|
/**
|
|
207
|
-
* Read the effective
|
|
208
|
-
*
|
|
209
|
-
*
|
|
210
|
-
*
|
|
232
|
+
* Read the effective runtime settings the provider booted with. Today
|
|
233
|
+
* the host only consumes `effective.effortLevel` to populate the
|
|
234
|
+
* Effort dropdown's initial value; the rest of the bag is opaque so
|
|
235
|
+
* providers with richer settings layers can passthrough additional
|
|
236
|
+
* keys without an SDK bump.
|
|
211
237
|
*/
|
|
212
238
|
getSettings(): Promise<AgentSettingsResponse>;
|
|
213
239
|
}
|
package/dist/backend.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,KAAK,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,yBAAyB,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAMhC,mEAAmE;AACnE,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,aAAa,GACb,MAAM,GACN,mBAAmB,CAAA;AAEvB,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAE7D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvD
|
|
1
|
+
{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}
|
package/dist/provider.d.ts
CHANGED
|
@@ -15,23 +15,55 @@
|
|
|
15
15
|
* This file is the boundary between Jack core and a provider package — keep
|
|
16
16
|
* it free of provider-specific imports.
|
|
17
17
|
*/
|
|
18
|
-
import type { AgentBackend, AgentQueryOptions } from './backend';
|
|
18
|
+
import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend';
|
|
19
|
+
import type { ZodType } from 'zod';
|
|
19
20
|
import type { ClientToolHandler, NormalizedMessage, NormalizedToolRef, ProviderUserContentPolicy, ToolShape } from '@ottimis/jack-chat-core';
|
|
20
21
|
export type ProviderId = string;
|
|
21
22
|
/**
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
23
|
+
* Where the provider sourced a slash command from. Drives the
|
|
24
|
+
* {@link SlashCommandDef} discriminated union below — file-sourced
|
|
25
|
+
* commands carry `body` + `filePath`, builtin and wire-sourced ones
|
|
26
|
+
* don't (they don't *have* a markdown file behind them).
|
|
26
27
|
*/
|
|
27
|
-
export type
|
|
28
|
+
export type SlashCommandScope = 'builtin' | 'wire' | 'user' | 'project' | (string & {});
|
|
29
|
+
/**
|
|
30
|
+
* Common surface every slash command def carries regardless of source.
|
|
31
|
+
* The renderer uses these for autocomplete + chip rendering.
|
|
32
|
+
*/
|
|
33
|
+
type SlashCommandDefBase = {
|
|
28
34
|
name: string;
|
|
29
|
-
scope: 'user' | 'project' | 'builtin';
|
|
30
35
|
description?: string;
|
|
31
36
|
argumentHint?: string;
|
|
37
|
+
};
|
|
38
|
+
/**
|
|
39
|
+
* Slash-command definition surfaced by a provider. Three sources can
|
|
40
|
+
* coexist (see {@link SlashCommandSupport}):
|
|
41
|
+
*
|
|
42
|
+
* - `'builtin'` — static catalog the runtime intercepts. The renderer
|
|
43
|
+
* never opens the file (there is none); the executor is the agent.
|
|
44
|
+
* - `'wire'` — pushed live by the agent over the wire (Gemini ACP
|
|
45
|
+
* `available_commands_update`). Same render contract as builtin —
|
|
46
|
+
* no on-disk artifact.
|
|
47
|
+
* - `'user' | 'project'` — file-based commands the user authored
|
|
48
|
+
* (Claude `.claude/commands/foo.md`, future per-provider analogs).
|
|
49
|
+
* `filePath` + `body` are required so the renderer can offer "open
|
|
50
|
+
* in editor" affordances and the host can expand `$ARGUMENTS` /
|
|
51
|
+
* `$N` placeholders.
|
|
52
|
+
*
|
|
53
|
+
* Discriminated by `scope` so consumers narrow before reading the
|
|
54
|
+
* file-only fields. Replaces the legacy uniform shape that forced
|
|
55
|
+
* builtin/wire commands to ship synthetic empty `body: ''` /
|
|
56
|
+
* `filePath: ''`.
|
|
57
|
+
*/
|
|
58
|
+
export type SlashCommandDef = (SlashCommandDefBase & {
|
|
59
|
+
scope: 'builtin';
|
|
60
|
+
}) | (SlashCommandDefBase & {
|
|
61
|
+
scope: 'wire';
|
|
62
|
+
}) | (SlashCommandDefBase & {
|
|
63
|
+
scope: 'user' | 'project';
|
|
32
64
|
body: string;
|
|
33
65
|
filePath: string;
|
|
34
|
-
};
|
|
66
|
+
});
|
|
35
67
|
/**
|
|
36
68
|
* Parsed envelope a provider's CLI may wrap slash commands in when it logs
|
|
37
69
|
* them into the session transcript. Claude uses
|
|
@@ -193,6 +225,14 @@ export type CapabilityMatrix = {
|
|
|
193
225
|
resumeSession: boolean;
|
|
194
226
|
/** Switch model live without respawn (Claude control request `set_model`). */
|
|
195
227
|
liveModelSwitch: boolean;
|
|
228
|
+
/**
|
|
229
|
+
* Switch reasoning-effort tier live without respawn. Drives whether the
|
|
230
|
+
* inline Effort dropdown fires `setEffortLevel()` (true) or requires a
|
|
231
|
+
* spawn-time setting (false → dropdown hidden / annotated). Decoupled
|
|
232
|
+
* from `liveModelSwitch` because Codex has live model but spawn-time
|
|
233
|
+
* effort.
|
|
234
|
+
*/
|
|
235
|
+
liveEffortSwitch: boolean;
|
|
196
236
|
/** Switch permission mode live without respawn. */
|
|
197
237
|
livePermissionModeSwitch: boolean;
|
|
198
238
|
/**
|
|
@@ -315,27 +355,19 @@ export type PrepareSpawnContext = {
|
|
|
315
355
|
isPackaged: boolean;
|
|
316
356
|
};
|
|
317
357
|
/**
|
|
318
|
-
* MCP server registration in canonical
|
|
319
|
-
*
|
|
320
|
-
*
|
|
321
|
-
* {@link
|
|
322
|
-
*
|
|
323
|
-
*
|
|
358
|
+
* MCP server registration in canonical wire-format shape. Same type
|
|
359
|
+
* used at both ends of the knowledge pipeline: as
|
|
360
|
+
* {@link KnowledgeContext.mcpServers} (input to the provider) and as
|
|
361
|
+
* {@link AgentQueryOptions.mcpServers} (output from
|
|
362
|
+
* {@link JackProvider.applyKnowledgeContext}). Each provider's
|
|
363
|
+
* applyKnowledgeContext translates the merged context into its native
|
|
364
|
+
* runtime layout (Claude SDK `mcpServers` map; Codex `mcp_servers.toml`;
|
|
365
|
+
* Gemini ACP `session/new { mcpServers }`).
|
|
366
|
+
*
|
|
367
|
+
* Re-exported as `McpServerSpec` from `./backend` — same type, two names
|
|
368
|
+
* for ergonomics in different code paths.
|
|
324
369
|
*/
|
|
325
|
-
export type KnowledgeMcpResolution =
|
|
326
|
-
type: 'stdio';
|
|
327
|
-
command: string;
|
|
328
|
-
args?: string[];
|
|
329
|
-
env?: Record<string, string>;
|
|
330
|
-
} | {
|
|
331
|
-
type: 'http';
|
|
332
|
-
url: string;
|
|
333
|
-
headers?: Record<string, string>;
|
|
334
|
-
} | {
|
|
335
|
-
type: 'sse';
|
|
336
|
-
url: string;
|
|
337
|
-
headers?: Record<string, string>;
|
|
338
|
-
};
|
|
370
|
+
export type KnowledgeMcpResolution = McpServerSpec;
|
|
339
371
|
/**
|
|
340
372
|
* Provider-neutral container for everything the host has computed about the
|
|
341
373
|
* agent's working context: the system prompt addendum (markdown), the extra
|
|
@@ -370,6 +402,14 @@ export type KnowledgeContext = {
|
|
|
370
402
|
* names the renderer maps to React components. Providers that don't
|
|
371
403
|
* declare branding fall back to neutral defaults.
|
|
372
404
|
*/
|
|
405
|
+
/**
|
|
406
|
+
* Curated icon catalog keys the renderer knows how to map to lucide React
|
|
407
|
+
* components. Hybrid closed/open: well-known values get autocomplete;
|
|
408
|
+
* arbitrary strings still type-check (the renderer falls back to a default
|
|
409
|
+
* icon for unknown keys, so a provider can ship a forward-looking key
|
|
410
|
+
* without breaking older hosts).
|
|
411
|
+
*/
|
|
412
|
+
export type ProviderIconKey = 'sparkles' | 'cpu' | 'gem' | 'bot' | 'brain' | 'star' | 'wand' | 'zap' | (string & {});
|
|
373
413
|
export type ProviderBranding = {
|
|
374
414
|
/**
|
|
375
415
|
* Primary accent color. Used as a subtle border on the chat composer +
|
|
@@ -382,12 +422,13 @@ export type ProviderBranding = {
|
|
|
382
422
|
*/
|
|
383
423
|
accentColor: string;
|
|
384
424
|
/**
|
|
385
|
-
* Curated icon key — one of
|
|
386
|
-
*
|
|
387
|
-
*
|
|
388
|
-
*
|
|
425
|
+
* Curated icon key — one of {@link ProviderIconKey}. Keeping this a
|
|
426
|
+
* closed/open enum (instead of free-form SVG/asset) means providers
|
|
427
|
+
* don't ship rendering assets and the host stays in control of what
|
|
428
|
+
* shapes can land in the UI. Unknown keys fall back to a default icon
|
|
429
|
+
* in the renderer.
|
|
389
430
|
*/
|
|
390
|
-
iconKey?:
|
|
431
|
+
iconKey?: ProviderIconKey;
|
|
391
432
|
};
|
|
392
433
|
export type JackProvider = {
|
|
393
434
|
id: ProviderId;
|
|
@@ -538,16 +579,8 @@ export type JackProvider = {
|
|
|
538
579
|
*
|
|
539
580
|
* Pattern A providers (Claude, Codex) leave this undefined; the host
|
|
540
581
|
* detects the pattern by absence and skips wiring.
|
|
541
|
-
*
|
|
542
|
-
* `ctx` carries the host's correlation ids the provider may want to
|
|
543
|
-
* bridge to wire-driven side channels (e.g. mapping
|
|
544
|
-
* `available_commands_update` notifications back to the renderer's
|
|
545
|
-
* slash command store via the host's session id). Optional for
|
|
546
|
-
* providers that don't need it.
|
|
547
582
|
*/
|
|
548
|
-
attachClientToolHandler?(handler: ClientToolHandler, ctx
|
|
549
|
-
jackSessionId?: string;
|
|
550
|
-
}): void;
|
|
583
|
+
attachClientToolHandler?(handler: ClientToolHandler, ctx: ClientToolHandlerAttachContext): void;
|
|
551
584
|
/**
|
|
552
585
|
* Persisted permission rules manager. The host's
|
|
553
586
|
* `permissions:{list,add,remove}` IPC dispatches through this — providers
|
|
@@ -571,6 +604,33 @@ export type InProcessMcpServerSpec = {
|
|
|
571
604
|
version: string;
|
|
572
605
|
tools: InProcessMcpToolSpec[];
|
|
573
606
|
};
|
|
607
|
+
/**
|
|
608
|
+
* Context the host hands to {@link JackProvider.attachClientToolHandler}
|
|
609
|
+
* so the provider can bridge wire-driven side channels back to the host
|
|
610
|
+
* (e.g. mapping Gemini's `available_commands_update` notifications to
|
|
611
|
+
* the renderer's per-session slash command store).
|
|
612
|
+
*
|
|
613
|
+
* Today only `sessionId` is consumed. `actorId` is reserved for the
|
|
614
|
+
* future team-tier multi-user mode (north-star: every entity carries an
|
|
615
|
+
* actor id so coordination scales beyond single-user). Adding a new
|
|
616
|
+
* required field here would be a major bump; new optional fields ride
|
|
617
|
+
* on a minor.
|
|
618
|
+
*/
|
|
619
|
+
export type ClientToolHandlerAttachContext = {
|
|
620
|
+
/**
|
|
621
|
+
* Host correlation id for the session being spawned. Required —
|
|
622
|
+
* the provider stores it on its per-spawn slot so wire notifications
|
|
623
|
+
* can route back to the right host-side consumer.
|
|
624
|
+
*/
|
|
625
|
+
sessionId: string;
|
|
626
|
+
/**
|
|
627
|
+
* Actor identity placeholder for future multi-user / team-tier
|
|
628
|
+
* support. Today the host always passes `'self'` (or omits) since
|
|
629
|
+
* Jack runs single-user; future remote-agent flows will populate
|
|
630
|
+
* with `'user_xxx@team_yyy'` style strings.
|
|
631
|
+
*/
|
|
632
|
+
actorId?: string;
|
|
633
|
+
};
|
|
574
634
|
/**
|
|
575
635
|
* Behaviour token the provider persists alongside each rule. Mirror of
|
|
576
636
|
* Claude's `permissions.{allow,deny,ask}` arrays — providers with a
|
|
@@ -585,17 +645,32 @@ export type PermissionBehavior = 'allow' | 'deny' | 'ask';
|
|
|
585
645
|
*/
|
|
586
646
|
export type PermissionSource = 'user' | 'userLocal' | 'project' | 'projectLocal';
|
|
587
647
|
/**
|
|
588
|
-
*
|
|
589
|
-
*
|
|
590
|
-
* (
|
|
648
|
+
* Optional human-readable parse hint for {@link PermissionRule}. Providers
|
|
649
|
+
* whose rule grammar has a recognisable "tool" + "pattern" decomposition
|
|
650
|
+
* (Claude's `Bash(npm install)`, `Edit(*.ts)`) populate this so the UI can
|
|
651
|
+
* render two columns instead of a raw string. Providers with a different
|
|
652
|
+
* grammar (Codex `approval_policy` keyed by command prefix) leave it
|
|
653
|
+
* undefined; the UI falls back to displaying `raw`.
|
|
654
|
+
*/
|
|
655
|
+
export type PermissionRuleHumanReadable = {
|
|
656
|
+
/** Best-effort tool name extracted by the provider (e.g. `Bash`, `Edit`). */
|
|
657
|
+
tool?: string;
|
|
658
|
+
/** Best-effort pattern extracted by the provider (the bit inside the parens, etc.). */
|
|
659
|
+
pattern?: string;
|
|
660
|
+
};
|
|
661
|
+
/**
|
|
662
|
+
* One persisted rule as the provider stores it. `raw` is the only
|
|
663
|
+
* field guaranteed across providers — it's the source of truth for
|
|
664
|
+
* round-trip writes (remove/add use the raw string verbatim) and the
|
|
665
|
+
* fallback display when no parse hint is available. The
|
|
666
|
+
* `humanReadable` sidecar is a Claude-style ergonomic split that
|
|
667
|
+
* other providers may opt out of.
|
|
591
668
|
*/
|
|
592
669
|
export type PermissionRule = {
|
|
593
|
-
/**
|
|
594
|
-
tool: string;
|
|
595
|
-
/** Content inside the parens (the glob / pattern), or null if the rule has no parens. */
|
|
596
|
-
pattern: string | null;
|
|
597
|
-
/** Original string as stored in the settings file — source of truth for round-trip writes. */
|
|
670
|
+
/** Original string as stored by the provider — source of truth for round-trip writes. */
|
|
598
671
|
raw: string;
|
|
672
|
+
/** Optional parse hint for two-column UI rendering. */
|
|
673
|
+
humanReadable?: PermissionRuleHumanReadable;
|
|
599
674
|
};
|
|
600
675
|
export type PermissionsSourceBlock = {
|
|
601
676
|
source: PermissionSource;
|
|
@@ -634,12 +709,17 @@ export type InProcessMcpToolSpec = {
|
|
|
634
709
|
name: string;
|
|
635
710
|
description: string;
|
|
636
711
|
/**
|
|
637
|
-
* Zod schema for the tool arguments
|
|
638
|
-
*
|
|
639
|
-
*
|
|
640
|
-
* (
|
|
712
|
+
* Zod schema for the tool arguments — a `Record<fieldName, ZodType>`
|
|
713
|
+
* (zod's "shape" form, what `z.object(...)` accepts). Provider
|
|
714
|
+
* implementations consume it via the SDK helper of their choice
|
|
715
|
+
* (Claude wraps with `tool(name, desc, schema, handler)` from
|
|
716
|
+
* `@anthropic-ai/claude-agent-sdk`).
|
|
717
|
+
*
|
|
718
|
+
* `zod` is a peer dep of this SDK so consumer + provider type-check
|
|
719
|
+
* against the same instance. The host always produces zod; trying
|
|
720
|
+
* to stuff JSON Schema here would silently break Claude's wrapper.
|
|
641
721
|
*/
|
|
642
|
-
schema: Record<string,
|
|
722
|
+
schema: Record<string, ZodType>;
|
|
643
723
|
handler: (args: Record<string, unknown>) => Promise<{
|
|
644
724
|
content: Array<{
|
|
645
725
|
type: 'text';
|
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ottimis/jack-provider-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -29,12 +29,14 @@
|
|
|
29
29
|
"clean": "rm -rf dist"
|
|
30
30
|
},
|
|
31
31
|
"peerDependencies": {
|
|
32
|
-
"@ottimis/jack-chat-core": ">=0.5.5"
|
|
32
|
+
"@ottimis/jack-chat-core": ">=0.5.5",
|
|
33
|
+
"zod": ">=3.22.0"
|
|
33
34
|
},
|
|
34
35
|
"devDependencies": {
|
|
35
36
|
"@ottimis/jack-chat-core": "^0.5.5",
|
|
36
37
|
"@types/node": "^22.14.1",
|
|
37
38
|
"tsx": "^4.19.2",
|
|
38
|
-
"typescript": "^5.8.3"
|
|
39
|
+
"typescript": "^5.8.3",
|
|
40
|
+
"zod": "^4.3.6"
|
|
39
41
|
}
|
|
40
42
|
}
|
package/src/backend.ts
CHANGED
|
@@ -65,10 +65,18 @@ export type AgentSystemPrompt =
|
|
|
65
65
|
| { type: 'preset'; preset: string; append?: string }
|
|
66
66
|
|
|
67
67
|
/**
|
|
68
|
-
* MCP server configuration
|
|
69
|
-
*
|
|
68
|
+
* MCP server configuration handed to the provider via
|
|
69
|
+
* {@link AgentQueryOptions.mcpServers}. Mirrors the official MCP wire
|
|
70
|
+
* format (the same shape Anthropic, OpenAI, and Google all consume).
|
|
71
|
+
*
|
|
72
|
+
* Replaces the legacy opaque `AgentMcpServerConfig = unknown` so the
|
|
73
|
+
* type system enforces the contract end-to-end and the host can inspect
|
|
74
|
+
* the bag for telemetry / preview without double-translating.
|
|
70
75
|
*/
|
|
71
|
-
export type
|
|
76
|
+
export type McpServerSpec =
|
|
77
|
+
| { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
|
|
78
|
+
| { type: 'http'; url: string; headers?: Record<string, string> }
|
|
79
|
+
| { type: 'sse'; url: string; headers?: Record<string, string> }
|
|
72
80
|
|
|
73
81
|
/** Reasoning-effort knob. Provider-validated; not all providers honor every value. */
|
|
74
82
|
export type AgentEffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
|
|
@@ -161,7 +169,7 @@ export type AgentQueryOptions = {
|
|
|
161
169
|
* knowledge sources).
|
|
162
170
|
*/
|
|
163
171
|
additionalDirectories?: string[]
|
|
164
|
-
mcpServers?: Record<string,
|
|
172
|
+
mcpServers?: Record<string, McpServerSpec>
|
|
165
173
|
resume?: string
|
|
166
174
|
/**
|
|
167
175
|
* Initial model for the spawn. Live switches use
|
|
@@ -231,16 +239,24 @@ export interface AgentSession extends AsyncIterable<NormalizedMessage> {
|
|
|
231
239
|
*/
|
|
232
240
|
setModel(model?: string): Promise<void>
|
|
233
241
|
/**
|
|
234
|
-
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
242
|
+
* Switch the reasoning-effort tier live, without respawning the child
|
|
243
|
+
* process. Pass `undefined` to clear any override and let the provider
|
|
244
|
+
* fall back to its default. Gated by `CapabilityMatrix.liveEffortSwitch`
|
|
245
|
+
* — providers without live switching declare `false` and the renderer
|
|
246
|
+
* hides the inline Effort dropdown.
|
|
247
|
+
*
|
|
248
|
+
* Replaces the legacy `applyFlagSettings({ effortLevel })` bag — Claude
|
|
249
|
+
* was the only producer and Codex/Gemini both threw `UNSUPPORTED`. The
|
|
250
|
+
* host now calls this method by name and the type system tells the
|
|
251
|
+
* provider author exactly what to wire.
|
|
237
252
|
*/
|
|
238
|
-
|
|
253
|
+
setEffortLevel(effort: AgentEffortLevel | undefined): Promise<void>
|
|
239
254
|
/**
|
|
240
|
-
* Read the effective
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
255
|
+
* Read the effective runtime settings the provider booted with. Today
|
|
256
|
+
* the host only consumes `effective.effortLevel` to populate the
|
|
257
|
+
* Effort dropdown's initial value; the rest of the bag is opaque so
|
|
258
|
+
* providers with richer settings layers can passthrough additional
|
|
259
|
+
* keys without an SDK bump.
|
|
244
260
|
*/
|
|
245
261
|
getSettings(): Promise<AgentSettingsResponse>
|
|
246
262
|
}
|
package/src/provider.ts
CHANGED
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
* it free of provider-specific imports.
|
|
17
17
|
*/
|
|
18
18
|
|
|
19
|
-
import type { AgentBackend, AgentQueryOptions } from './backend'
|
|
19
|
+
import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend'
|
|
20
|
+
import type { ZodType } from 'zod'
|
|
20
21
|
import type {
|
|
21
22
|
ClientToolHandler,
|
|
22
23
|
NormalizedMessage,
|
|
@@ -28,20 +29,48 @@ import type {
|
|
|
28
29
|
export type ProviderId = string
|
|
29
30
|
|
|
30
31
|
/**
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
32
|
+
* Where the provider sourced a slash command from. Drives the
|
|
33
|
+
* {@link SlashCommandDef} discriminated union below — file-sourced
|
|
34
|
+
* commands carry `body` + `filePath`, builtin and wire-sourced ones
|
|
35
|
+
* don't (they don't *have* a markdown file behind them).
|
|
35
36
|
*/
|
|
36
|
-
export type
|
|
37
|
+
export type SlashCommandScope = 'builtin' | 'wire' | 'user' | 'project' | (string & {})
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Common surface every slash command def carries regardless of source.
|
|
41
|
+
* The renderer uses these for autocomplete + chip rendering.
|
|
42
|
+
*/
|
|
43
|
+
type SlashCommandDefBase = {
|
|
37
44
|
name: string
|
|
38
|
-
scope: 'user' | 'project' | 'builtin'
|
|
39
45
|
description?: string
|
|
40
46
|
argumentHint?: string
|
|
41
|
-
body: string
|
|
42
|
-
filePath: string
|
|
43
47
|
}
|
|
44
48
|
|
|
49
|
+
/**
|
|
50
|
+
* Slash-command definition surfaced by a provider. Three sources can
|
|
51
|
+
* coexist (see {@link SlashCommandSupport}):
|
|
52
|
+
*
|
|
53
|
+
* - `'builtin'` — static catalog the runtime intercepts. The renderer
|
|
54
|
+
* never opens the file (there is none); the executor is the agent.
|
|
55
|
+
* - `'wire'` — pushed live by the agent over the wire (Gemini ACP
|
|
56
|
+
* `available_commands_update`). Same render contract as builtin —
|
|
57
|
+
* no on-disk artifact.
|
|
58
|
+
* - `'user' | 'project'` — file-based commands the user authored
|
|
59
|
+
* (Claude `.claude/commands/foo.md`, future per-provider analogs).
|
|
60
|
+
* `filePath` + `body` are required so the renderer can offer "open
|
|
61
|
+
* in editor" affordances and the host can expand `$ARGUMENTS` /
|
|
62
|
+
* `$N` placeholders.
|
|
63
|
+
*
|
|
64
|
+
* Discriminated by `scope` so consumers narrow before reading the
|
|
65
|
+
* file-only fields. Replaces the legacy uniform shape that forced
|
|
66
|
+
* builtin/wire commands to ship synthetic empty `body: ''` /
|
|
67
|
+
* `filePath: ''`.
|
|
68
|
+
*/
|
|
69
|
+
export type SlashCommandDef =
|
|
70
|
+
| (SlashCommandDefBase & { scope: 'builtin' })
|
|
71
|
+
| (SlashCommandDefBase & { scope: 'wire' })
|
|
72
|
+
| (SlashCommandDefBase & { scope: 'user' | 'project'; body: string; filePath: string })
|
|
73
|
+
|
|
45
74
|
/**
|
|
46
75
|
* Parsed envelope a provider's CLI may wrap slash commands in when it logs
|
|
47
76
|
* them into the session transcript. Claude uses
|
|
@@ -212,6 +241,14 @@ export type CapabilityMatrix = {
|
|
|
212
241
|
resumeSession: boolean
|
|
213
242
|
/** Switch model live without respawn (Claude control request `set_model`). */
|
|
214
243
|
liveModelSwitch: boolean
|
|
244
|
+
/**
|
|
245
|
+
* Switch reasoning-effort tier live without respawn. Drives whether the
|
|
246
|
+
* inline Effort dropdown fires `setEffortLevel()` (true) or requires a
|
|
247
|
+
* spawn-time setting (false → dropdown hidden / annotated). Decoupled
|
|
248
|
+
* from `liveModelSwitch` because Codex has live model but spawn-time
|
|
249
|
+
* effort.
|
|
250
|
+
*/
|
|
251
|
+
liveEffortSwitch: boolean
|
|
215
252
|
/** Switch permission mode live without respawn. */
|
|
216
253
|
livePermissionModeSwitch: boolean
|
|
217
254
|
/**
|
|
@@ -353,17 +390,19 @@ export type PrepareSpawnContext = {
|
|
|
353
390
|
}
|
|
354
391
|
|
|
355
392
|
/**
|
|
356
|
-
* MCP server registration in canonical
|
|
357
|
-
*
|
|
358
|
-
*
|
|
359
|
-
* {@link
|
|
360
|
-
*
|
|
361
|
-
*
|
|
393
|
+
* MCP server registration in canonical wire-format shape. Same type
|
|
394
|
+
* used at both ends of the knowledge pipeline: as
|
|
395
|
+
* {@link KnowledgeContext.mcpServers} (input to the provider) and as
|
|
396
|
+
* {@link AgentQueryOptions.mcpServers} (output from
|
|
397
|
+
* {@link JackProvider.applyKnowledgeContext}). Each provider's
|
|
398
|
+
* applyKnowledgeContext translates the merged context into its native
|
|
399
|
+
* runtime layout (Claude SDK `mcpServers` map; Codex `mcp_servers.toml`;
|
|
400
|
+
* Gemini ACP `session/new { mcpServers }`).
|
|
401
|
+
*
|
|
402
|
+
* Re-exported as `McpServerSpec` from `./backend` — same type, two names
|
|
403
|
+
* for ergonomics in different code paths.
|
|
362
404
|
*/
|
|
363
|
-
export type KnowledgeMcpResolution =
|
|
364
|
-
| { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
|
|
365
|
-
| { type: 'http'; url: string; headers?: Record<string, string> }
|
|
366
|
-
| { type: 'sse'; url: string; headers?: Record<string, string> }
|
|
405
|
+
export type KnowledgeMcpResolution = McpServerSpec
|
|
367
406
|
|
|
368
407
|
/**
|
|
369
408
|
* Provider-neutral container for everything the host has computed about the
|
|
@@ -400,6 +439,24 @@ export type KnowledgeContext = {
|
|
|
400
439
|
* names the renderer maps to React components. Providers that don't
|
|
401
440
|
* declare branding fall back to neutral defaults.
|
|
402
441
|
*/
|
|
442
|
+
/**
|
|
443
|
+
* Curated icon catalog keys the renderer knows how to map to lucide React
|
|
444
|
+
* components. Hybrid closed/open: well-known values get autocomplete;
|
|
445
|
+
* arbitrary strings still type-check (the renderer falls back to a default
|
|
446
|
+
* icon for unknown keys, so a provider can ship a forward-looking key
|
|
447
|
+
* without breaking older hosts).
|
|
448
|
+
*/
|
|
449
|
+
export type ProviderIconKey =
|
|
450
|
+
| 'sparkles'
|
|
451
|
+
| 'cpu'
|
|
452
|
+
| 'gem'
|
|
453
|
+
| 'bot'
|
|
454
|
+
| 'brain'
|
|
455
|
+
| 'star'
|
|
456
|
+
| 'wand'
|
|
457
|
+
| 'zap'
|
|
458
|
+
| (string & {})
|
|
459
|
+
|
|
403
460
|
export type ProviderBranding = {
|
|
404
461
|
/**
|
|
405
462
|
* Primary accent color. Used as a subtle border on the chat composer +
|
|
@@ -412,12 +469,13 @@ export type ProviderBranding = {
|
|
|
412
469
|
*/
|
|
413
470
|
accentColor: string
|
|
414
471
|
/**
|
|
415
|
-
* Curated icon key — one of
|
|
416
|
-
*
|
|
417
|
-
*
|
|
418
|
-
*
|
|
472
|
+
* Curated icon key — one of {@link ProviderIconKey}. Keeping this a
|
|
473
|
+
* closed/open enum (instead of free-form SVG/asset) means providers
|
|
474
|
+
* don't ship rendering assets and the host stays in control of what
|
|
475
|
+
* shapes can land in the UI. Unknown keys fall back to a default icon
|
|
476
|
+
* in the renderer.
|
|
419
477
|
*/
|
|
420
|
-
iconKey?:
|
|
478
|
+
iconKey?: ProviderIconKey
|
|
421
479
|
}
|
|
422
480
|
|
|
423
481
|
export type JackProvider = {
|
|
@@ -572,16 +630,10 @@ export type JackProvider = {
|
|
|
572
630
|
*
|
|
573
631
|
* Pattern A providers (Claude, Codex) leave this undefined; the host
|
|
574
632
|
* detects the pattern by absence and skips wiring.
|
|
575
|
-
*
|
|
576
|
-
* `ctx` carries the host's correlation ids the provider may want to
|
|
577
|
-
* bridge to wire-driven side channels (e.g. mapping
|
|
578
|
-
* `available_commands_update` notifications back to the renderer's
|
|
579
|
-
* slash command store via the host's session id). Optional for
|
|
580
|
-
* providers that don't need it.
|
|
581
633
|
*/
|
|
582
634
|
attachClientToolHandler?(
|
|
583
635
|
handler: ClientToolHandler,
|
|
584
|
-
ctx
|
|
636
|
+
ctx: ClientToolHandlerAttachContext
|
|
585
637
|
): void
|
|
586
638
|
/**
|
|
587
639
|
* Persisted permission rules manager. The host's
|
|
@@ -608,6 +660,34 @@ export type InProcessMcpServerSpec = {
|
|
|
608
660
|
tools: InProcessMcpToolSpec[]
|
|
609
661
|
}
|
|
610
662
|
|
|
663
|
+
/**
|
|
664
|
+
* Context the host hands to {@link JackProvider.attachClientToolHandler}
|
|
665
|
+
* so the provider can bridge wire-driven side channels back to the host
|
|
666
|
+
* (e.g. mapping Gemini's `available_commands_update` notifications to
|
|
667
|
+
* the renderer's per-session slash command store).
|
|
668
|
+
*
|
|
669
|
+
* Today only `sessionId` is consumed. `actorId` is reserved for the
|
|
670
|
+
* future team-tier multi-user mode (north-star: every entity carries an
|
|
671
|
+
* actor id so coordination scales beyond single-user). Adding a new
|
|
672
|
+
* required field here would be a major bump; new optional fields ride
|
|
673
|
+
* on a minor.
|
|
674
|
+
*/
|
|
675
|
+
export type ClientToolHandlerAttachContext = {
|
|
676
|
+
/**
|
|
677
|
+
* Host correlation id for the session being spawned. Required —
|
|
678
|
+
* the provider stores it on its per-spawn slot so wire notifications
|
|
679
|
+
* can route back to the right host-side consumer.
|
|
680
|
+
*/
|
|
681
|
+
sessionId: string
|
|
682
|
+
/**
|
|
683
|
+
* Actor identity placeholder for future multi-user / team-tier
|
|
684
|
+
* support. Today the host always passes `'self'` (or omits) since
|
|
685
|
+
* Jack runs single-user; future remote-agent flows will populate
|
|
686
|
+
* with `'user_xxx@team_yyy'` style strings.
|
|
687
|
+
*/
|
|
688
|
+
actorId?: string
|
|
689
|
+
}
|
|
690
|
+
|
|
611
691
|
/**
|
|
612
692
|
* Behaviour token the provider persists alongside each rule. Mirror of
|
|
613
693
|
* Claude's `permissions.{allow,deny,ask}` arrays — providers with a
|
|
@@ -624,17 +704,33 @@ export type PermissionBehavior = 'allow' | 'deny' | 'ask'
|
|
|
624
704
|
export type PermissionSource = 'user' | 'userLocal' | 'project' | 'projectLocal'
|
|
625
705
|
|
|
626
706
|
/**
|
|
627
|
-
*
|
|
628
|
-
*
|
|
629
|
-
* (
|
|
707
|
+
* Optional human-readable parse hint for {@link PermissionRule}. Providers
|
|
708
|
+
* whose rule grammar has a recognisable "tool" + "pattern" decomposition
|
|
709
|
+
* (Claude's `Bash(npm install)`, `Edit(*.ts)`) populate this so the UI can
|
|
710
|
+
* render two columns instead of a raw string. Providers with a different
|
|
711
|
+
* grammar (Codex `approval_policy` keyed by command prefix) leave it
|
|
712
|
+
* undefined; the UI falls back to displaying `raw`.
|
|
713
|
+
*/
|
|
714
|
+
export type PermissionRuleHumanReadable = {
|
|
715
|
+
/** Best-effort tool name extracted by the provider (e.g. `Bash`, `Edit`). */
|
|
716
|
+
tool?: string
|
|
717
|
+
/** Best-effort pattern extracted by the provider (the bit inside the parens, etc.). */
|
|
718
|
+
pattern?: string
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
/**
|
|
722
|
+
* One persisted rule as the provider stores it. `raw` is the only
|
|
723
|
+
* field guaranteed across providers — it's the source of truth for
|
|
724
|
+
* round-trip writes (remove/add use the raw string verbatim) and the
|
|
725
|
+
* fallback display when no parse hint is available. The
|
|
726
|
+
* `humanReadable` sidecar is a Claude-style ergonomic split that
|
|
727
|
+
* other providers may opt out of.
|
|
630
728
|
*/
|
|
631
729
|
export type PermissionRule = {
|
|
632
|
-
/**
|
|
633
|
-
tool: string
|
|
634
|
-
/** Content inside the parens (the glob / pattern), or null if the rule has no parens. */
|
|
635
|
-
pattern: string | null
|
|
636
|
-
/** Original string as stored in the settings file — source of truth for round-trip writes. */
|
|
730
|
+
/** Original string as stored by the provider — source of truth for round-trip writes. */
|
|
637
731
|
raw: string
|
|
732
|
+
/** Optional parse hint for two-column UI rendering. */
|
|
733
|
+
humanReadable?: PermissionRuleHumanReadable
|
|
638
734
|
}
|
|
639
735
|
|
|
640
736
|
export type PermissionsSourceBlock = {
|
|
@@ -687,12 +783,17 @@ export type InProcessMcpToolSpec = {
|
|
|
687
783
|
name: string
|
|
688
784
|
description: string
|
|
689
785
|
/**
|
|
690
|
-
* Zod schema for the tool arguments
|
|
691
|
-
*
|
|
692
|
-
*
|
|
693
|
-
* (
|
|
786
|
+
* Zod schema for the tool arguments — a `Record<fieldName, ZodType>`
|
|
787
|
+
* (zod's "shape" form, what `z.object(...)` accepts). Provider
|
|
788
|
+
* implementations consume it via the SDK helper of their choice
|
|
789
|
+
* (Claude wraps with `tool(name, desc, schema, handler)` from
|
|
790
|
+
* `@anthropic-ai/claude-agent-sdk`).
|
|
791
|
+
*
|
|
792
|
+
* `zod` is a peer dep of this SDK so consumer + provider type-check
|
|
793
|
+
* against the same instance. The host always produces zod; trying
|
|
794
|
+
* to stuff JSON Schema here would silently break Claude's wrapper.
|
|
694
795
|
*/
|
|
695
|
-
schema: Record<string,
|
|
796
|
+
schema: Record<string, ZodType>
|
|
696
797
|
handler: (args: Record<string, unknown>) => Promise<{
|
|
697
798
|
content: Array<{ type: 'text'; text: string }>
|
|
698
799
|
isError?: boolean
|