@yaag/runtime 0.14.1 → 0.15.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": "@yaag/runtime",
3
- "version": "0.14.1",
3
+ "version": "0.15.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -4,8 +4,9 @@
4
4
  */
5
5
 
6
6
  /**
7
- * One registered Agent Definition — the only kind a registry file names
8
- * (ADR-0046, the registration exception to ADR-0019).
7
+ * One registered Agent Definition (ADR-0046, the registration exception to
8
+ * ADR-0019). A registry file also registers Orchestration Programs — see
9
+ * `ProgramEntry` (ADR-0050).
9
10
  *
10
11
  * `file` resolves relative to the directory of the declaring registry file,
11
12
  * never to the current working directory. Only `name` is verifiable against
@@ -19,13 +20,30 @@ export interface AgentDefinitionEntry {
19
20
  readonly tags?: readonly string[];
20
21
  }
21
22
 
23
+ /**
24
+ * One registered Orchestration Program (ADR-0050). There is no `exportName`: a
25
+ * program is always the default export that `defineRun(...)` makes. Listing
26
+ * imports no module, thus the entry must declare `name`.
27
+ *
28
+ * `file` resolves relative to the directory of the declaring registry file,
29
+ * never to the current working directory.
30
+ */
31
+ export interface ProgramEntry {
32
+ readonly file: string;
33
+ readonly name: string;
34
+ readonly description?: string;
35
+ readonly tags?: readonly string[];
36
+ }
37
+
22
38
  /**
23
39
  * The document one `registry.json` holds. The schema is lenient on purpose: an
24
40
  * unknown key is preserved by the file and ignored by the parser, so an older
25
- * yaag still reads a newer registry file.
41
+ * yaag still reads a newer registry file. The `programs` section is discovery
42
+ * only: it makes a program listable, it does not change how it runs.
26
43
  */
27
44
  export interface RegistryDocument {
28
45
  readonly agents?: readonly AgentDefinitionEntry[];
46
+ readonly programs?: readonly ProgramEntry[];
29
47
  }
30
48
 
31
49
  /** Which layer a Catalog row came from. A `dir` query never matches `global`. */
@@ -34,6 +52,9 @@ export type CatalogLayer = "global" | "project";
34
52
  /** Where a Catalog row came from, for disambiguating duplicate names. */
35
53
  export interface CatalogSource {
36
54
  readonly layer: CatalogLayer;
37
- /** The declaring registry file (agents) or the Program Directory (programs). */
55
+ /**
56
+ * The declaring registry file for every registered row — an agent and a
57
+ * registered program — or the Program Directory for a scanned program row.
58
+ */
38
59
  readonly origin: string;
39
60
  }
@@ -5,14 +5,16 @@ import { parseRegistryFile } from "./registry-schema.ts";
5
5
  const BROKEN_REGISTRY_FILE = "/repo/other/.yaag/registry.json";
6
6
 
7
7
  /**
8
- * The five contract cases. The order here is the order the cases were written,
8
+ * The six contract cases. The order here is the order the cases were written,
9
9
  * not the order a reader produces: `CatalogResult` states the global layer
10
10
  * first, then the Program Directories in sorted order.
11
11
  *
12
12
  * A scanned program row carries no `description`: a program states its
13
13
  * description inside `defineRun(...)`, and ADR-0046 forbids the import at list
14
- * time. An agent row with a path states the stat the reader ran, so
15
- * `fileMissing: false` means "checked and present", not "not checked".
14
+ * time. A registered program row carries the curated `description` and `tags`
15
+ * its Registry File entry states, and no `exportName` at all. An agent row
16
+ * with a path states the stat the reader ran, so `fileMissing: false` means
17
+ * "checked and present", not "not checked".
16
18
  */
17
19
  const ROWS: readonly CatalogRow[] = [
18
20
  {
@@ -57,21 +59,33 @@ const ROWS: readonly CatalogRow[] = [
57
59
  diagnostics: [
58
60
  {
59
61
  scope: "entry",
62
+ section: "agents",
60
63
  index: 2,
61
64
  message: '$: must have required property "name"',
62
65
  },
63
66
  ],
64
67
  },
68
+ {
69
+ kind: "program",
70
+ registered: true,
71
+ name: "research",
72
+ description: "Runs a multi-model research panel",
73
+ tags: ["research", "panel"],
74
+ path: "/home/u/.config/yaag/programs/research.ts",
75
+ source: { layer: "global", origin: "/home/u/.config/yaag/registry.json" },
76
+ fileMissing: false,
77
+ },
65
78
  ];
66
79
 
67
80
  /**
68
81
  * The in-memory Catalog every consumer test asserts against. Construction is
69
82
  * pure and the result is deep-frozen, so a consumer cannot change the contract
70
- * by accident. It holds five rows — a healthy program with no description, a
71
- * healthy agent, an
72
- * agent whose file is missing, a duplicate name across layers, and an entry
73
- * that carries a diagnostic but is still listed — plus one file-scoped
74
- * diagnostic whose message form is what `parseRegistryFile` emits.
83
+ * by accident. It holds six rows — a healthy scanned program with no
84
+ * description, a healthy agent, an agent whose file is missing, a duplicate
85
+ * name across layers, an entry that carries a diagnostic but is still listed,
86
+ * and a globally registered program with a curated description and tags and
87
+ * no `exportName` — plus one file-scoped diagnostic whose message form is
88
+ * what `parseRegistryFile` emits.
75
89
  */
76
90
  export const CATALOG_FIXTURE: CatalogResult = deepFreeze({
77
91
  rows: ROWS,
@@ -6,7 +6,9 @@ import type { CatalogQuery, CatalogRow } from "./catalog-result.ts";
6
6
  * Matches one row against a substring or glob pattern — never a regex. An
7
7
  * absent, empty, or whitespace-only pattern matches everything. The haystack
8
8
  * fields are tested independently: `name`, `description`, each tag, `path`,
9
- * and `exportName`. Matching is case-insensitive.
9
+ * and `exportName`. A field that the row does not carry is skipped, thus a
10
+ * registered program row, which has no `exportName`, is tested on its name,
11
+ * its description, its tags and its path. Matching is case-insensitive.
10
12
  *
11
13
  * A pattern that contains `*` or `?` is a glob anchored per field (`*` is any
12
14
  * run including empty, `?` is exactly one character). Every other character is
@@ -37,9 +39,12 @@ export function filterCatalog(
37
39
  }
38
40
 
39
41
  /**
40
- * A `dir` query names one Program Directory. It matches a program by its
41
- * origin and an agent by the Program Directory that owns the declaring
42
- * registry file. It never matches a global row.
42
+ * A `dir` query names one Program Directory. A row matches when the Program
43
+ * Directory of its origin is that directory: a scanned program states the
44
+ * directory directly, and a registered row — an agent or a program that
45
+ * `<dir>/.yaag/registry.json` registers — states the registry file, from which
46
+ * the `/.yaag/` segment is stripped. A global row never matches a `dir`,
47
+ * whatever its origin.
43
48
  */
44
49
  function matchesDirectory(row: CatalogRow, dir: string | undefined): boolean {
45
50
  if (dir === undefined || dir === "") return true;
@@ -1,6 +1,10 @@
1
1
  import type { CatalogSource } from "./catalog-entry.ts";
2
2
 
3
- /** What a Catalog row describes: a scanned program, or a registered Definition. */
3
+ /**
4
+ * What a Catalog row describes. `program` covers a scanned program and a
5
+ * program that a registry file registers; `agent` is a registered Agent
6
+ * Definition.
7
+ */
4
8
  export type CatalogKind = "program" | "agent";
5
9
 
6
10
  /**
@@ -10,8 +14,16 @@ export type CatalogKind = "program" | "agent";
10
14
  export interface CatalogDiagnostic {
11
15
  /** `file` = the whole registry file is unusable; `entry` = one entry, still listed. */
12
16
  readonly scope: "file" | "entry";
13
- /** Index within the file's `agents` array, when the diagnostic is entry-scoped. */
17
+ /**
18
+ * Index within the entry's own section (`agents` or `programs`), when the
19
+ * diagnostic is entry-scoped. Read `section` to know which array it indexes.
20
+ */
14
21
  readonly index?: number;
22
+ /**
23
+ * Which registry file section an entry-scoped diagnostic came from. Absent on
24
+ * a file-scoped diagnostic and on a diagnostic that an older producer made.
25
+ */
26
+ readonly section?: "agents" | "programs";
15
27
  /**
16
28
  * The registry file the problem came from. A file-scoped diagnostic produces
17
29
  * no row, so this field is the only thing that names its file; absent means
@@ -35,8 +47,17 @@ export interface CatalogRow {
35
47
  readonly name: string;
36
48
  readonly description?: string;
37
49
  readonly tags?: readonly string[];
38
- /** The program file path, or the Definition's resolved `file`. */
50
+ /**
51
+ * The scanned program's file path, or the resolved `file` of a registry entry
52
+ * (an agent or a registered program). It is `""` when the entry declares no
53
+ * file.
54
+ */
39
55
  readonly path: string;
56
+ /**
57
+ * Set only on a program row that a registry file entry made. It is absent on
58
+ * a scanned program row and on every agent row, which is registered already.
59
+ */
60
+ readonly registered?: true;
40
61
  /** Agents only: the module export the Definition is read from. */
41
62
  readonly exportName?: string;
42
63
  readonly source: CatalogSource;
@@ -35,6 +35,7 @@ export type {
35
35
  AgentDefinitionEntry,
36
36
  CatalogLayer,
37
37
  CatalogSource,
38
+ ProgramEntry,
38
39
  RegistryDocument,
39
40
  } from "./catalog-entry.ts";
40
41
  export { CATALOG_FIXTURE } from "./catalog-fixture.ts";
@@ -10,7 +10,9 @@ import type { CatalogResult, CatalogRow } from "./catalog-result.ts";
10
10
  *
11
11
  * A scanned row carries no `description`: a program's description lives inside
12
12
  * `defineRun(...)`, and reading it needs an import, which ADR-0046 forbids at
13
- * list time. `yaag_describe` owns that path.
13
+ * list time. `yaag_describe` owns that path. A registered program row is
14
+ * different: its `description` and `tags` come from the registry file entry, so
15
+ * they are curated text and no import reads them.
14
16
  *
15
17
  * Never throws: an unreadable or absent directory becomes one file-scoped
16
18
  * diagnostic and zero rows.
@@ -1,6 +1,6 @@
1
1
  import { readFile, stat } from "node:fs/promises";
2
2
  import { dirname, resolve } from "node:path";
3
- import type { AgentDefinitionEntry, CatalogLayer } from "./catalog-entry.ts";
3
+ import type { AgentDefinitionEntry, CatalogLayer, ProgramEntry } from "./catalog-entry.ts";
4
4
  import type { CatalogDiagnostic, CatalogResult, CatalogRow } from "./catalog-result.ts";
5
5
  import { parseRegistryFile } from "./registry-schema.ts";
6
6
 
@@ -18,8 +18,21 @@ const EMPTY: CatalogResult = { rows: [], diagnostics: [] };
18
18
  * becomes a diagnostic. This deviates from `readConfigLayer`, which throws on
19
19
  * `EACCES`, on purpose: the Catalog flags, it never fails (ADR-0046).
20
20
  *
21
- * The `fileMissing` flag is a `stat` only. This function imports no
22
- * Orchestration Program module and reads no target file.
21
+ * For one registry file the reader emits every `agents` row first, then every
22
+ * `programs` row, each in file order. Rows are never sorted here.
23
+ *
24
+ * Entry diagnostics are bucketed per section. A `programs` diagnostic never
25
+ * attaches to an `agents` row, because `index` counts inside its own section.
26
+ *
27
+ * The `fileMissing` flag is a `stat` only, for an agent row and for a
28
+ * registered program row. Thus a registered program whose target file was
29
+ * deleted is flagged. This is intended.
30
+ *
31
+ * This function imports no Orchestration Program module and reads no target
32
+ * file. Two guards keep that honest: `registry-reader.test.ts` writes a module
33
+ * with a top-level side effect and asserts the marker file was never created,
34
+ * and `apps/yaag/src/program/runtime-alias.test.ts` guards the
35
+ * program-visible surface.
23
36
  */
24
37
  export async function readRegistryLayer(request: RegistryLayerRequest): Promise<CatalogResult> {
25
38
  let text: string;
@@ -41,39 +54,60 @@ export async function readRegistryLayer(request: RegistryLayerRequest): Promise<
41
54
 
42
55
  const parsed = parseRegistryFile(text, request.path);
43
56
  const fileScoped: CatalogDiagnostic[] = [];
44
- const entryScoped = new Map<number, CatalogDiagnostic[]>();
57
+ const buckets = new Map<string, CatalogDiagnostic[]>();
45
58
  for (const diagnostic of parsed.diagnostics) {
46
59
  if (diagnostic.scope === "file" || diagnostic.index === undefined) {
47
60
  fileScoped.push(diagnostic);
48
61
  continue;
49
62
  }
50
- const bucket = entryScoped.get(diagnostic.index) ?? [];
63
+ // A diagnostic without `section` can only come from an older producer of
64
+ // `ParsedRegistryFile`, when `agents` was the only section. Never drop it.
65
+ const key = bucketKey(diagnostic.section ?? "agents", diagnostic.index);
66
+ const bucket = buckets.get(key) ?? [];
51
67
  bucket.push(diagnostic);
52
- entryScoped.set(diagnostic.index, bucket);
68
+ buckets.set(key, bucket);
53
69
  }
54
70
 
55
71
  const base = dirname(resolve(request.path));
56
- const rows = parsed.entries.map((entry, index) =>
57
- toRow(entry, base, request, entryScoped.get(index)),
72
+ const agentRows = parsed.entries.map((entry, index) =>
73
+ toAgentRow({ entry, base, request, diagnostics: buckets.get(bucketKey("agents", index)) }),
58
74
  );
75
+ const programRows = parsed.programs.map((entry, index) =>
76
+ toProgramRow({ entry, base, request, diagnostics: buckets.get(bucketKey("programs", index)) }),
77
+ );
78
+ const rows = [...agentRows, ...programRows];
59
79
  return { rows: await Promise.all(rows.map(withFileMissing)), diagnostics: fileScoped };
60
80
  }
61
81
 
82
+ type EntrySection = "agents" | "programs";
83
+
84
+ /** Keys an entry diagnostic bucket, so an index counts inside its section. */
85
+ function bucketKey(section: EntrySection, index: number): string {
86
+ return `${section}:${index}`;
87
+ }
88
+
89
+ /** One row to build. An options object keeps the positional parameters few. */
90
+ interface RowRequest<Entry> {
91
+ readonly entry: Entry;
92
+ readonly base: string;
93
+ readonly request: RegistryLayerRequest;
94
+ readonly diagnostics: readonly CatalogDiagnostic[] | undefined;
95
+ }
96
+
62
97
  /**
63
- * Builds one row. A relative `file` resolves against the declaring registry
64
- * file's directory, never the current working directory; an entry that lost
65
- * its `file` keeps an empty path and is never checked on disk.
98
+ * The fields an agent row and a registered program row share. A relative
99
+ * `file` resolves against the declaring registry file's directory, never the
100
+ * current working directory; an entry that lost its `file` keeps an empty path
101
+ * and is never checked on disk.
66
102
  */
67
- function toRow(
68
- entry: AgentDefinitionEntry,
69
- base: string,
70
- request: RegistryLayerRequest,
71
- diagnostics: readonly CatalogDiagnostic[] | undefined,
72
- ): CatalogRow {
103
+ function commonFields({
104
+ entry,
105
+ base,
106
+ request,
107
+ diagnostics,
108
+ }: RowRequest<ProgramEntry>): Omit<CatalogRow, "kind"> {
73
109
  return {
74
- kind: "agent",
75
110
  name: entry.name,
76
- exportName: entry.exportName,
77
111
  path: entry.file === "" ? "" : resolve(base, entry.file),
78
112
  ...(entry.description === undefined ? {} : { description: entry.description }),
79
113
  ...(entry.tags === undefined ? {} : { tags: entry.tags }),
@@ -82,6 +116,25 @@ function toRow(
82
116
  };
83
117
  }
84
118
 
119
+ /** Builds one registered Agent Definition row. */
120
+ function toAgentRow(row: RowRequest<AgentDefinitionEntry>): CatalogRow {
121
+ const { name, ...rest } = commonFields(row);
122
+ return { kind: "agent", name, exportName: row.entry.exportName, ...rest };
123
+ }
124
+
125
+ /**
126
+ * Builds one registered Orchestration Program row. There is no `exportName`
127
+ * key at all, not an empty one: the matcher must not test it and the renderers
128
+ * must print no `export=`.
129
+ */
130
+ function toProgramRow(row: RowRequest<ProgramEntry>): CatalogRow {
131
+ return { kind: "program", registered: true, ...commonFields(row) };
132
+ }
133
+
134
+ /**
135
+ * Adds the `fileMissing` flag from a single `stat`. A row with an empty path
136
+ * is returned unchanged: no stat is run and no `fileMissing` key appears.
137
+ */
85
138
  async function withFileMissing(row: CatalogRow): Promise<CatalogRow> {
86
139
  if (row.path === "") return row;
87
140
  return { ...row, fileMissing: !(await isFile(row.path)) };
@@ -1,7 +1,7 @@
1
- import { Type } from "typebox";
1
+ import { type TSchema, Type } from "typebox";
2
2
  import { Value } from "typebox/value";
3
3
  import { formatValidationErrors } from "../validation-errors.ts";
4
- import type { AgentDefinitionEntry, RegistryDocument } from "./catalog-entry.ts";
4
+ import type { AgentDefinitionEntry, ProgramEntry, RegistryDocument } from "./catalog-entry.ts";
5
5
  import type { CatalogDiagnostic } from "./catalog-result.ts";
6
6
 
7
7
  /**
@@ -21,13 +21,25 @@ const AGENT_ENTRY_SCHEMA = Type.Object({
21
21
  tags: Type.Optional(Type.Array(Type.String())),
22
22
  });
23
23
 
24
- /** The outcome of parsing one registry file: entries plus every problem found. */
24
+ const PROGRAM_ENTRY_SCHEMA = Type.Object({
25
+ file: Type.String(),
26
+ name: Type.String(),
27
+ description: Type.Optional(Type.String()),
28
+ tags: Type.Optional(Type.Array(Type.String())),
29
+ });
30
+
31
+ /**
32
+ * The outcome of parsing one registry file: the agent entries, the program
33
+ * entries, plus every problem found. `entries` holds agent entries only, and
34
+ * `programs` is an empty array when the file declares none — never `undefined`.
35
+ */
25
36
  export interface ParsedRegistryFile {
26
37
  readonly entries: readonly AgentDefinitionEntry[];
38
+ readonly programs: readonly ProgramEntry[];
27
39
  readonly diagnostics: readonly CatalogDiagnostic[];
28
40
  }
29
41
 
30
- const EMPTY: ParsedRegistryFile = { entries: [], diagnostics: [] };
42
+ const EMPTY: ParsedRegistryFile = { entries: [], programs: [], diagnostics: [] };
31
43
 
32
44
  /**
33
45
  * Parses one registry file's JSON text. Never throws: invalid JSON becomes one
@@ -41,7 +53,11 @@ export function parseRegistryFile(text: string, path?: string): ParsedRegistryFi
41
53
  value = JSON.parse(text);
42
54
  } catch (cause) {
43
55
  const message = cause instanceof Error ? cause.message : String(cause);
44
- return { entries: [], diagnostics: [fileIssue(`is not valid JSON: ${message}`, path)] };
56
+ return {
57
+ entries: [],
58
+ programs: [],
59
+ diagnostics: [fileIssue(`is not valid JSON: ${message}`, path)],
60
+ };
45
61
  }
46
62
  return readRegistryDocument(value, path);
47
63
  }
@@ -49,36 +65,83 @@ export function parseRegistryFile(text: string, path?: string): ParsedRegistryFi
49
65
  /**
50
66
  * Reads an already-parsed registry document. Never throws: a wrong root shape
51
67
  * is a file-scoped diagnostic naming `path`, and a malformed entry is kept
52
- * with an entry-scoped diagnostic carrying its index.
68
+ * with an entry-scoped diagnostic carrying its index. It parses `agents` and
69
+ * `programs` independently — a broken section never discards the other — and
70
+ * stamps every entry-scoped diagnostic with its section and its index within
71
+ * that section.
53
72
  */
54
73
  export function readRegistryDocument(value: unknown, path?: string): ParsedRegistryFile {
55
74
  const document = asRegistryDocument(value);
56
75
  if (document === undefined) {
57
- return { entries: [], diagnostics: [fileIssue("must contain a JSON object", path)] };
58
- }
59
- const agents = document.agents;
60
- if (agents === undefined) return EMPTY;
61
- if (!Array.isArray(agents)) {
62
- return { entries: [], diagnostics: [fileIssue('"agents" must be an array', path)] };
76
+ return {
77
+ entries: [],
78
+ programs: [],
79
+ diagnostics: [fileIssue("must contain a JSON object", path)],
80
+ };
63
81
  }
82
+ if (document.agents === undefined && document.programs === undefined) return EMPTY;
64
83
 
65
- const entries: AgentDefinitionEntry[] = [];
84
+ const agents = parseSection<AgentDefinitionEntry>({
85
+ raw: document.agents,
86
+ section: "agents",
87
+ schema: AGENT_ENTRY_SCHEMA,
88
+ build: toAgentEntry,
89
+ path,
90
+ });
91
+ const programs = parseSection<ProgramEntry>({
92
+ raw: document.programs,
93
+ section: "programs",
94
+ schema: PROGRAM_ENTRY_SCHEMA,
95
+ build: toProgramEntry,
96
+ path,
97
+ });
98
+ return {
99
+ entries: agents.items,
100
+ programs: programs.items,
101
+ diagnostics: [...agents.diagnostics, ...programs.diagnostics],
102
+ };
103
+ }
104
+
105
+ /** What `parseSection` needs to read one registry file section. */
106
+ interface SectionRequest<T> {
107
+ readonly raw: unknown;
108
+ readonly section: "agents" | "programs";
109
+ readonly schema: TSchema;
110
+ readonly build: (element: unknown) => T;
111
+ readonly path: string | undefined;
112
+ }
113
+
114
+ /**
115
+ * Reads one section. An absent section gives no entry and no diagnostic; a
116
+ * section that is not an array gives one file-scoped diagnostic and no entry,
117
+ * and it never touches the other section.
118
+ */
119
+ function parseSection<T>(request: SectionRequest<T>): {
120
+ items: T[];
121
+ diagnostics: CatalogDiagnostic[];
122
+ } {
123
+ const { raw, section, schema, build, path } = request;
124
+ if (raw === undefined) return { items: [], diagnostics: [] };
125
+ if (!Array.isArray(raw)) {
126
+ return { items: [], diagnostics: [fileIssue(`"${section}" must be an array`, path)] };
127
+ }
128
+ const items: T[] = [];
66
129
  const diagnostics: CatalogDiagnostic[] = [];
67
- agents.forEach((element, index) => {
68
- const errors = formatValidationErrors(element, Value.Errors(AGENT_ENTRY_SCHEMA, element));
130
+ raw.forEach((element, index) => {
131
+ const errors = formatValidationErrors(element, Value.Errors(schema, element));
69
132
  if (errors.length > 0) {
70
- diagnostics.push({ scope: "entry", index, message: errors.join("; ") });
133
+ diagnostics.push({ scope: "entry", section, index, message: errors.join("; ") });
71
134
  }
72
- entries.push(toEntry(element));
135
+ items.push(build(element));
73
136
  });
74
- return { entries, diagnostics };
137
+ return { items, diagnostics };
75
138
  }
76
139
 
77
140
  /**
78
141
  * Narrows a parsed JSON root to a registry document. An array, a scalar, and
79
- * `null` are all rejected: only a JSON object can hold `agents`. The `agents`
80
- * field itself stays unchecked here, because the caller reports a wrong one as
81
- * its own diagnostic.
142
+ * `null` are all rejected: only a JSON object can hold the `agents` and
143
+ * `programs` sections. The two fields themselves stay unchecked here, because
144
+ * the caller reports a wrong one as its own diagnostic, one section at a time.
82
145
  */
83
146
  function asRegistryDocument(value: unknown): RegistryDocument | undefined {
84
147
  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
@@ -86,26 +149,46 @@ function asRegistryDocument(value: unknown): RegistryDocument | undefined {
86
149
  }
87
150
 
88
151
  /**
89
- * Builds an entry from a possibly malformed element. A missing or non-string
90
- * field becomes `""` so the entry still produces a row: the Catalog flags a
91
- * problem, it never drops the entry.
152
+ * Builds an agent entry from a possibly malformed element. A missing or
153
+ * non-string field becomes `""` so the entry still produces a row: the Catalog
154
+ * flags a problem, it never drops the entry.
92
155
  */
93
- function toEntry(element: unknown): AgentDefinitionEntry {
94
- const record = (typeof element === "object" && element !== null ? element : {}) as Record<
95
- string,
96
- unknown
97
- >;
98
- const description = record["description"];
99
- const tags = record["tags"];
156
+ function toAgentEntry(element: unknown): AgentDefinitionEntry {
157
+ const record = asRecord(element);
100
158
  return {
101
159
  file: text(record["file"]),
102
160
  exportName: text(record["exportName"]),
103
161
  name: text(record["name"]),
162
+ ...metadata(record),
163
+ };
164
+ }
165
+
166
+ /** Builds a program entry from a possibly malformed element, repaired the same way. */
167
+ function toProgramEntry(element: unknown): ProgramEntry {
168
+ const record = asRecord(element);
169
+ return { file: text(record["file"]), name: text(record["name"]), ...metadata(record) };
170
+ }
171
+
172
+ /** Keeps `description` when it is a string and keeps the string tags only. */
173
+ function metadata(record: Record<string, unknown>): {
174
+ description?: string;
175
+ tags?: string[];
176
+ } {
177
+ const description = record["description"];
178
+ const tags = record["tags"];
179
+ return {
104
180
  ...(typeof description === "string" ? { description } : {}),
105
181
  ...(Array.isArray(tags) ? { tags: tags.filter((tag) => typeof tag === "string") } : {}),
106
182
  };
107
183
  }
108
184
 
185
+ function asRecord(element: unknown): Record<string, unknown> {
186
+ return (typeof element === "object" && element !== null ? element : {}) as Record<
187
+ string,
188
+ unknown
189
+ >;
190
+ }
191
+
109
192
  function text(value: unknown): string {
110
193
  return typeof value === "string" ? value : "";
111
194
  }
package/src/index.ts CHANGED
@@ -39,6 +39,7 @@ export type {
39
39
  DescribedAgent,
40
40
  NameDeviation,
41
41
  ParsedRegistryFile,
42
+ ProgramEntry,
42
43
  RegistryDocument,
43
44
  RegistryLayerRequest,
44
45
  } from "./catalog/index.ts";