@ailu-ai/contracts 2.0.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.
Files changed (142) hide show
  1. package/LICENSE +201 -0
  2. package/dist/admin.d.ts +99 -0
  3. package/dist/admin.d.ts.map +1 -0
  4. package/dist/admin.js +59 -0
  5. package/dist/admin.js.map +1 -0
  6. package/dist/admin.test.d.ts +2 -0
  7. package/dist/admin.test.d.ts.map +1 -0
  8. package/dist/admin.test.js +42 -0
  9. package/dist/admin.test.js.map +1 -0
  10. package/dist/approvals.d.ts +58 -0
  11. package/dist/approvals.d.ts.map +1 -0
  12. package/dist/approvals.js +28 -0
  13. package/dist/approvals.js.map +1 -0
  14. package/dist/artifacts.d.ts +22 -0
  15. package/dist/artifacts.d.ts.map +1 -0
  16. package/dist/artifacts.js +9 -0
  17. package/dist/artifacts.js.map +1 -0
  18. package/dist/catalog.d.ts +626 -0
  19. package/dist/catalog.d.ts.map +1 -0
  20. package/dist/catalog.js +69 -0
  21. package/dist/catalog.js.map +1 -0
  22. package/dist/catalog.test.d.ts +2 -0
  23. package/dist/catalog.test.d.ts.map +1 -0
  24. package/dist/catalog.test.js +98 -0
  25. package/dist/catalog.test.js.map +1 -0
  26. package/dist/compliance.d.ts +428 -0
  27. package/dist/compliance.d.ts.map +1 -0
  28. package/dist/compliance.js +80 -0
  29. package/dist/compliance.js.map +1 -0
  30. package/dist/connectors.d.ts +161 -0
  31. package/dist/connectors.d.ts.map +1 -0
  32. package/dist/connectors.js +49 -0
  33. package/dist/connectors.js.map +1 -0
  34. package/dist/error-envelope.d.ts +16 -0
  35. package/dist/error-envelope.d.ts.map +1 -0
  36. package/dist/error-envelope.js +7 -0
  37. package/dist/error-envelope.js.map +1 -0
  38. package/dist/eval.d.ts +144 -0
  39. package/dist/eval.d.ts.map +1 -0
  40. package/dist/eval.js +36 -0
  41. package/dist/eval.js.map +1 -0
  42. package/dist/events.d.ts +359 -0
  43. package/dist/events.d.ts.map +1 -0
  44. package/dist/events.js +134 -0
  45. package/dist/events.js.map +1 -0
  46. package/dist/fleet.d.ts +147 -0
  47. package/dist/fleet.d.ts.map +1 -0
  48. package/dist/fleet.js +34 -0
  49. package/dist/fleet.js.map +1 -0
  50. package/dist/fs-policy.d.ts +101 -0
  51. package/dist/fs-policy.d.ts.map +1 -0
  52. package/dist/fs-policy.js +36 -0
  53. package/dist/fs-policy.js.map +1 -0
  54. package/dist/fs-policy.test.d.ts +2 -0
  55. package/dist/fs-policy.test.d.ts.map +1 -0
  56. package/dist/fs-policy.test.js +35 -0
  57. package/dist/fs-policy.test.js.map +1 -0
  58. package/dist/fs.d.ts +182 -0
  59. package/dist/fs.d.ts.map +1 -0
  60. package/dist/fs.js +59 -0
  61. package/dist/fs.js.map +1 -0
  62. package/dist/fs.test.d.ts +2 -0
  63. package/dist/fs.test.d.ts.map +1 -0
  64. package/dist/fs.test.js +35 -0
  65. package/dist/fs.test.js.map +1 -0
  66. package/dist/graphs.d.ts +951 -0
  67. package/dist/graphs.d.ts.map +1 -0
  68. package/dist/graphs.js +94 -0
  69. package/dist/graphs.js.map +1 -0
  70. package/dist/graphs.test.d.ts +2 -0
  71. package/dist/graphs.test.d.ts.map +1 -0
  72. package/dist/graphs.test.js +65 -0
  73. package/dist/graphs.test.js.map +1 -0
  74. package/dist/index.d.ts +25 -0
  75. package/dist/index.d.ts.map +1 -0
  76. package/dist/index.js +25 -0
  77. package/dist/index.js.map +1 -0
  78. package/dist/index.test.d.ts +2 -0
  79. package/dist/index.test.d.ts.map +1 -0
  80. package/dist/index.test.js +9 -0
  81. package/dist/index.test.js.map +1 -0
  82. package/dist/knowledge.d.ts +315 -0
  83. package/dist/knowledge.d.ts.map +1 -0
  84. package/dist/knowledge.js +111 -0
  85. package/dist/knowledge.js.map +1 -0
  86. package/dist/knowledge.test.d.ts +2 -0
  87. package/dist/knowledge.test.d.ts.map +1 -0
  88. package/dist/knowledge.test.js +22 -0
  89. package/dist/knowledge.test.js.map +1 -0
  90. package/dist/node-metadata.d.ts +3096 -0
  91. package/dist/node-metadata.d.ts.map +1 -0
  92. package/dist/node-metadata.js +184 -0
  93. package/dist/node-metadata.js.map +1 -0
  94. package/dist/node-metadata.test.d.ts +2 -0
  95. package/dist/node-metadata.test.d.ts.map +1 -0
  96. package/dist/node-metadata.test.js +126 -0
  97. package/dist/node-metadata.test.js.map +1 -0
  98. package/dist/observability.d.ts +154 -0
  99. package/dist/observability.d.ts.map +1 -0
  100. package/dist/observability.js +34 -0
  101. package/dist/observability.js.map +1 -0
  102. package/dist/pii.d.ts +88 -0
  103. package/dist/pii.d.ts.map +1 -0
  104. package/dist/pii.js +42 -0
  105. package/dist/pii.js.map +1 -0
  106. package/dist/principal.d.ts +81 -0
  107. package/dist/principal.d.ts.map +1 -0
  108. package/dist/principal.js +48 -0
  109. package/dist/principal.js.map +1 -0
  110. package/dist/principal.test.d.ts +2 -0
  111. package/dist/principal.test.d.ts.map +1 -0
  112. package/dist/principal.test.js +44 -0
  113. package/dist/principal.test.js.map +1 -0
  114. package/dist/registries.d.ts +26 -0
  115. package/dist/registries.d.ts.map +1 -0
  116. package/dist/registries.js +11 -0
  117. package/dist/registries.js.map +1 -0
  118. package/dist/router.d.ts +48 -0
  119. package/dist/router.d.ts.map +1 -0
  120. package/dist/router.js +22 -0
  121. package/dist/router.js.map +1 -0
  122. package/dist/runs.d.ts +270 -0
  123. package/dist/runs.d.ts.map +1 -0
  124. package/dist/runs.js +108 -0
  125. package/dist/runs.js.map +1 -0
  126. package/dist/runs.test.d.ts +2 -0
  127. package/dist/runs.test.d.ts.map +1 -0
  128. package/dist/runs.test.js +79 -0
  129. package/dist/runs.test.js.map +1 -0
  130. package/dist/search.d.ts +88 -0
  131. package/dist/search.d.ts.map +1 -0
  132. package/dist/search.js +23 -0
  133. package/dist/search.js.map +1 -0
  134. package/dist/skills.d.ts +208 -0
  135. package/dist/skills.d.ts.map +1 -0
  136. package/dist/skills.js +63 -0
  137. package/dist/skills.js.map +1 -0
  138. package/dist/tenant.d.ts +204 -0
  139. package/dist/tenant.d.ts.map +1 -0
  140. package/dist/tenant.js +46 -0
  141. package/dist/tenant.js.map +1 -0
  142. package/package.json +33 -0
package/dist/runs.js ADDED
@@ -0,0 +1,108 @@
1
+ import { z } from "zod";
2
+ // "rejected" (product ADR 0068, issue #496): a governance-level terminal status the
3
+ // control plane assigns when a human REJECTS a pending `human-gate` approval — distinct
4
+ // from "suspended" (still awaiting a decision) and from "failed" (an execution error).
5
+ // The engine itself has no notion of rejection; a rejected run's underlying GraphState
6
+ // stays "suspended" forever (the engine's own resume() would otherwise unconditionally
7
+ // ADVANCE past a human-gate node) — the control plane refuses to call resume() at all
8
+ // once it observes a rejected gate approval, and surfaces "rejected" on the DTO instead.
9
+ // "cancelled" (ADR 0044): a run STOPPED on purpose at a node boundary — a human kill switch or
10
+ // a circuit breaker asked for it, the engine finished the node it was on, checkpointed, and went
11
+ // terminal. Distinct from "failed" (nothing malfunctioned) and from "rejected" (no gate was
12
+ // refused — there may not even be a gate). Unlike "rejected", this one IS an engine status: the
13
+ // underlying GraphState really is `cancelled`, so the run stays resumable/replayable from its
14
+ // last checkpoint and the control plane surfaces exactly what the engine recorded.
15
+ const GraphStatusSchema = z.enum([
16
+ "idle",
17
+ "running",
18
+ "suspended",
19
+ "completed",
20
+ "failed",
21
+ "rejected",
22
+ "cancelled"
23
+ ]);
24
+ export const CreateRunDtoSchema = z.object({
25
+ graphId: z.string().min(1),
26
+ initialData: z.record(z.string(), z.unknown()).default({})
27
+ });
28
+ export const RunDtoSchema = z.object({
29
+ id: z.string().min(1),
30
+ graphId: z.string().min(1),
31
+ status: GraphStatusSchema,
32
+ currentNodeId: z.string().min(1).optional(),
33
+ channels: z.record(z.string(), z.unknown()),
34
+ version: z.number().int().min(0),
35
+ checkpointId: z.string().min(1).optional(),
36
+ /** Owning tenant (tenancy). Optional for pre-tenancy rows backfilled to `default`. */
37
+ tenantId: z.string().min(1).optional(),
38
+ /** Id of the principal who started the run. */
39
+ createdBy: z.string().min(1).optional(),
40
+ createdAt: z.string().datetime(),
41
+ updatedAt: z.string().datetime()
42
+ });
43
+ /** Lightweight row for the runs list — no channels, cheap to query at scale. */
44
+ export const RunSummaryDtoSchema = z.object({
45
+ id: z.string().min(1),
46
+ graphId: z.string().min(1),
47
+ status: GraphStatusSchema,
48
+ currentNodeId: z.string().min(1).nullable(),
49
+ tenantId: z.string().min(1).optional(),
50
+ createdBy: z.string().min(1).optional(),
51
+ createdAt: z.string().datetime(),
52
+ updatedAt: z.string().datetime()
53
+ });
54
+ export const RunListDtoSchema = z.object({
55
+ items: z.array(RunSummaryDtoSchema),
56
+ total: z.number().int().min(0),
57
+ limit: z.number().int().min(1),
58
+ offset: z.number().int().min(0)
59
+ });
60
+ /** Query params arrive as strings over HTTP — coerce numerics. */
61
+ export const ListRunsQueryDtoSchema = z.object({
62
+ status: GraphStatusSchema.optional(),
63
+ graphId: z.string().min(1).optional(),
64
+ limit: z.coerce.number().int().min(1).max(200).default(50),
65
+ offset: z.coerce.number().int().min(0).default(0)
66
+ });
67
+ export const InterruptRunDtoSchema = z.object({
68
+ nodeId: z.string().min(1),
69
+ when: z.enum(["before", "after"])
70
+ });
71
+ /**
72
+ * Channel keys the runtime governance machinery owns: `__approvedTools` carries the
73
+ * human-granted tools an agent may run past an approval gate, and `__approvalIds`
74
+ * carries the pending ApprovalEngine request ids. Allowing a client to PATCH these
75
+ * directly would be a self-approval back door (forge an unlock, or erase the pending
76
+ * ids that the resume gate checks), so they are rejected by the patch DTO below. The
77
+ * literals mirror `@ailu-ai/graph-sdk`'s `APPROVED_TOOLS_CHANNEL` / `APPROVAL_IDS_CHANNEL`;
78
+ * contracts stays dependency-free of the SDK, so they are duplicated as constants here.
79
+ */
80
+ export const RESERVED_PATCH_CHANNELS = ["__approvedTools", "__approvalIds"];
81
+ export const PatchRunStateDtoSchema = z.object({
82
+ patch: z
83
+ .record(z.string(), z.unknown())
84
+ .refine((patch) => RESERVED_PATCH_CHANNELS.every((channel) => !(channel in patch)), (patch) => ({
85
+ message: `patch may not write the reserved governance channel(s): ${RESERVED_PATCH_CHANNELS.filter((channel) => channel in patch).join(", ")}`
86
+ })),
87
+ resumeFrom: z.string().min(1).optional()
88
+ });
89
+ export const ReplayRunDtoSchema = z.object({
90
+ checkpointId: z.string().min(1)
91
+ });
92
+ export const CheckpointDtoSchema = z.object({
93
+ id: z.string().min(1),
94
+ runId: z.string().min(1),
95
+ graphState: z.object({
96
+ runId: z.string().min(1),
97
+ graphId: z.string().min(1),
98
+ currentNodeId: z.string().min(1),
99
+ status: GraphStatusSchema,
100
+ channels: z.record(z.string(), z.unknown()),
101
+ version: z.number().int().min(0),
102
+ checkpointId: z.string().min(1).optional(),
103
+ createdAt: z.string().datetime(),
104
+ updatedAt: z.string().datetime()
105
+ }),
106
+ createdAt: z.string().datetime()
107
+ });
108
+ //# sourceMappingURL=runs.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runs.js","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=runs.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runs.test.d.ts","sourceRoot":"","sources":["../src/runs.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,79 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { ListRunsQueryDtoSchema, PatchRunStateDtoSchema, RESERVED_PATCH_CHANNELS, RunDtoSchema } from "./runs.js";
3
+ /**
4
+ * The patch-run-state contract gates the `PATCH /runs/:id/state` boundary. A client
5
+ * may write ordinary channels, but never the reserved governance channels
6
+ * (`__approvedTools` / `__approvalIds`) — writing those directly would be a
7
+ * self-approval back door (forge an unlock, or erase the pending ids the resume gate
8
+ * reads). The schema rejects such a patch so it surfaces as a 400/422, not a silent
9
+ * state mutation.
10
+ */
11
+ describe("@ailu-ai/contracts — PatchRunStateDtoSchema reserved-channel gate", () => {
12
+ it("accepts a patch of ordinary channels", () => {
13
+ const result = PatchRunStateDtoSchema.safeParse({
14
+ patch: { draft: "hello", count: 3 },
15
+ resumeFrom: "node-a"
16
+ });
17
+ expect(result.success).toBe(true);
18
+ });
19
+ it("rejects a patch that writes __approvedTools", () => {
20
+ const result = PatchRunStateDtoSchema.safeParse({
21
+ patch: { __approvedTools: ["refund"] }
22
+ });
23
+ expect(result.success).toBe(false);
24
+ if (!result.success) {
25
+ expect(result.error.issues[0]?.message).toContain("__approvedTools");
26
+ }
27
+ });
28
+ it("rejects a patch that writes __approvalIds", () => {
29
+ const result = PatchRunStateDtoSchema.safeParse({
30
+ patch: { __approvalIds: [] }
31
+ });
32
+ expect(result.success).toBe(false);
33
+ if (!result.success) {
34
+ expect(result.error.issues[0]?.message).toContain("__approvalIds");
35
+ }
36
+ });
37
+ it("rejects a patch that mixes a reserved channel with ordinary ones", () => {
38
+ const result = PatchRunStateDtoSchema.safeParse({
39
+ patch: { draft: "ok", __approvedTools: ["wire"] }
40
+ });
41
+ expect(result.success).toBe(false);
42
+ });
43
+ it("names both reserved channels", () => {
44
+ expect([...RESERVED_PATCH_CHANNELS]).toEqual(["__approvedTools", "__approvalIds"]);
45
+ });
46
+ });
47
+ /**
48
+ * ADR 0044 — `cancelled` is a first-class terminal run status on the wire. A control plane that
49
+ * stops a run must be able to say so WITHOUT lying: not "failed" (nothing malfunctioned) and not
50
+ * "rejected" (no gate was refused). These tests pin that the published contract accepts it
51
+ * everywhere a status appears, since the whole point is that the distinction survives the API
52
+ * boundary.
53
+ */
54
+ describe("@ailu-ai/contracts — cancelled run status", () => {
55
+ const baseRun = {
56
+ id: "graph-support:run:1",
57
+ graphId: "graph-support",
58
+ channels: {},
59
+ version: 3,
60
+ createdAt: "2026-09-16T10:15:00.000Z",
61
+ updatedAt: "2026-09-16T10:15:42.000Z"
62
+ };
63
+ it("accepts a cancelled run on RunDtoSchema", () => {
64
+ const result = RunDtoSchema.safeParse({ ...baseRun, status: "cancelled" });
65
+ expect(result.success).toBe(true);
66
+ });
67
+ it("keeps cancelled distinct from failed and rejected", () => {
68
+ for (const status of ["cancelled", "failed", "rejected"]) {
69
+ expect(RunDtoSchema.safeParse({ ...baseRun, status }).success).toBe(true);
70
+ }
71
+ // A status outside the vocabulary is still refused — the enum did not become a free string.
72
+ expect(RunDtoSchema.safeParse({ ...baseRun, status: "aborted" }).success).toBe(false);
73
+ });
74
+ it("lets the run list be filtered by status=cancelled", () => {
75
+ const result = ListRunsQueryDtoSchema.safeParse({ status: "cancelled" });
76
+ expect(result.success).toBe(true);
77
+ });
78
+ });
79
+ //# sourceMappingURL=runs.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runs.test.js","sourceRoot":"","sources":["../src/runs.test.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,88 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Resource-search DTOs (ADR 0011) — the API↔Studio wire shapes for the unified search over
4
+ * graphs / agents / KB. Mirrors the engine `@ailu-ai/search` types, minus `tenantId` (the
5
+ * caller's tenant is implicit; never echoed to the client).
6
+ */
7
+ export declare const SearchResourceTypeSchema: z.ZodEnum<["graph", "agent", "kb"]>;
8
+ export type SearchResourceType = z.infer<typeof SearchResourceTypeSchema>;
9
+ /** One ranked search result. */
10
+ export declare const SearchHitDtoSchema: z.ZodObject<{
11
+ type: z.ZodEnum<["graph", "agent", "kb"]>;
12
+ id: z.ZodString;
13
+ title: z.ZodString;
14
+ snippet: z.ZodString;
15
+ href: z.ZodString;
16
+ score: z.ZodNumber;
17
+ namespace: z.ZodOptional<z.ZodString>;
18
+ }, "strip", z.ZodTypeAny, {
19
+ type: "agent" | "kb" | "graph";
20
+ id: string;
21
+ title: string;
22
+ score: number;
23
+ snippet: string;
24
+ href: string;
25
+ namespace?: string | undefined;
26
+ }, {
27
+ type: "agent" | "kb" | "graph";
28
+ id: string;
29
+ title: string;
30
+ score: number;
31
+ snippet: string;
32
+ href: string;
33
+ namespace?: string | undefined;
34
+ }>;
35
+ export type SearchHitDto = z.infer<typeof SearchHitDtoSchema>;
36
+ /** Response wrapper for `GET /search`. */
37
+ export declare const SearchResultsDtoSchema: z.ZodObject<{
38
+ query: z.ZodString;
39
+ hits: z.ZodArray<z.ZodObject<{
40
+ type: z.ZodEnum<["graph", "agent", "kb"]>;
41
+ id: z.ZodString;
42
+ title: z.ZodString;
43
+ snippet: z.ZodString;
44
+ href: z.ZodString;
45
+ score: z.ZodNumber;
46
+ namespace: z.ZodOptional<z.ZodString>;
47
+ }, "strip", z.ZodTypeAny, {
48
+ type: "agent" | "kb" | "graph";
49
+ id: string;
50
+ title: string;
51
+ score: number;
52
+ snippet: string;
53
+ href: string;
54
+ namespace?: string | undefined;
55
+ }, {
56
+ type: "agent" | "kb" | "graph";
57
+ id: string;
58
+ title: string;
59
+ score: number;
60
+ snippet: string;
61
+ href: string;
62
+ namespace?: string | undefined;
63
+ }>, "many">;
64
+ }, "strip", z.ZodTypeAny, {
65
+ query: string;
66
+ hits: {
67
+ type: "agent" | "kb" | "graph";
68
+ id: string;
69
+ title: string;
70
+ score: number;
71
+ snippet: string;
72
+ href: string;
73
+ namespace?: string | undefined;
74
+ }[];
75
+ }, {
76
+ query: string;
77
+ hits: {
78
+ type: "agent" | "kb" | "graph";
79
+ id: string;
80
+ title: string;
81
+ score: number;
82
+ snippet: string;
83
+ href: string;
84
+ namespace?: string | undefined;
85
+ }[];
86
+ }>;
87
+ export type SearchResultsDto = z.infer<typeof SearchResultsDtoSchema>;
88
+ //# sourceMappingURL=search.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,eAAO,MAAM,wBAAwB,qCAAmC,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,gCAAgC;AAChC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;EAQ7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
package/dist/search.js ADDED
@@ -0,0 +1,23 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Resource-search DTOs (ADR 0011) — the API↔Studio wire shapes for the unified search over
4
+ * graphs / agents / KB. Mirrors the engine `@ailu-ai/search` types, minus `tenantId` (the
5
+ * caller's tenant is implicit; never echoed to the client).
6
+ */
7
+ export const SearchResourceTypeSchema = z.enum(["graph", "agent", "kb"]);
8
+ /** One ranked search result. */
9
+ export const SearchHitDtoSchema = z.object({
10
+ type: SearchResourceTypeSchema,
11
+ id: z.string(),
12
+ title: z.string(),
13
+ snippet: z.string(),
14
+ href: z.string(),
15
+ score: z.number(),
16
+ namespace: z.string().optional()
17
+ });
18
+ /** Response wrapper for `GET /search`. */
19
+ export const SearchResultsDtoSchema = z.object({
20
+ query: z.string(),
21
+ hits: z.array(SearchHitDtoSchema)
22
+ });
23
+ //# sourceMappingURL=search.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;AAGzE,gCAAgC;AAChC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,wBAAwB;IAC9B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAGH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;CAClC,CAAC,CAAC"}
@@ -0,0 +1,208 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Skills DTOs (ADR 0035 phase 12) — the SKILL.md surface shared across the API ↔ Studio boundary.
4
+ *
5
+ * A skill is procedural know-how loaded **progressively**: YAML frontmatter (`name` + `description`
6
+ * — a cheap, always-resident index) plus an opaque markdown **body** loaded on demand. A skill is
7
+ * **data, never code**: the body is prompt/context, never executed. The engine `ailu-skills`
8
+ * crate is the source of truth for behaviour; these schemas type the registry/catalog surface the
9
+ * control plane exposes and validate the SKILL.md frontmatter on registration.
10
+ */
11
+ /** An L3 resource a skill body references, resolved on demand. `kind` ∈ `artifact | kb | path`. */
12
+ export declare const SkillResourceDtoSchema: z.ZodObject<{
13
+ kind: z.ZodEnum<["artifact", "kb", "path"]>;
14
+ /** The reference (an artifact ref, a KB doc id, or a relative path) — resolved lazily. */
15
+ ref: z.ZodString;
16
+ }, "strip", z.ZodTypeAny, {
17
+ kind: "path" | "artifact" | "kb";
18
+ ref: string;
19
+ }, {
20
+ kind: "path" | "artifact" | "kb";
21
+ ref: string;
22
+ }>;
23
+ /** Who registered a skill version — provenance stamped on every registration (approver+, ADR 0035 D4). */
24
+ export declare const SkillProvenanceDtoSchema: z.ZodObject<{
25
+ principal: z.ZodOptional<z.ZodString>;
26
+ attestationId: z.ZodOptional<z.ZodString>;
27
+ registeredAt: z.ZodOptional<z.ZodString>;
28
+ status: z.ZodOptional<z.ZodEnum<["asserted", "verified", "rejected"]>>;
29
+ }, "strip", z.ZodTypeAny, {
30
+ status?: "rejected" | "asserted" | "verified" | undefined;
31
+ principal?: string | undefined;
32
+ attestationId?: string | undefined;
33
+ registeredAt?: string | undefined;
34
+ }, {
35
+ status?: "rejected" | "asserted" | "verified" | undefined;
36
+ principal?: string | undefined;
37
+ attestationId?: string | undefined;
38
+ registeredAt?: string | undefined;
39
+ }>;
40
+ /**
41
+ * SKILL.md frontmatter (the always-resident index). `name@version` is the pin reference; a
42
+ * `requires`-bearing skill grants capability and is approval-gated on selection. `embeddingModel`
43
+ * + `embeddingDim` pin the determinism anchor (anti-drift; re-embed only on a model change).
44
+ */
45
+ export declare const SkillFrontmatterDtoSchema: z.ZodObject<{
46
+ /** Stable kebab id. */
47
+ name: z.ZodString;
48
+ /** Semver; referenced as `name@major.minor.patch`. */
49
+ version: z.ZodString;
50
+ /** The load-bearing, embeddable task-match paragraph. */
51
+ description: z.ZodString;
52
+ /** Namespace convention: `skill:{tenant}:org` shared + `skill:{tenant}:agent:{id}`. */
53
+ scope: z.ZodOptional<z.ZodString>;
54
+ /** Tools / profiles the body assumes — the governance trigger (approval-gated on selection). */
55
+ requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
56
+ /** L3 bundled resource references (resolved on demand). */
57
+ resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
58
+ kind: z.ZodEnum<["artifact", "kb", "path"]>;
59
+ /** The reference (an artifact ref, a KB doc id, or a relative path) — resolved lazily. */
60
+ ref: z.ZodString;
61
+ }, "strip", z.ZodTypeAny, {
62
+ kind: "path" | "artifact" | "kb";
63
+ ref: string;
64
+ }, {
65
+ kind: "path" | "artifact" | "kb";
66
+ ref: string;
67
+ }>, "many">>;
68
+ embeddingModel: z.ZodOptional<z.ZodString>;
69
+ embeddingDim: z.ZodOptional<z.ZodNumber>;
70
+ }, "strip", z.ZodTypeAny, {
71
+ name: string;
72
+ version: string;
73
+ description: string;
74
+ scope?: string | undefined;
75
+ requires?: string[] | undefined;
76
+ resources?: {
77
+ kind: "path" | "artifact" | "kb";
78
+ ref: string;
79
+ }[] | undefined;
80
+ embeddingModel?: string | undefined;
81
+ embeddingDim?: number | undefined;
82
+ }, {
83
+ name: string;
84
+ version: string;
85
+ description: string;
86
+ scope?: string | undefined;
87
+ requires?: string[] | undefined;
88
+ resources?: {
89
+ kind: "path" | "artifact" | "kb";
90
+ ref: string;
91
+ }[] | undefined;
92
+ embeddingModel?: string | undefined;
93
+ embeddingDim?: number | undefined;
94
+ }>;
95
+ /**
96
+ * The agent-node `skills` overlay (mirrors the engine `SkillSpec`): `required` pins + an advisory
97
+ * vector-selection cap, scoped to a tenant namespace. Identical to the `metadata.agent.skills`
98
+ * carrier in {@link AgentNodeMetadataSchema} — re-exported here for catalog/registry consumers.
99
+ */
100
+ export declare const SkillSpecDtoSchema: z.ZodObject<{
101
+ namespace: z.ZodString;
102
+ required: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
103
+ advisoryK: z.ZodOptional<z.ZodNumber>;
104
+ }, "strip", z.ZodTypeAny, {
105
+ namespace: string;
106
+ required?: string[] | undefined;
107
+ advisoryK?: number | undefined;
108
+ }, {
109
+ namespace: string;
110
+ required?: string[] | undefined;
111
+ advisoryK?: number | undefined;
112
+ }>;
113
+ /** One entry in a tenant's skill catalog: the frontmatter + provenance + lifecycle state. */
114
+ export declare const SkillCatalogEntryDtoSchema: z.ZodObject<{
115
+ /** Stable kebab id. */
116
+ name: z.ZodString;
117
+ /** Semver; referenced as `name@major.minor.patch`. */
118
+ version: z.ZodString;
119
+ /** The load-bearing, embeddable task-match paragraph. */
120
+ description: z.ZodString;
121
+ /** Namespace convention: `skill:{tenant}:org` shared + `skill:{tenant}:agent:{id}`. */
122
+ scope: z.ZodOptional<z.ZodString>;
123
+ /** Tools / profiles the body assumes — the governance trigger (approval-gated on selection). */
124
+ requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
125
+ /** L3 bundled resource references (resolved on demand). */
126
+ resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
127
+ kind: z.ZodEnum<["artifact", "kb", "path"]>;
128
+ /** The reference (an artifact ref, a KB doc id, or a relative path) — resolved lazily. */
129
+ ref: z.ZodString;
130
+ }, "strip", z.ZodTypeAny, {
131
+ kind: "path" | "artifact" | "kb";
132
+ ref: string;
133
+ }, {
134
+ kind: "path" | "artifact" | "kb";
135
+ ref: string;
136
+ }>, "many">>;
137
+ embeddingModel: z.ZodOptional<z.ZodString>;
138
+ embeddingDim: z.ZodOptional<z.ZodNumber>;
139
+ } & {
140
+ namespace: z.ZodString;
141
+ provenance: z.ZodObject<{
142
+ principal: z.ZodOptional<z.ZodString>;
143
+ attestationId: z.ZodOptional<z.ZodString>;
144
+ registeredAt: z.ZodOptional<z.ZodString>;
145
+ status: z.ZodOptional<z.ZodEnum<["asserted", "verified", "rejected"]>>;
146
+ }, "strip", z.ZodTypeAny, {
147
+ status?: "rejected" | "asserted" | "verified" | undefined;
148
+ principal?: string | undefined;
149
+ attestationId?: string | undefined;
150
+ registeredAt?: string | undefined;
151
+ }, {
152
+ status?: "rejected" | "asserted" | "verified" | undefined;
153
+ principal?: string | undefined;
154
+ attestationId?: string | undefined;
155
+ registeredAt?: string | undefined;
156
+ }>;
157
+ /** Tombstoned versions are never selectable (versions are immutable — tombstone-not-mutate). */
158
+ tombstoned: z.ZodDefault<z.ZodBoolean>;
159
+ createdAt: z.ZodString;
160
+ }, "strip", z.ZodTypeAny, {
161
+ name: string;
162
+ createdAt: string;
163
+ version: string;
164
+ description: string;
165
+ namespace: string;
166
+ provenance: {
167
+ status?: "rejected" | "asserted" | "verified" | undefined;
168
+ principal?: string | undefined;
169
+ attestationId?: string | undefined;
170
+ registeredAt?: string | undefined;
171
+ };
172
+ tombstoned: boolean;
173
+ scope?: string | undefined;
174
+ requires?: string[] | undefined;
175
+ resources?: {
176
+ kind: "path" | "artifact" | "kb";
177
+ ref: string;
178
+ }[] | undefined;
179
+ embeddingModel?: string | undefined;
180
+ embeddingDim?: number | undefined;
181
+ }, {
182
+ name: string;
183
+ createdAt: string;
184
+ version: string;
185
+ description: string;
186
+ namespace: string;
187
+ provenance: {
188
+ status?: "rejected" | "asserted" | "verified" | undefined;
189
+ principal?: string | undefined;
190
+ attestationId?: string | undefined;
191
+ registeredAt?: string | undefined;
192
+ };
193
+ scope?: string | undefined;
194
+ requires?: string[] | undefined;
195
+ resources?: {
196
+ kind: "path" | "artifact" | "kb";
197
+ ref: string;
198
+ }[] | undefined;
199
+ embeddingModel?: string | undefined;
200
+ embeddingDim?: number | undefined;
201
+ tombstoned?: boolean | undefined;
202
+ }>;
203
+ export type SkillResourceDto = z.infer<typeof SkillResourceDtoSchema>;
204
+ export type SkillProvenanceDto = z.infer<typeof SkillProvenanceDtoSchema>;
205
+ export type SkillFrontmatterDto = z.infer<typeof SkillFrontmatterDtoSchema>;
206
+ export type SkillSpecDto = z.infer<typeof SkillSpecDtoSchema>;
207
+ export type SkillCatalogEntryDto = z.infer<typeof SkillCatalogEntryDtoSchema>;
208
+ //# sourceMappingURL=skills.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,mGAAmG;AACnG,eAAO,MAAM,sBAAsB;;IAEjC,0FAA0F;;;;;;;;EAE1F,CAAC;AAEH,0GAA0G;AAC1G,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;EAKnC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;IACpC,uBAAuB;;IAEvB,sDAAsD;;IAEtD,yDAAyD;;IAEzD,uFAAuF;;IAEvF,gGAAgG;;IAEhG,2DAA2D;;;QA5B3D,0FAA0F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgC1F,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAI7B,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B;IA5BrC,uBAAuB;;IAEvB,sDAAsD;;IAEtD,yDAAyD;;IAEzD,uFAAuF;;IAEvF,gGAAgG;;IAEhG,2DAA2D;;;QA5B3D,0FAA0F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiD1F,gGAAgG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGhG,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}
package/dist/skills.js ADDED
@@ -0,0 +1,63 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Skills DTOs (ADR 0035 phase 12) — the SKILL.md surface shared across the API ↔ Studio boundary.
4
+ *
5
+ * A skill is procedural know-how loaded **progressively**: YAML frontmatter (`name` + `description`
6
+ * — a cheap, always-resident index) plus an opaque markdown **body** loaded on demand. A skill is
7
+ * **data, never code**: the body is prompt/context, never executed. The engine `ailu-skills`
8
+ * crate is the source of truth for behaviour; these schemas type the registry/catalog surface the
9
+ * control plane exposes and validate the SKILL.md frontmatter on registration.
10
+ */
11
+ /** An L3 resource a skill body references, resolved on demand. `kind` ∈ `artifact | kb | path`. */
12
+ export const SkillResourceDtoSchema = z.object({
13
+ kind: z.enum(["artifact", "kb", "path"]),
14
+ /** The reference (an artifact ref, a KB doc id, or a relative path) — resolved lazily. */
15
+ ref: z.string().min(1)
16
+ });
17
+ /** Who registered a skill version — provenance stamped on every registration (approver+, ADR 0035 D4). */
18
+ export const SkillProvenanceDtoSchema = z.object({
19
+ principal: z.string().min(1).optional(),
20
+ attestationId: z.string().min(1).optional(),
21
+ registeredAt: z.string().datetime().optional(),
22
+ status: z.enum(["asserted", "verified", "rejected"]).optional()
23
+ });
24
+ /**
25
+ * SKILL.md frontmatter (the always-resident index). `name@version` is the pin reference; a
26
+ * `requires`-bearing skill grants capability and is approval-gated on selection. `embeddingModel`
27
+ * + `embeddingDim` pin the determinism anchor (anti-drift; re-embed only on a model change).
28
+ */
29
+ export const SkillFrontmatterDtoSchema = z.object({
30
+ /** Stable kebab id. */
31
+ name: z.string().min(1),
32
+ /** Semver; referenced as `name@major.minor.patch`. */
33
+ version: z.string().min(1),
34
+ /** The load-bearing, embeddable task-match paragraph. */
35
+ description: z.string().min(1),
36
+ /** Namespace convention: `skill:{tenant}:org` shared + `skill:{tenant}:agent:{id}`. */
37
+ scope: z.string().min(1).optional(),
38
+ /** Tools / profiles the body assumes — the governance trigger (approval-gated on selection). */
39
+ requires: z.array(z.string().min(1)).optional(),
40
+ /** L3 bundled resource references (resolved on demand). */
41
+ resources: z.array(SkillResourceDtoSchema).optional(),
42
+ embeddingModel: z.string().min(1).optional(),
43
+ embeddingDim: z.number().int().min(1).optional()
44
+ });
45
+ /**
46
+ * The agent-node `skills` overlay (mirrors the engine `SkillSpec`): `required` pins + an advisory
47
+ * vector-selection cap, scoped to a tenant namespace. Identical to the `metadata.agent.skills`
48
+ * carrier in {@link AgentNodeMetadataSchema} — re-exported here for catalog/registry consumers.
49
+ */
50
+ export const SkillSpecDtoSchema = z.object({
51
+ namespace: z.string().min(1),
52
+ required: z.array(z.string().min(1)).optional(),
53
+ advisoryK: z.number().int().min(0).optional()
54
+ });
55
+ /** One entry in a tenant's skill catalog: the frontmatter + provenance + lifecycle state. */
56
+ export const SkillCatalogEntryDtoSchema = SkillFrontmatterDtoSchema.extend({
57
+ namespace: z.string().min(1),
58
+ provenance: SkillProvenanceDtoSchema,
59
+ /** Tombstoned versions are never selectable (versions are immutable — tombstone-not-mutate). */
60
+ tombstoned: z.boolean().default(false),
61
+ createdAt: z.string().datetime()
62
+ });
63
+ //# sourceMappingURL=skills.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}