@dxos/introspect-tools 0.8.4-main.fdfb99ef29 → 0.9.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dxos/introspect-tools",
3
- "version": "0.8.4-main.fdfb99ef29",
3
+ "version": "0.9.0",
4
4
  "description": "Tool definitions (Effect Schema inputs + metadata) shared between the introspect-mcp server and downstream consumers (react-ui-introspect, etc.). Browser-safe — no Node-only dependencies.",
5
5
  "homepage": "https://dxos.org",
6
6
  "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
8
8
  "type": "git",
9
9
  "url": "https://github.com/dxos/dxos"
10
10
  },
11
- "license": "MIT",
11
+ "license": "FSL-1.1-Apache-2.0",
12
12
  "author": "info@dxos.org",
13
13
  "sideEffects": false,
14
14
  "type": "module",
@@ -26,15 +26,15 @@
26
26
  "src"
27
27
  ],
28
28
  "dependencies": {
29
- "effect": "3.20.0",
29
+ "effect": "3.21.3",
30
30
  "zod": "^4.0.0",
31
- "@dxos/effect-zod": "0.8.4-main.fdfb99ef29",
32
- "@dxos/util": "0.8.4-main.fdfb99ef29"
31
+ "@dxos/effect-zod": "0.9.0",
32
+ "@dxos/util": "0.9.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@types/node": "22.10.2",
36
36
  "typescript": "^6.0.3",
37
- "vitest": "4.1.5"
37
+ "vitest": "4.1.7"
38
38
  },
39
39
  "publishConfig": {
40
40
  "access": "public"
package/src/index.ts CHANGED
@@ -8,11 +8,49 @@
8
8
 
9
9
  export { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, type ListOptions } from './limits';
10
10
  export { TOOL_METADATA, inputSchemaToZod, type ToolMetadata } from './metadata';
11
+ export {
12
+ CapabilitySchema,
13
+ IdiomHostKindSchema,
14
+ IdiomHostSchema,
15
+ IdiomSchema,
16
+ OperationSchema,
17
+ PackageDetailSchema,
18
+ PackageSchema,
19
+ PluginDetailSchema,
20
+ PluginIdSchema,
21
+ PluginSchema,
22
+ SchemaSchema,
23
+ SourceLocationSchema,
24
+ SurfaceSchema,
25
+ SymbolDetailSchema,
26
+ SymbolIncludeSchema,
27
+ SymbolKindSchema,
28
+ SymbolMatchSchema,
29
+ type Capability,
30
+ type Idiom,
31
+ type IdiomHost,
32
+ type IdiomHostKind,
33
+ type Operation,
34
+ type Package,
35
+ type PackageDetail,
36
+ type Plugin,
37
+ type PluginDetail,
38
+ type PluginId,
39
+ type PluginsFile,
40
+ type SchemaContribution,
41
+ type SourceLocation,
42
+ type Surface,
43
+ type SymbolDetail,
44
+ type SymbolInclude,
45
+ type SymbolKind,
46
+ type SymbolMatch,
47
+ } from './output-schemas';
11
48
  export {
12
49
  FindSymbolInput,
13
50
  GetPackageInput,
14
51
  GetSymbolInput,
15
52
  ListCapabilitiesInput,
53
+ ListIdiomsInput,
16
54
  ListOperationsInput,
17
55
  ListOptionsInput,
18
56
  ListPackagesInput,
@@ -20,14 +58,18 @@ export {
20
58
  ListSchemasInput,
21
59
  ListSurfacesInput,
22
60
  ListSymbolsInput,
61
+ PickerAnnotationId,
62
+ getPicker,
23
63
  type FindSymbolArgs,
24
64
  type GetPackageArgs,
25
65
  type GetSymbolArgs,
26
66
  type ListCapabilitiesArgs,
67
+ type ListIdiomsArgs,
27
68
  type ListOperationsArgs,
28
69
  type ListPackagesArgs,
29
70
  type ListPluginsArgs,
30
71
  type ListSchemasArgs,
31
72
  type ListSurfacesArgs,
32
73
  type ListSymbolsArgs,
74
+ type PickerKind,
33
75
  } from './schemas';
@@ -0,0 +1,55 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { TOOL_METADATA } from './metadata';
8
+
9
+ // Top-level field key each tool's outputSchema must expose. MCP requires
10
+ // `structuredContent` to be a JSON object, so every tool wraps its
11
+ // result(s) under a stable key — this is the contract downstream
12
+ // consumers (e.g. dxos/edge introspect-service) bind to.
13
+ const EXPECTED_OUTPUT_KEYS: Record<string, string> = {
14
+ list_packages: 'packages',
15
+ get_package: 'package',
16
+ list_symbols: 'symbols',
17
+ find_symbol: 'matches',
18
+ get_symbol: 'symbol',
19
+ list_plugins: 'plugins',
20
+ list_surfaces: 'surfaces',
21
+ list_capabilities: 'capabilities',
22
+ list_operations: 'operations',
23
+ list_schemas: 'schemas',
24
+ list_idioms: 'idioms',
25
+ };
26
+
27
+ describe('TOOL_METADATA', () => {
28
+ test('every entry declares title, description, inputSchema, outputSchema', ({ expect }) => {
29
+ for (const [name, meta] of Object.entries(TOOL_METADATA)) {
30
+ expect(meta.title, `${name}.title`).toBeTypeOf('string');
31
+ expect(meta.description, `${name}.description`).toBeTypeOf('string');
32
+ expect(meta.inputSchema, `${name}.inputSchema`).toBeDefined();
33
+ expect(meta.inputSchema.fields, `${name}.inputSchema.fields`).toBeDefined();
34
+ expect(meta.outputSchema, `${name}.outputSchema`).toBeDefined();
35
+ expect(meta.outputSchema.fields, `${name}.outputSchema.fields`).toBeDefined();
36
+ }
37
+ });
38
+
39
+ test('outputSchema top-level key matches the documented convention', ({ expect }) => {
40
+ for (const [name, expectedKey] of Object.entries(EXPECTED_OUTPUT_KEYS)) {
41
+ const meta = TOOL_METADATA[name];
42
+ expect(meta, `tool ${name} missing from TOOL_METADATA`).toBeDefined();
43
+ const keys = Object.keys(meta.outputSchema.fields);
44
+ expect(keys, `${name}.outputSchema fields`).toEqual([expectedKey]);
45
+ }
46
+ });
47
+
48
+ test('all registered tools have an expected output key entry', ({ expect }) => {
49
+ // Catches new tools added to TOOL_METADATA without a corresponding
50
+ // documented output-key convention.
51
+ for (const name of Object.keys(TOOL_METADATA)) {
52
+ expect(EXPECTED_OUTPUT_KEYS[name], `tool ${name} missing from EXPECTED_OUTPUT_KEYS`).toBeDefined();
53
+ }
54
+ });
55
+ });
package/src/metadata.ts CHANGED
@@ -16,11 +16,23 @@ import type { z } from 'zod';
16
16
  import { effectFieldsToZod } from '@dxos/effect-zod';
17
17
  import { trim } from '@dxos/util';
18
18
 
19
+ import {
20
+ CapabilitySchema,
21
+ IdiomSchema,
22
+ OperationSchema,
23
+ PackageSchema,
24
+ PluginSchema,
25
+ SchemaSchema,
26
+ SurfaceSchema,
27
+ SymbolDetailSchema,
28
+ SymbolMatchSchema,
29
+ } from './output-schemas';
19
30
  import {
20
31
  FindSymbolInput,
21
32
  GetPackageInput,
22
33
  GetSymbolInput,
23
34
  ListCapabilitiesInput,
35
+ ListIdiomsInput,
24
36
  ListOperationsInput,
25
37
  ListPackagesInput,
26
38
  ListPluginsInput,
@@ -52,6 +64,15 @@ export type ToolMetadata = {
52
64
  * (react-ui-form, etc.) use this directly.
53
65
  */
54
66
  inputSchema: Schema.Struct<any>;
67
+
68
+ /**
69
+ * Effect Schema struct describing the tool's success return shape.
70
+ * MCP's `structuredContent` must be a JSON object, so each tool wraps
71
+ * its item(s) under a stable top-level key (e.g. `{ packages: [...] }`,
72
+ * `{ package: null | {...} }`). Consumers building Effect AI Tools can
73
+ * pass this directly as `success` to `Tool.make`.
74
+ */
75
+ outputSchema: Schema.Struct<any>;
55
76
  };
56
77
 
57
78
  /**
@@ -71,6 +92,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
71
92
  Returns lightweight rows; call get_package for dependency and entry-point detail.
72
93
  `,
73
94
  inputSchema: ListPackagesInput,
95
+ outputSchema: Schema.Struct({ packages: Schema.Array(PackageSchema) }),
74
96
  },
75
97
  get_package: {
76
98
  title: 'Get package detail',
@@ -80,6 +102,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
80
102
  Use after list_packages or when the user references a package directly.
81
103
  `,
82
104
  inputSchema: GetPackageInput,
105
+ outputSchema: Schema.Struct({ package: Schema.NullOr(PackageSchema) }),
83
106
  },
84
107
  list_symbols: {
85
108
  title: 'List all exported symbols of a package',
@@ -89,6 +112,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
89
112
  Returns lightweight rows with refs you can pass to get_symbol; capped at 30 — refine with \`kind\` or call get_symbol directly.
90
113
  `,
91
114
  inputSchema: ListSymbolsInput,
115
+ outputSchema: Schema.Struct({ symbols: Schema.Array(SymbolMatchSchema) }),
92
116
  },
93
117
  find_symbol: {
94
118
  title: 'Find an exported symbol by name',
@@ -98,6 +122,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
98
122
  Returns refs you can pass to get_symbol. Ranking: exact match, then prefix, then substring.
99
123
  `,
100
124
  inputSchema: FindSymbolInput,
125
+ outputSchema: Schema.Struct({ matches: Schema.Array(SymbolMatchSchema) }),
101
126
  },
102
127
  get_symbol: {
103
128
  title: 'Get symbol detail',
@@ -107,6 +132,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
107
132
  Pass include=["source"] to expand the full declaration text, include=["jsdoc"] for the full JSDoc body.
108
133
  `,
109
134
  inputSchema: GetSymbolInput,
135
+ outputSchema: Schema.Struct({ symbol: Schema.NullOr(SymbolDetailSchema) }),
110
136
  },
111
137
  list_plugins: {
112
138
  title: 'List Composer plugins',
@@ -116,6 +142,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
116
142
  Filter by \`id\` substring (e.g. "markdown") to narrow the list.
117
143
  `,
118
144
  inputSchema: ListPluginsInput,
145
+ outputSchema: Schema.Struct({ plugins: Schema.Array(PluginSchema) }),
119
146
  },
120
147
  list_surfaces: {
121
148
  title: 'List surfaces',
@@ -125,6 +152,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
125
152
  Filter by \`id\` (plugin id) to scope to a single plugin's surfaces.
126
153
  `,
127
154
  inputSchema: ListSurfacesInput,
155
+ outputSchema: Schema.Struct({ surfaces: Schema.Array(SurfaceSchema) }),
128
156
  },
129
157
  list_capabilities: {
130
158
  title: 'List capability contributions',
@@ -133,6 +161,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
133
161
  keys are produced (or required) by which plugins. Filter by \`id\` (plugin id) to scope to a single plugin.
134
162
  `,
135
163
  inputSchema: ListCapabilitiesInput,
164
+ outputSchema: Schema.Struct({ capabilities: Schema.Array(CapabilitySchema) }),
136
165
  },
137
166
  list_operations: {
138
167
  title: 'List operations',
@@ -144,6 +173,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
144
173
  to scope to a single plugin.
145
174
  `,
146
175
  inputSchema: ListOperationsInput,
176
+ outputSchema: Schema.Struct({ operations: Schema.Array(OperationSchema) }),
147
177
  },
148
178
  list_schemas: {
149
179
  title: 'List schemas',
@@ -153,6 +183,20 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
153
183
  Filter by \`id\` (plugin id, e.g. "org.dxos.plugin.markdown") to scope to a single plugin's schemas.
154
184
  `,
155
185
  inputSchema: ListSchemasInput,
186
+ outputSchema: Schema.Struct({ schemas: Schema.Array(SchemaSchema) }),
187
+ },
188
+ list_idioms: {
189
+ title: 'List idioms',
190
+ description: trim`
191
+ List idioms catalogued across the monorepo. An *idiom* is a JSDoc-tagged
192
+ reference example (\`@idiom <slug>\`) that pins the canonical way to use a
193
+ symbol — applicability, anti-pattern, and links to related idioms. Use this
194
+ to discover how a feature is meant to be used, or to find a worked example
195
+ before writing new code. Filter by \`slug\` substring or by \`hostKind\`
196
+ (\`symbol\`, \`story\`, \`test\`).
197
+ `,
198
+ inputSchema: ListIdiomsInput,
199
+ outputSchema: Schema.Struct({ idioms: Schema.Array(IdiomSchema) }),
156
200
  },
157
201
  };
158
202
 
@@ -0,0 +1,223 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // Effect Schema definitions for every introspect tool *result* (output) shape.
6
+ //
7
+ // These are the source of truth for the data returned by `@dxos/introspect`.
8
+ // `@dxos/introspect/src/types.ts` re-derives its TypeScript types from these
9
+ // schemas, and downstream consumers that can't depend on `@dxos/introspect`
10
+ // (browser/worker contexts — `@dxos/introspect` pulls Node-only `ts-morph`
11
+ // and `glob`) import the schemas directly.
12
+
13
+ import * as Schema from 'effect/Schema';
14
+
15
+ //
16
+ // Primitives
17
+ //
18
+
19
+ export const SymbolKindSchema = Schema.Literal(
20
+ 'function',
21
+ 'class',
22
+ 'interface',
23
+ 'type',
24
+ 'enum',
25
+ 'variable',
26
+ 'namespace',
27
+ 'unknown',
28
+ );
29
+ export type SymbolKind = typeof SymbolKindSchema.Type;
30
+
31
+ export const SymbolIncludeSchema = Schema.Literal('source', 'jsdoc');
32
+ export type SymbolInclude = typeof SymbolIncludeSchema.Type;
33
+
34
+ export const SourceLocationSchema = Schema.Struct({
35
+ file: Schema.String,
36
+ line: Schema.Number,
37
+ column: Schema.Number,
38
+ });
39
+ export type SourceLocation = typeof SourceLocationSchema.Type;
40
+
41
+ export const PluginIdSchema = Schema.String;
42
+ export type PluginId = typeof PluginIdSchema.Type;
43
+
44
+ //
45
+ // Packages
46
+ //
47
+
48
+ export const PackageSchema = Schema.Struct({
49
+ name: Schema.String,
50
+ version: Schema.String,
51
+ private: Schema.Boolean,
52
+ /** Path relative to the monorepo root (no trailing slash). */
53
+ path: Schema.String,
54
+ description: Schema.optional(Schema.String),
55
+ });
56
+ export type Package = typeof PackageSchema.Type;
57
+
58
+ export const PackageDetailSchema = Schema.Struct({
59
+ ...PackageSchema.fields,
60
+ /** Workspace dependencies (other packages in the monorepo). */
61
+ workspaceDependencies: Schema.Array(Schema.String),
62
+ /** External (catalog or pinned) dependency names. */
63
+ externalDependencies: Schema.Array(Schema.String),
64
+ /** Resolved entry points (relative to package root). */
65
+ entryPoints: Schema.Array(Schema.String),
66
+ /** Number of exported symbols at the top level. */
67
+ exportCount: Schema.Number,
68
+ });
69
+ export type PackageDetail = typeof PackageDetailSchema.Type;
70
+
71
+ //
72
+ // Symbols
73
+ //
74
+
75
+ export const SymbolMatchSchema = Schema.Struct({
76
+ ref: Schema.String,
77
+ package: Schema.String,
78
+ name: Schema.String,
79
+ kind: SymbolKindSchema,
80
+ /** One-line summary from JSDoc, if any. */
81
+ summary: Schema.optional(Schema.String),
82
+ });
83
+ export type SymbolMatch = typeof SymbolMatchSchema.Type;
84
+
85
+ export const SymbolDetailSchema = Schema.Struct({
86
+ ref: Schema.String,
87
+ package: Schema.String,
88
+ name: Schema.String,
89
+ kind: SymbolKindSchema,
90
+ signature: Schema.String,
91
+ jsdoc: Schema.optional(Schema.String),
92
+ summary: Schema.optional(Schema.String),
93
+ location: SourceLocationSchema,
94
+ /** Source text — only present when `include` requested it. */
95
+ source: Schema.optional(Schema.String),
96
+ });
97
+ export type SymbolDetail = typeof SymbolDetailSchema.Type;
98
+
99
+ //
100
+ // Plugins / surfaces / capabilities / operations / schemas
101
+ //
102
+
103
+ export const PluginSchema = Schema.Struct({
104
+ /** e.g. `org.dxos.plugin.code`. */
105
+ id: PluginIdSchema,
106
+ /** npm package name, e.g. `@dxos/plugin-code`. */
107
+ package: Schema.String,
108
+ name: Schema.optional(Schema.String),
109
+ description: Schema.optional(Schema.String),
110
+ icon: Schema.optional(Schema.String),
111
+ iconHue: Schema.optional(Schema.String),
112
+ /** Static tags read from `meta.tags` (e.g. `['labs']`). Empty array if absent. */
113
+ tags: Schema.Array(Schema.String),
114
+ /**
115
+ * Ids of other plugins this plugin depends on, derived from its package's
116
+ * `workspace:*` dependencies. Sorted for deterministic output. Empty array
117
+ * if the plugin's package has no dependencies on other plugin packages.
118
+ */
119
+ dependsOn: Schema.Array(PluginIdSchema),
120
+ /** Source location of the `meta` declaration. */
121
+ metaLocation: SourceLocationSchema,
122
+ });
123
+ export type Plugin = typeof PluginSchema.Type;
124
+
125
+ export const SurfaceSchema = Schema.Struct({
126
+ pluginId: PluginIdSchema,
127
+ /** Surface id passed to `Surface.create({ id })`. */
128
+ id: Schema.String,
129
+ /** One or more roles the surface answers to. */
130
+ role: Schema.Array(Schema.String),
131
+ location: SourceLocationSchema,
132
+ });
133
+ export type Surface = typeof SurfaceSchema.Type;
134
+
135
+ export const CapabilitySchema = Schema.Struct({
136
+ pluginId: PluginIdSchema,
137
+ /** Identifier expression as written in source, e.g. `Capabilities.ReactSurface`. */
138
+ type: Schema.String,
139
+ location: SourceLocationSchema,
140
+ });
141
+ export type Capability = typeof CapabilitySchema.Type;
142
+
143
+ export const OperationSchema = Schema.Struct({
144
+ pluginId: PluginIdSchema,
145
+ /** Operation identifier expression. */
146
+ type: Schema.String,
147
+ location: SourceLocationSchema,
148
+ });
149
+ export type Operation = typeof OperationSchema.Type;
150
+
151
+ export const SchemaSchema = Schema.Struct({
152
+ pluginId: PluginIdSchema,
153
+ /** Identifier expression as written in `addSchemaModule`, e.g. `CodeProject.CodeProject`. */
154
+ name: Schema.String,
155
+ /** Resolved typename (e.g. `org.dxos.type.codeProject`) when statically extractable. */
156
+ typename: Schema.optional(Schema.String),
157
+ location: SourceLocationSchema,
158
+ });
159
+ export type SchemaContribution = typeof SchemaSchema.Type;
160
+
161
+ export const PluginDetailSchema = Schema.Struct({
162
+ ...PluginSchema.fields,
163
+ surfaces: Schema.Array(SurfaceSchema),
164
+ capabilities: Schema.Array(CapabilitySchema),
165
+ operations: Schema.Array(OperationSchema),
166
+ schemas: Schema.Array(SchemaSchema),
167
+ });
168
+ export type PluginDetail = typeof PluginDetailSchema.Type;
169
+
170
+ //
171
+ // Idioms
172
+ //
173
+
174
+ export const IdiomHostKindSchema = Schema.Literal('story', 'test', 'symbol');
175
+ export type IdiomHostKind = typeof IdiomHostKindSchema.Type;
176
+
177
+ export const IdiomHostSchema = Schema.Struct({
178
+ /** Path relative to the scan root. */
179
+ file: Schema.String,
180
+ /** 1-indexed line where the JSDoc opens. */
181
+ line: Schema.Number,
182
+ /** Best-effort name of the export immediately following the JSDoc. */
183
+ symbol: Schema.optional(Schema.String),
184
+ /** Detected host kind based on file location and symbol shape. */
185
+ kind: IdiomHostKindSchema,
186
+ });
187
+ export type IdiomHost = typeof IdiomHostSchema.Type;
188
+
189
+ export const IdiomSchema = Schema.Struct({
190
+ /** Globally unique AT Protocol NSID (https://atproto.com/specs/nsid). */
191
+ slug: Schema.String,
192
+ /** Leading JSDoc paragraph (rationale). */
193
+ summary: Schema.optional(Schema.String),
194
+ /** Applicability (required field per IDIOMS.md). */
195
+ applies: Schema.String,
196
+ /** Anti-pattern this replaces. */
197
+ insteadOf: Schema.optional(Schema.String),
198
+ /** Raw {@link …} targets named under `uses:`. */
199
+ uses: Schema.Array(Schema.String),
200
+ /** Slugs of related idioms. */
201
+ related: Schema.Array(Schema.String),
202
+ host: IdiomHostSchema,
203
+ });
204
+ export type Idiom = typeof IdiomSchema.Type;
205
+
206
+ //
207
+ // Sidecar file format
208
+ //
209
+
210
+ /**
211
+ * Shape of the `plugins.json` sidecar stored in R2 / written by the cache
212
+ * upload script. Uses plain mutable arrays so callers can work with standard
213
+ * JSON.parse output without readonly friction.
214
+ */
215
+ export type PluginsFile = {
216
+ version: 1;
217
+ plugins: Plugin[];
218
+ surfaces: Surface[];
219
+ capabilities: Capability[];
220
+ operations: Operation[];
221
+ schemas: SchemaContribution[];
222
+ idioms?: Idiom[];
223
+ };
package/src/schemas.ts CHANGED
@@ -13,11 +13,29 @@
13
13
  // - Required fields: `.annotations({ description })` on the primitive itself.
14
14
 
15
15
  import * as Schema from 'effect/Schema';
16
+ import * as SchemaAST from 'effect/SchemaAST';
16
17
 
17
18
  import { trim } from '@dxos/util';
18
19
 
19
20
  import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './limits';
20
21
 
22
+ /**
23
+ * Annotation key for fields whose value should be picked from a known
24
+ * enumeration that the MCP server can produce on demand. Consumers
25
+ * (e.g. `@dxos/react-ui-introspect`'s ToolForm) read this annotation off
26
+ * the field's AST and render a Combobox over the matching list.
27
+ *
28
+ * The kind names a domain rather than a specific tool — e.g. `plugin-id`
29
+ * means "any tool that emits plugin ids works" — so adding a new tool
30
+ * doesn't require new picker plumbing.
31
+ */
32
+ export const PickerAnnotationId = '@dxos/introspect-tools/picker';
33
+
34
+ export type PickerKind = 'plugin-id' | 'package-name';
35
+
36
+ export const getPicker = (ast: SchemaAST.AST): PickerKind | undefined =>
37
+ (ast.annotations as Record<string, unknown>)[PickerAnnotationId] as PickerKind | undefined;
38
+
21
39
  /**
22
40
  * Pagination + projection options shared by every list-style tool. Spread its
23
41
  * `.fields` into a tool's `Schema.Struct({...})` so the same pair of knobs
@@ -32,7 +50,7 @@ export const ListOptionsInput = Schema.Struct({
32
50
  ).annotations({
33
51
  title: 'Limit',
34
52
  description: trim`
35
- Maximum number of items to return. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.
53
+ Maximum number of items. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.
36
54
  `,
37
55
  }),
38
56
  compact: Schema.optional(Schema.Boolean).annotations({
@@ -56,10 +74,10 @@ export const ListPackagesInput = Schema.Struct({
56
74
  name: Schema.optional(Schema.String).annotations({
57
75
  title: 'Name filter',
58
76
  description: 'Substring of the package name (case-insensitive).',
77
+ [PickerAnnotationId]: 'package-name' satisfies PickerKind,
59
78
  }),
60
79
  pathPrefix: Schema.optional(Schema.String).annotations({
61
80
  title: 'Path prefix',
62
- description: 'Restrict to packages whose path starts with this segment, e.g. "packages/plugins".',
63
81
  }),
64
82
  privateOnly: Schema.optional(Schema.Boolean).annotations({
65
83
  title: 'Private only',
@@ -72,6 +90,7 @@ export const GetPackageInput = Schema.Struct({
72
90
  name: Schema.String.annotations({
73
91
  title: 'Package name',
74
92
  description: 'Exact package name, e.g. "@dxos/echo".',
93
+ [PickerAnnotationId]: 'package-name' satisfies PickerKind,
75
94
  }),
76
95
  });
77
96
 
@@ -83,6 +102,7 @@ export const ListSymbolsInput = Schema.Struct({
83
102
  package: Schema.String.annotations({
84
103
  title: 'Package',
85
104
  description: 'Exact package name, e.g. "@dxos/ai".',
105
+ [PickerAnnotationId]: 'package-name' satisfies PickerKind,
86
106
  }),
87
107
  kind: Schema.optional(SymbolKindEnum).annotations({
88
108
  title: 'Kind',
@@ -123,6 +143,9 @@ export const GetSymbolInput = Schema.Struct({
123
143
  //
124
144
 
125
145
  export const ListPluginsInput = Schema.Struct({
146
+ // No picker annotation — this is a free-form substring filter, not an
147
+ // exact-match selector. Picking from the list of known plugin ids would
148
+ // defeat the purpose of `list_plugins`.
126
149
  id: Schema.optional(Schema.String).annotations({
127
150
  title: 'Plugin id',
128
151
  description: 'Substring of the plugin id (case-insensitive). Omit to list every plugin.',
@@ -133,7 +156,7 @@ export const ListPluginsInput = Schema.Struct({
133
156
  const PluginIdFilter = Schema.Struct({
134
157
  id: Schema.optional(Schema.String).annotations({
135
158
  title: 'Plugin id',
136
- description: 'Restrict to contributions from this plugin id (e.g. "org.dxos.plugin.markdown").',
159
+ [PickerAnnotationId]: 'plugin-id' satisfies PickerKind,
137
160
  }),
138
161
  ...ListOptionsInput.fields,
139
162
  });
@@ -143,6 +166,24 @@ export const ListCapabilitiesInput = PluginIdFilter;
143
166
  export const ListOperationsInput = PluginIdFilter;
144
167
  export const ListSchemasInput = PluginIdFilter;
145
168
 
169
+ //
170
+ // Idioms
171
+ //
172
+
173
+ const IdiomHostKindEnum = Schema.Literal('story', 'test', 'symbol');
174
+
175
+ export const ListIdiomsInput = Schema.Struct({
176
+ slug: Schema.optional(Schema.String).annotations({
177
+ title: 'Slug filter',
178
+ description: 'Substring of the idiom slug (case-insensitive). Omit to list every idiom.',
179
+ }),
180
+ hostKind: Schema.optional(IdiomHostKindEnum).annotations({
181
+ title: 'Host kind',
182
+ description: 'Filter idioms by their host site: `symbol` (production code), `story`, or `test`.',
183
+ }),
184
+ ...ListOptionsInput.fields,
185
+ });
186
+
146
187
  //
147
188
  // Inferred TypeScript types — handy for downstream consumers.
148
189
  //
@@ -157,3 +198,4 @@ export type ListSurfacesArgs = typeof ListSurfacesInput.Type;
157
198
  export type ListCapabilitiesArgs = typeof ListCapabilitiesInput.Type;
158
199
  export type ListOperationsArgs = typeof ListOperationsInput.Type;
159
200
  export type ListSchemasArgs = typeof ListSchemasInput.Type;
201
+ export type ListIdiomsArgs = typeof ListIdiomsInput.Type;