@hivemagnus/ardent-studio 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/NOTICE +12 -0
- package/README.md +133 -2
- package/dist/agents/config-edit.d.ts +20 -0
- package/dist/agents/config-edit.js +75 -0
- package/dist/agents/directory.d.ts +27 -0
- package/dist/agents/directory.js +97 -0
- package/dist/agents/operations.d.ts +47 -0
- package/dist/agents/operations.js +93 -0
- package/dist/auth/links.d.ts +27 -0
- package/dist/auth/links.js +46 -0
- package/dist/auth/oathweave.d.ts +46 -0
- package/dist/auth/oathweave.js +123 -0
- package/dist/blobs/store.d.ts +45 -0
- package/dist/blobs/store.js +159 -0
- package/dist/clients/chattermost.d.ts +16 -0
- package/dist/clients/chattermost.js +36 -0
- package/dist/clients/hivemem.d.ts +85 -0
- package/dist/clients/hivemem.js +89 -0
- package/dist/clients/magnus.d.ts +851 -0
- package/dist/clients/magnus.js +541 -0
- package/dist/clients/service-token.d.ts +24 -0
- package/dist/clients/service-token.js +87 -0
- package/dist/clients/sse.d.ts +8 -0
- package/dist/clients/sse.js +42 -0
- package/dist/conductor/activity.d.ts +38 -0
- package/dist/conductor/activity.js +101 -0
- package/dist/conductor/addressing.d.ts +24 -0
- package/dist/conductor/addressing.js +42 -0
- package/dist/conductor/conductor.d.ts +225 -0
- package/dist/conductor/conductor.js +939 -0
- package/dist/conductor/follower.d.ts +48 -0
- package/dist/conductor/follower.js +154 -0
- package/dist/conductor/live.d.ts +23 -0
- package/dist/conductor/live.js +32 -0
- package/dist/conductor/prompting.d.ts +74 -0
- package/dist/conductor/prompting.js +177 -0
- package/dist/config.d.ts +52 -0
- package/dist/config.js +163 -0
- package/dist/db/database.d.ts +12 -0
- package/dist/db/database.js +62 -0
- package/dist/db/json.d.ts +8 -0
- package/dist/db/json.js +13 -0
- package/dist/db/migrations.d.ts +6 -0
- package/dist/db/migrations.js +571 -0
- package/dist/db/repos/agents.d.ts +86 -0
- package/dist/db/repos/agents.js +92 -0
- package/dist/db/repos/audit.d.ts +37 -0
- package/dist/db/repos/audit.js +20 -0
- package/dist/db/repos/events.d.ts +29 -0
- package/dist/db/repos/events.js +55 -0
- package/dist/db/repos/files.d.ts +41 -0
- package/dist/db/repos/files.js +72 -0
- package/dist/db/repos/idempotency.d.ts +27 -0
- package/dist/db/repos/idempotency.js +46 -0
- package/dist/db/repos/links.d.ts +47 -0
- package/dist/db/repos/links.js +99 -0
- package/dist/db/repos/projects.d.ts +44 -0
- package/dist/db/repos/projects.js +107 -0
- package/dist/db/repos/proposals.d.ts +46 -0
- package/dist/db/repos/proposals.js +65 -0
- package/dist/db/repos/review.d.ts +191 -0
- package/dist/db/repos/review.js +195 -0
- package/dist/db/repos/room.d.ts +163 -0
- package/dist/db/repos/room.js +151 -0
- package/dist/db/repos/sessions.d.ts +36 -0
- package/dist/db/repos/sessions.js +30 -0
- package/dist/db/repos/summaries.d.ts +22 -0
- package/dist/db/repos/summaries.js +105 -0
- package/dist/db/repos/tasks.d.ts +103 -0
- package/dist/db/repos/tasks.js +112 -0
- package/dist/db/repos/team.d.ts +49 -0
- package/dist/db/repos/team.js +95 -0
- package/dist/db/repos/templates.d.ts +55 -0
- package/dist/db/repos/templates.js +120 -0
- package/dist/db/store.d.ts +57 -0
- package/dist/db/store.js +108 -0
- package/dist/events/bus.d.ts +21 -0
- package/dist/events/bus.js +31 -0
- package/dist/events/types.d.ts +3 -0
- package/dist/events/types.js +1 -0
- package/dist/ids.d.ts +28 -0
- package/dist/ids.js +81 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +17 -0
- package/dist/knowledge/extract.d.ts +17 -0
- package/dist/knowledge/extract.js +82 -0
- package/dist/knowledge/sync.d.ts +40 -0
- package/dist/knowledge/sync.js +172 -0
- package/dist/logger.d.ts +5 -0
- package/dist/logger.js +11 -0
- package/dist/main.d.ts +2 -0
- package/dist/main.js +42 -0
- package/dist/review/anchors.d.ts +16 -0
- package/dist/review/anchors.js +67 -0
- package/dist/review/context.d.ts +4 -0
- package/dist/review/context.js +29 -0
- package/dist/review/docx.d.ts +29 -0
- package/dist/review/docx.js +21 -0
- package/dist/review/export.d.ts +16 -0
- package/dist/review/export.js +84 -0
- package/dist/review/importer.d.ts +68 -0
- package/dist/review/importer.js +215 -0
- package/dist/review/index.d.ts +13 -0
- package/dist/review/index.js +7 -0
- package/dist/server/app.d.ts +5 -0
- package/dist/server/app.js +44 -0
- package/dist/server/deps.d.ts +43 -0
- package/dist/server/deps.js +17 -0
- package/dist/server/env.d.ts +6 -0
- package/dist/server/env.js +1 -0
- package/dist/server/errors.d.ts +12 -0
- package/dist/server/errors.js +25 -0
- package/dist/server/routes/agent-studio.d.ts +5 -0
- package/dist/server/routes/agent-studio.js +441 -0
- package/dist/server/routes/agents.d.ts +3 -0
- package/dist/server/routes/agents.js +4 -0
- package/dist/server/routes/files.d.ts +3 -0
- package/dist/server/routes/files.js +88 -0
- package/dist/server/routes/health.d.ts +3 -0
- package/dist/server/routes/health.js +31 -0
- package/dist/server/routes/links.d.ts +3 -0
- package/dist/server/routes/links.js +79 -0
- package/dist/server/routes/projects.d.ts +3 -0
- package/dist/server/routes/projects.js +119 -0
- package/dist/server/routes/review.d.ts +3 -0
- package/dist/server/routes/review.js +198 -0
- package/dist/server/routes/room.d.ts +9 -0
- package/dist/server/routes/room.js +224 -0
- package/dist/server/routes/stream.d.ts +4 -0
- package/dist/server/routes/stream.js +104 -0
- package/dist/server/routes/team.d.ts +3 -0
- package/dist/server/routes/team.js +183 -0
- package/dist/server/routes/templates.d.ts +11 -0
- package/dist/server/routes/templates.js +103 -0
- package/dist/server/routes/work.d.ts +3 -0
- package/dist/server/routes/work.js +139 -0
- package/dist/server/routing.d.ts +31 -0
- package/dist/server/routing.js +132 -0
- package/dist/service.d.ts +34 -0
- package/dist/service.js +93 -0
- package/dist/shared/browser.d.ts +5824 -0
- package/dist/shared/browser.js +1318 -0
- package/dist/team/proposals.d.ts +129 -0
- package/dist/team/proposals.js +349 -0
- package/dist/team/service.d.ts +12 -0
- package/dist/team/service.js +13 -0
- package/dist/team/validation.d.ts +37 -0
- package/dist/team/validation.js +157 -0
- package/dist/templates/secrets.d.ts +2 -0
- package/dist/templates/secrets.js +23 -0
- package/dist/templates/seeds.d.ts +34 -0
- package/dist/templates/seeds.js +277 -0
- package/dist/url.d.ts +2 -0
- package/dist/url.js +7 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +11 -0
- package/docs/openapi-browser.json +12658 -0
- package/package.json +91 -4
|
@@ -0,0 +1,1318 @@
|
|
|
1
|
+
// Public browser contract for the ArdentStudio API. Zod schemas only, with no server
|
|
2
|
+
// imports, so a static console can export, vendor and pin it. The server validates its
|
|
3
|
+
// own requests with these schemas, so the contract and the implementation cannot drift.
|
|
4
|
+
//
|
|
5
|
+
// Paths are relative to /api/ardentstudio/v1. Response objects strip unknown keys when
|
|
6
|
+
// parsed, so later releases may add fields. Errors use errorResponseSchema.
|
|
7
|
+
import { z } from 'zod';
|
|
8
|
+
export const ardentStudioBrowserContractVersion = 1;
|
|
9
|
+
export const ARDENT_STUDIO_API_PREFIX = '/api/ardentstudio/v1';
|
|
10
|
+
export const ARDENT_STUDIO_AUDIENCE = 'ardentstudio';
|
|
11
|
+
export const ARDENT_STUDIO_PERMISSIONS = [
|
|
12
|
+
'ardentstudio:projects:read',
|
|
13
|
+
'ardentstudio:projects:write',
|
|
14
|
+
'ardentstudio:templates:read',
|
|
15
|
+
'ardentstudio:templates:write',
|
|
16
|
+
'ardentstudio:review:write',
|
|
17
|
+
'ardentstudio:agents:admin',
|
|
18
|
+
];
|
|
19
|
+
export const permissionSchema = z.enum(ARDENT_STUDIO_PERMISSIONS);
|
|
20
|
+
/** Every mutation sends this header. A repeated key replays the first answer; a different request with the same key is a 409. */
|
|
21
|
+
export const IDEMPOTENCY_HEADER = 'x-idempotency-key';
|
|
22
|
+
export const idempotencyKeySchema = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/);
|
|
23
|
+
// ── Shared values ──
|
|
24
|
+
const isoDate = z.iso.datetime();
|
|
25
|
+
export const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
|
|
26
|
+
const prefixedId = (prefix) => z.string().regex(new RegExp(`^${prefix}_[0-9A-HJKMNP-TV-Z]{26}$`));
|
|
27
|
+
export const projectIdSchema = prefixedId('prj');
|
|
28
|
+
export const requestedDeliverableIdSchema = prefixedId('req');
|
|
29
|
+
export const fileIdSchema = prefixedId('fil');
|
|
30
|
+
export const templateIdSchema = prefixedId('tpl');
|
|
31
|
+
export const bindingIdSchema = prefixedId('bnd');
|
|
32
|
+
export const teamRevisionIdSchema = prefixedId('trv');
|
|
33
|
+
export const conversationIdSchema = prefixedId('cnv');
|
|
34
|
+
export const messageIdSchema = prefixedId('msg');
|
|
35
|
+
export const taskIdSchema = prefixedId('tsk');
|
|
36
|
+
export const decisionIdSchema = prefixedId('dec');
|
|
37
|
+
export const deliverableIdSchema = prefixedId('dlv');
|
|
38
|
+
export const revisionIdSchema = prefixedId('drv');
|
|
39
|
+
export const commentIdSchema = prefixedId('cmt');
|
|
40
|
+
export const reviewDecisionIdSchema = prefixedId('rvd');
|
|
41
|
+
export const exportIdSchema = prefixedId('exp');
|
|
42
|
+
export const linkIdSchema = prefixedId('lnk');
|
|
43
|
+
export const teamProposalIdSchema = prefixedId('prp');
|
|
44
|
+
/** A Magnus-managed Ardent profile: `<nodeId>~<profile>`, the same reference Magnus uses. */
|
|
45
|
+
export const agentRefSchema = z.string().regex(/^[A-Za-z0-9._-]{1,128}~[A-Za-z0-9._-]{1,128}$/);
|
|
46
|
+
export const roleKeySchema = z.string().regex(/^[a-z][a-z0-9_-]{0,47}$/);
|
|
47
|
+
export const slugSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/);
|
|
48
|
+
const text = (max) => z.string().max(max);
|
|
49
|
+
const name = z.string().trim().min(1).max(200);
|
|
50
|
+
const shortList = (max, item = 500) => z.array(z.string().trim().min(1).max(item)).max(max);
|
|
51
|
+
export const errorResponseSchema = z.object({
|
|
52
|
+
error: z.object({ code: z.string(), message: z.string(), details: z.unknown().optional() }),
|
|
53
|
+
});
|
|
54
|
+
// ── Projects ──
|
|
55
|
+
export const DELIVERABLE_FORMATS = ['md', 'txt', 'docx', 'pdf', 'svg', 'png', 'jpeg', 'webp', 'csv', 'json'];
|
|
56
|
+
export const deliverableFormatSchema = z.enum(DELIVERABLE_FORMATS);
|
|
57
|
+
export const STAGES = ['create', 'research', 'discuss', 'review', 'revise', 'deliver'];
|
|
58
|
+
export const stageSchema = z.enum(STAGES);
|
|
59
|
+
export const projectStatusSchema = z.enum(['active', 'archived']);
|
|
60
|
+
export const projectAreaSchema = z.enum(['team', 'room', 'agents', 'review']);
|
|
61
|
+
export const requestedDeliverableRequestSchema = z.object({
|
|
62
|
+
name,
|
|
63
|
+
kind: z.string().trim().min(1).max(64),
|
|
64
|
+
formats: z.array(deliverableFormatSchema).min(1).max(10),
|
|
65
|
+
stage: stageSchema.nullable().optional(),
|
|
66
|
+
producer_role_key: roleKeySchema.nullable().optional(),
|
|
67
|
+
}).strict();
|
|
68
|
+
export const requestedDeliverableSchema = z.object({
|
|
69
|
+
id: requestedDeliverableIdSchema,
|
|
70
|
+
name: z.string(),
|
|
71
|
+
kind: z.string(),
|
|
72
|
+
formats: z.array(deliverableFormatSchema),
|
|
73
|
+
stage: stageSchema.nullable(),
|
|
74
|
+
producer_role_key: roleKeySchema.nullable(),
|
|
75
|
+
});
|
|
76
|
+
export const hivememStateSchema = z.enum(['pending', 'ready', 'failed']);
|
|
77
|
+
export const projectSchema = z.object({
|
|
78
|
+
id: projectIdSchema,
|
|
79
|
+
name: z.string(),
|
|
80
|
+
brief_md: z.string(),
|
|
81
|
+
audience: z.string().nullable(),
|
|
82
|
+
constraints: z.array(z.string()),
|
|
83
|
+
tags: z.array(z.string()),
|
|
84
|
+
status: projectStatusSchema,
|
|
85
|
+
created_by: z.string(),
|
|
86
|
+
hivemem: z.object({ workspace_id: z.string(), state: hivememStateSchema, error: z.string().nullable() }),
|
|
87
|
+
chattermost_channel_id: z.string().nullable(),
|
|
88
|
+
last_area: projectAreaSchema.nullable(),
|
|
89
|
+
deliverables: z.array(requestedDeliverableSchema),
|
|
90
|
+
created_at: isoDate,
|
|
91
|
+
updated_at: isoDate,
|
|
92
|
+
archived_at: isoDate.nullable(),
|
|
93
|
+
});
|
|
94
|
+
/**
|
|
95
|
+
* The newest meaningful project record: a room message, a pinned decision, a received or reviewed
|
|
96
|
+
* revision, an added reference or link, a published team, an export, or the project's creation or
|
|
97
|
+
* archiving. type is the matching event type; text is a one-line description built from that
|
|
98
|
+
* record only. Presence, sync progress and other bookkeeping do not count.
|
|
99
|
+
*/
|
|
100
|
+
export const lastActivitySchema = z.object({ type: z.string(), at: isoDate, text: z.string() });
|
|
101
|
+
/** Counts derived from stored records. A change is announced as project.updated with fields ["counts"]. */
|
|
102
|
+
export const projectCountsSchema = z.object({
|
|
103
|
+
/** Agent clarifications nobody has answered yet. */
|
|
104
|
+
open_questions: z.number().int(),
|
|
105
|
+
/** Deliverable revisions waiting for a person: unreviewed, or changes requested and no new revision yet. */
|
|
106
|
+
review_pending: z.number().int(),
|
|
107
|
+
/** Studio tasks in an active state (queued, running, input_required, pausing, paused). */
|
|
108
|
+
active_tasks: z.number().int(),
|
|
109
|
+
});
|
|
110
|
+
export const projectSummarySchema = projectSchema.omit({ deliverables: true, brief_md: true }).extend({
|
|
111
|
+
brief_excerpt: z.string(),
|
|
112
|
+
file_count: z.number().int(),
|
|
113
|
+
link_count: z.number().int(),
|
|
114
|
+
deliverable_count: z.number().int(),
|
|
115
|
+
team: z.object({ revision: z.number().int().nullable(), role_count: z.number().int(), bound_count: z.number().int() }),
|
|
116
|
+
...projectCountsSchema.shape,
|
|
117
|
+
/** Never synthesized; null only when the project has no such record. */
|
|
118
|
+
last_activity: lastActivitySchema.nullable(),
|
|
119
|
+
});
|
|
120
|
+
const projectFields = {
|
|
121
|
+
name,
|
|
122
|
+
brief_md: text(100_000),
|
|
123
|
+
audience: text(2_000).nullable(),
|
|
124
|
+
constraints: shortList(50, 2_000),
|
|
125
|
+
tags: shortList(20, 40),
|
|
126
|
+
deliverables: z.array(requestedDeliverableRequestSchema).max(50),
|
|
127
|
+
};
|
|
128
|
+
export const createProjectRequestSchema = z.object({
|
|
129
|
+
name: projectFields.name,
|
|
130
|
+
brief_md: projectFields.brief_md.default(''),
|
|
131
|
+
audience: projectFields.audience.default(null),
|
|
132
|
+
constraints: projectFields.constraints.default([]),
|
|
133
|
+
tags: projectFields.tags.default([]),
|
|
134
|
+
deliverables: projectFields.deliverables.default([]),
|
|
135
|
+
}).strict();
|
|
136
|
+
export const updateProjectRequestSchema = z.object({
|
|
137
|
+
name: projectFields.name.optional(),
|
|
138
|
+
brief_md: projectFields.brief_md.optional(),
|
|
139
|
+
audience: projectFields.audience.optional(),
|
|
140
|
+
constraints: projectFields.constraints.optional(),
|
|
141
|
+
tags: projectFields.tags.optional(),
|
|
142
|
+
/** Replaces the whole list. Existing ids are kept for entries matched by name. */
|
|
143
|
+
deliverables: projectFields.deliverables.optional(),
|
|
144
|
+
last_area: projectAreaSchema.nullable().optional(),
|
|
145
|
+
chattermost_channel_id: z.string().trim().min(1).max(64).nullable().optional(),
|
|
146
|
+
}).strict();
|
|
147
|
+
export const listProjectsQuerySchema = z.object({
|
|
148
|
+
status: z.enum(['active', 'archived', 'all']).default('active'),
|
|
149
|
+
q: z.string().trim().max(200).optional(),
|
|
150
|
+
/** true: only projects with review_pending > 0. */
|
|
151
|
+
needs_review: z.enum(['true', 'false']).optional(),
|
|
152
|
+
});
|
|
153
|
+
export const listProjectsResponseSchema = z.object({ projects: z.array(projectSummarySchema) });
|
|
154
|
+
export const projectResponseSchema = projectSchema;
|
|
155
|
+
// ── Files ──
|
|
156
|
+
export const UPLOAD_MIME_TYPES = [
|
|
157
|
+
'text/markdown', 'text/plain', 'text/csv', 'application/json', 'application/pdf',
|
|
158
|
+
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
|
|
159
|
+
'image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/svg+xml',
|
|
160
|
+
];
|
|
161
|
+
export const uploadMimeSchema = z.enum(UPLOAD_MIME_TYPES);
|
|
162
|
+
export const filePurposeSchema = z.enum(['reference', 'attachment', 'avatar']);
|
|
163
|
+
/**
|
|
164
|
+
* not_indexed: stored only (attachments, avatars). pending/indexing: queued or in flight.
|
|
165
|
+
* indexed: HiveMem holds the current revision. failed: retried automatically, or by reindex.
|
|
166
|
+
* unsupported: the type has no text to index yet.
|
|
167
|
+
*/
|
|
168
|
+
export const knowledgeStateSchema = z.enum(['not_indexed', 'pending', 'indexing', 'indexed', 'failed', 'unsupported']);
|
|
169
|
+
/** A file's or link's HiveMem sync state. source_id is the HiveMem source; revision the synced content digest. */
|
|
170
|
+
export const knowledgeSyncSchema = z.object({
|
|
171
|
+
state: knowledgeStateSchema,
|
|
172
|
+
source_id: z.string().nullable(),
|
|
173
|
+
revision: z.string().nullable(),
|
|
174
|
+
chunks: z.number().int().nullable(),
|
|
175
|
+
error: z.string().nullable(),
|
|
176
|
+
attempts: z.number().int(),
|
|
177
|
+
updated_at: isoDate.nullable(),
|
|
178
|
+
});
|
|
179
|
+
export const fileSchema = z.object({
|
|
180
|
+
id: fileIdSchema,
|
|
181
|
+
project_id: projectIdSchema,
|
|
182
|
+
name: z.string(),
|
|
183
|
+
mime: z.string(),
|
|
184
|
+
size: z.number().int(),
|
|
185
|
+
sha256: sha256Schema,
|
|
186
|
+
purpose: filePurposeSchema,
|
|
187
|
+
created_by: z.string(),
|
|
188
|
+
created_at: isoDate,
|
|
189
|
+
knowledge: knowledgeSyncSchema,
|
|
190
|
+
});
|
|
191
|
+
export const uploadFileQuerySchema = z.object({
|
|
192
|
+
name: z.string().trim().min(1).max(255).refine(value => !/[/\\\0]/.test(value) && value !== '.' && value !== '..', 'Invalid file name'),
|
|
193
|
+
purpose: filePurposeSchema.default('reference'),
|
|
194
|
+
});
|
|
195
|
+
export const listFilesQuerySchema = z.object({ purpose: filePurposeSchema.optional() });
|
|
196
|
+
export const listFilesResponseSchema = z.object({ files: z.array(fileSchema) });
|
|
197
|
+
export const fileResponseSchema = fileSchema;
|
|
198
|
+
// ── Reference links ──
|
|
199
|
+
/** An http or https URL without user name or password. Studio stores it; it never fetches it. */
|
|
200
|
+
export function isReferenceUrl(value) {
|
|
201
|
+
try {
|
|
202
|
+
const url = new URL(value);
|
|
203
|
+
return (url.protocol === 'https:' || url.protocol === 'http:') && Boolean(url.hostname) && !url.username && !url.password;
|
|
204
|
+
}
|
|
205
|
+
catch {
|
|
206
|
+
return false;
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
const referenceUrl = z.string().trim().min(1).max(2048).refine(isReferenceUrl, 'Expected an http or https URL without a user name or password');
|
|
210
|
+
/**
|
|
211
|
+
* A link reference. Its title, URL and note are synced to the project HiveMem workspace as a
|
|
212
|
+
* knowledge source (source_uri is the URL); the linked page itself is not fetched or indexed.
|
|
213
|
+
*/
|
|
214
|
+
export const referenceLinkSchema = z.object({
|
|
215
|
+
id: linkIdSchema,
|
|
216
|
+
project_id: projectIdSchema,
|
|
217
|
+
/** Normalized (WHATWG URL serialization). */
|
|
218
|
+
url: z.string(),
|
|
219
|
+
title: z.string(),
|
|
220
|
+
note_md: z.string(),
|
|
221
|
+
created_by: z.string(),
|
|
222
|
+
created_at: isoDate,
|
|
223
|
+
updated_at: isoDate,
|
|
224
|
+
/** Set when the link was removed; its HiveMem source is retired. */
|
|
225
|
+
deleted_at: isoDate.nullable(),
|
|
226
|
+
knowledge: knowledgeSyncSchema,
|
|
227
|
+
});
|
|
228
|
+
export const createLinkRequestSchema = z.object({
|
|
229
|
+
url: referenceUrl,
|
|
230
|
+
title: z.string().trim().min(1).max(200),
|
|
231
|
+
note_md: text(4_000).default(''),
|
|
232
|
+
}).strict();
|
|
233
|
+
export const updateLinkRequestSchema = z.object({
|
|
234
|
+
url: referenceUrl.optional(),
|
|
235
|
+
title: z.string().trim().min(1).max(200).optional(),
|
|
236
|
+
note_md: text(4_000).optional(),
|
|
237
|
+
}).strict();
|
|
238
|
+
export const listLinksResponseSchema = z.object({ links: z.array(referenceLinkSchema) });
|
|
239
|
+
export const linkResponseSchema = referenceLinkSchema;
|
|
240
|
+
// ── Templates ──
|
|
241
|
+
export const skillRefSchema = z.object({
|
|
242
|
+
kind: z.enum(['local', 'hiveskills']),
|
|
243
|
+
ref: z.string().regex(/^[A-Za-z0-9_.:/-]{1,128}$/),
|
|
244
|
+
channel: z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/).optional(),
|
|
245
|
+
}).strict();
|
|
246
|
+
export const avatarPresetSchema = z.object({
|
|
247
|
+
preset: z.string().regex(/^[a-z0-9-]{1,40}$/),
|
|
248
|
+
accent: z.string().regex(/^[a-z0-9-]{1,40}$/),
|
|
249
|
+
emblem: z.string().regex(/^[a-z0-9-]{1,40}$/),
|
|
250
|
+
}).strict();
|
|
251
|
+
export const integrationSchema = z.enum(['hivemem', 'hiveskills', 'emberpath']);
|
|
252
|
+
export const runtimeRequirementSchema = z.object({
|
|
253
|
+
ardent: z.string().max(40).nullable(),
|
|
254
|
+
backend: z.enum(['llamacpp', 'codex', 'any']),
|
|
255
|
+
}).strict();
|
|
256
|
+
export const templateRefSchema = z.object({ template_id: templateIdSchema, version: z.number().int().min(1) }).strict();
|
|
257
|
+
export const agentTemplateBodySchema = z.object({
|
|
258
|
+
name,
|
|
259
|
+
category: z.string().trim().min(1).max(64),
|
|
260
|
+
purpose: text(2_000),
|
|
261
|
+
example_uses: shortList(20),
|
|
262
|
+
soul_md: text(65_536),
|
|
263
|
+
identity_md: text(65_536),
|
|
264
|
+
skills: z.array(skillRefSchema).max(50),
|
|
265
|
+
/** An Emberpath alias or a model name. Never a URL with credentials or a key. */
|
|
266
|
+
model_hint: z.string().max(200).nullable(),
|
|
267
|
+
runtime_req: runtimeRequirementSchema,
|
|
268
|
+
integrations: z.array(integrationSchema).max(3),
|
|
269
|
+
expected_outputs: shortList(20),
|
|
270
|
+
avatar_preset: avatarPresetSchema,
|
|
271
|
+
}).strict();
|
|
272
|
+
export const RELATIONSHIP_TYPES = ['reports_to', 'delegates_to', 'hands_off_to', 'reviews'];
|
|
273
|
+
export const relationshipTypeSchema = z.enum(RELATIONSHIP_TYPES);
|
|
274
|
+
export const relationshipSchema = z.object({
|
|
275
|
+
from: roleKeySchema,
|
|
276
|
+
to: roleKeySchema,
|
|
277
|
+
type: relationshipTypeSchema,
|
|
278
|
+
/** On hands_off_to, `revise` marks the one loop a workflow may contain. */
|
|
279
|
+
stage: stageSchema.nullable().optional(),
|
|
280
|
+
label: z.string().max(120).optional(),
|
|
281
|
+
}).strict();
|
|
282
|
+
const roleFields = {
|
|
283
|
+
key: roleKeySchema,
|
|
284
|
+
name,
|
|
285
|
+
coordinator: z.boolean(),
|
|
286
|
+
responsibilities_md: text(20_000),
|
|
287
|
+
instructions_md: text(20_000),
|
|
288
|
+
contributions: shortList(30),
|
|
289
|
+
deliverables: shortList(30, 200),
|
|
290
|
+
agent_template_ref: templateRefSchema.nullable(),
|
|
291
|
+
skills: z.array(skillRefSchema).max(50),
|
|
292
|
+
stage: stageSchema.nullable(),
|
|
293
|
+
};
|
|
294
|
+
export const templateRoleSchema = z.object(roleFields).strict();
|
|
295
|
+
export const teamTemplateBodySchema = z.object({
|
|
296
|
+
name,
|
|
297
|
+
category: z.string().trim().min(1).max(64),
|
|
298
|
+
purpose: text(2_000),
|
|
299
|
+
example_uses: shortList(20),
|
|
300
|
+
roles: z.array(templateRoleSchema).min(1).max(30),
|
|
301
|
+
relationships: z.array(relationshipSchema).max(200),
|
|
302
|
+
stages: z.array(stageSchema).max(STAGES.length),
|
|
303
|
+
integrations: z.array(integrationSchema).max(3),
|
|
304
|
+
runtime_req: runtimeRequirementSchema,
|
|
305
|
+
}).strict();
|
|
306
|
+
export const templateKindSchema = z.enum(['agent', 'team']);
|
|
307
|
+
export const templateSourceSchema = z.enum(['seed', 'user']);
|
|
308
|
+
export const templateSummarySchema = z.object({
|
|
309
|
+
id: templateIdSchema,
|
|
310
|
+
kind: templateKindSchema,
|
|
311
|
+
slug: slugSchema,
|
|
312
|
+
source: templateSourceSchema,
|
|
313
|
+
archived: z.boolean(),
|
|
314
|
+
name: z.string(),
|
|
315
|
+
category: z.string(),
|
|
316
|
+
purpose: z.string(),
|
|
317
|
+
latest_version: z.number().int(),
|
|
318
|
+
/** Projects whose current or draft team pins any version of this template. */
|
|
319
|
+
used_by: z.number().int(),
|
|
320
|
+
created_at: isoDate,
|
|
321
|
+
updated_at: isoDate,
|
|
322
|
+
});
|
|
323
|
+
export const templateVersionSummarySchema = z.object({
|
|
324
|
+
version: z.number().int(),
|
|
325
|
+
changelog: z.string(),
|
|
326
|
+
created_by: z.string(),
|
|
327
|
+
created_at: isoDate,
|
|
328
|
+
});
|
|
329
|
+
const versionFields = {
|
|
330
|
+
template_id: templateIdSchema,
|
|
331
|
+
version: z.number().int(),
|
|
332
|
+
changelog: z.string(),
|
|
333
|
+
created_by: z.string(),
|
|
334
|
+
created_at: isoDate,
|
|
335
|
+
};
|
|
336
|
+
export const agentTemplateVersionSchema = z.object({ ...versionFields, kind: z.literal('agent'), body: agentTemplateBodySchema });
|
|
337
|
+
export const teamTemplateVersionSchema = z.object({ ...versionFields, kind: z.literal('team'), body: teamTemplateBodySchema });
|
|
338
|
+
export const templateVersionSchema = z.discriminatedUnion('kind', [agentTemplateVersionSchema, teamTemplateVersionSchema]);
|
|
339
|
+
export const templateDetailSchema = templateSummarySchema.extend({
|
|
340
|
+
versions: z.array(templateVersionSummarySchema),
|
|
341
|
+
latest: templateVersionSchema,
|
|
342
|
+
});
|
|
343
|
+
export const listTemplatesQuerySchema = z.object({
|
|
344
|
+
kind: templateKindSchema.optional(),
|
|
345
|
+
source: templateSourceSchema.optional(),
|
|
346
|
+
archived: z.enum(['true', 'false', 'all']).default('false'),
|
|
347
|
+
q: z.string().trim().max(200).optional(),
|
|
348
|
+
});
|
|
349
|
+
export const listTemplatesResponseSchema = z.object({ templates: z.array(templateSummarySchema) });
|
|
350
|
+
export const createTemplateRequestSchema = z.discriminatedUnion('kind', [
|
|
351
|
+
z.object({ kind: z.literal('agent'), slug: slugSchema.optional(), changelog: text(2_000).default('Initial version'), body: agentTemplateBodySchema }).strict(),
|
|
352
|
+
z.object({ kind: z.literal('team'), slug: slugSchema.optional(), changelog: text(2_000).default('Initial version'), body: teamTemplateBodySchema }).strict(),
|
|
353
|
+
]);
|
|
354
|
+
export const createTemplateVersionRequestSchema = z.object({
|
|
355
|
+
/** The latest version this edit was based on. A newer version answers 409. */
|
|
356
|
+
base_version: z.number().int().min(1),
|
|
357
|
+
changelog: z.string().trim().min(1).max(2_000),
|
|
358
|
+
body: z.union([agentTemplateBodySchema, teamTemplateBodySchema]),
|
|
359
|
+
}).strict();
|
|
360
|
+
export const archiveTemplateRequestSchema = z.object({ archived: z.boolean().default(true) }).strict();
|
|
361
|
+
// ── Team assignment ──
|
|
362
|
+
export const teamDraftRoleSchema = z.object({
|
|
363
|
+
...roleFields,
|
|
364
|
+
agent_ref: agentRefSchema.nullable().default(null),
|
|
365
|
+
/** Project files this role should know about. */
|
|
366
|
+
knowledge: z.array(fileIdSchema).max(100).default([]),
|
|
367
|
+
}).strict();
|
|
368
|
+
export const assignmentRoleSchema = z.object({
|
|
369
|
+
...roleFields,
|
|
370
|
+
agent_ref: agentRefSchema.nullable(),
|
|
371
|
+
binding_id: bindingIdSchema.nullable(),
|
|
372
|
+
knowledge: z.array(fileIdSchema),
|
|
373
|
+
});
|
|
374
|
+
export const teamDraftBodySchema = z.object({
|
|
375
|
+
roles: z.array(teamDraftRoleSchema).max(30),
|
|
376
|
+
relationships: z.array(relationshipSchema).max(200),
|
|
377
|
+
stages: z.array(stageSchema).max(STAGES.length).default([]),
|
|
378
|
+
}).strict();
|
|
379
|
+
export const teamBodySchema = z.object({
|
|
380
|
+
roles: z.array(assignmentRoleSchema),
|
|
381
|
+
relationships: z.array(relationshipSchema),
|
|
382
|
+
stages: z.array(stageSchema),
|
|
383
|
+
});
|
|
384
|
+
export const teamRevisionStatusSchema = z.enum(['draft', 'published', 'superseded']);
|
|
385
|
+
export const teamRevisionSchema = z.object({
|
|
386
|
+
id: teamRevisionIdSchema,
|
|
387
|
+
project_id: projectIdSchema,
|
|
388
|
+
revision: z.number().int(),
|
|
389
|
+
status: teamRevisionStatusSchema,
|
|
390
|
+
source_template: templateRefSchema.nullable(),
|
|
391
|
+
body: teamBodySchema,
|
|
392
|
+
created_by: z.string(),
|
|
393
|
+
created_at: isoDate,
|
|
394
|
+
updated_at: isoDate,
|
|
395
|
+
published_by: z.string().nullable(),
|
|
396
|
+
published_at: isoDate.nullable(),
|
|
397
|
+
});
|
|
398
|
+
export const VALIDATION_CODES = [
|
|
399
|
+
'coordinator_count', 'reporting_cycle', 'workflow_cycle', 'deliverable_without_producer',
|
|
400
|
+
'duplicate_role_key', 'unknown_role', 'self_relationship', 'multiple_managers', 'coordinator_reports',
|
|
401
|
+
'unbound_role', 'reviewer_is_only_producer', 'skill_not_enabled', 'agent_unavailable', 'agent_without_hivemem',
|
|
402
|
+
'outside_reporting_tree', 'agent_facts_unavailable',
|
|
403
|
+
];
|
|
404
|
+
export const validationIssueSchema = z.object({
|
|
405
|
+
severity: z.enum(['error', 'warning']),
|
|
406
|
+
code: z.enum(VALIDATION_CODES),
|
|
407
|
+
message: z.string(),
|
|
408
|
+
role_key: z.string().optional(),
|
|
409
|
+
relationship_index: z.number().int().optional(),
|
|
410
|
+
deliverable: z.string().optional(),
|
|
411
|
+
});
|
|
412
|
+
export const validationResultSchema = z.object({
|
|
413
|
+
issues: z.array(validationIssueSchema),
|
|
414
|
+
/** No errors. */
|
|
415
|
+
can_publish: z.boolean(),
|
|
416
|
+
/** No errors, and the coordinator is bound to an available agent. */
|
|
417
|
+
can_start_room: z.boolean(),
|
|
418
|
+
/** Whether agent availability, skills and HiveMem could be checked through Magnus. */
|
|
419
|
+
agent_facts: z.enum(['complete', 'partial', 'unavailable']),
|
|
420
|
+
});
|
|
421
|
+
export const teamStateSchema = z.object({
|
|
422
|
+
current: teamRevisionSchema.nullable(),
|
|
423
|
+
draft: teamRevisionSchema.nullable(),
|
|
424
|
+
/** Validation of the draft when there is one, else of the current revision. */
|
|
425
|
+
validation: validationResultSchema.nullable(),
|
|
426
|
+
});
|
|
427
|
+
export const putTeamDraftRequestSchema = z.object({
|
|
428
|
+
/** The published revision this draft builds on (null before the first publish). A newer published revision answers 409. */
|
|
429
|
+
base_revision: z.number().int().min(1).nullable(),
|
|
430
|
+
source_template: templateRefSchema.nullable().optional(),
|
|
431
|
+
body: teamDraftBodySchema,
|
|
432
|
+
}).strict();
|
|
433
|
+
export const validateTeamRequestSchema = z.object({ body: teamDraftBodySchema.optional() }).strict();
|
|
434
|
+
export const publishTeamRequestSchema = z.object({ draft_revision: z.number().int().min(1) }).strict();
|
|
435
|
+
export const applyTemplateRequestSchema = z.object({
|
|
436
|
+
template_id: templateIdSchema,
|
|
437
|
+
version: z.number().int().min(1),
|
|
438
|
+
/** Required to overwrite an existing draft. */
|
|
439
|
+
replace_draft: z.boolean().default(false),
|
|
440
|
+
}).strict();
|
|
441
|
+
export const saveAsTemplateRequestSchema = z.object({
|
|
442
|
+
from: z.enum(['draft', 'current']).default('current'),
|
|
443
|
+
/** Save as a new version of this user team template instead of a new template. */
|
|
444
|
+
template_id: templateIdSchema.optional(),
|
|
445
|
+
base_version: z.number().int().min(1).optional(),
|
|
446
|
+
slug: slugSchema.optional(),
|
|
447
|
+
name,
|
|
448
|
+
category: z.string().trim().min(1).max(64).default('custom'),
|
|
449
|
+
purpose: text(2_000).default(''),
|
|
450
|
+
changelog: z.string().trim().min(1).max(2_000).default('Saved from a project team'),
|
|
451
|
+
}).strict();
|
|
452
|
+
// ── Team proposals ──
|
|
453
|
+
/** A role an agent proposes. Optional fields default as shown, so a draft can be built from it. */
|
|
454
|
+
export const teamProposalRoleSchema = z.object({
|
|
455
|
+
key: roleKeySchema,
|
|
456
|
+
name,
|
|
457
|
+
coordinator: z.boolean().default(false),
|
|
458
|
+
responsibilities_md: text(20_000).default(''),
|
|
459
|
+
instructions_md: text(20_000).default(''),
|
|
460
|
+
contributions: shortList(30).default([]),
|
|
461
|
+
deliverables: shortList(30, 200).default([]),
|
|
462
|
+
agent_template_ref: templateRefSchema.nullable().default(null),
|
|
463
|
+
skills: z.array(skillRefSchema).max(50).default([]),
|
|
464
|
+
stage: stageSchema.nullable().default(null),
|
|
465
|
+
/** Why the role is on the team. */
|
|
466
|
+
rationale: text(2_000).default(''),
|
|
467
|
+
});
|
|
468
|
+
export const teamProposalRelationshipSchema = z.object({
|
|
469
|
+
from: roleKeySchema,
|
|
470
|
+
to: roleKeySchema,
|
|
471
|
+
type: relationshipTypeSchema,
|
|
472
|
+
stage: stageSchema.nullable().optional(),
|
|
473
|
+
label: z.string().max(120).optional(),
|
|
474
|
+
});
|
|
475
|
+
/** A suggestion only: a person binds roles. agent_ref is one of the agents the request listed. */
|
|
476
|
+
export const teamProposalBindingSchema = z.object({ role_key: roleKeySchema, agent_ref: agentRefSchema, reason: text(1_000).default('') });
|
|
477
|
+
/**
|
|
478
|
+
* The JSON an agent must answer a team_proposal task with. Besides the field rules: role keys are
|
|
479
|
+
* unique, exactly one role is the coordinator, relationships and bindings name proposed roles, a
|
|
480
|
+
* role has at most one binding, and a relationship never points at its own role.
|
|
481
|
+
*/
|
|
482
|
+
export const teamProposalSchema = z.object({
|
|
483
|
+
rationale: text(4_000).default(''),
|
|
484
|
+
/** The team template the proposal started from, if any. */
|
|
485
|
+
source_template: templateRefSchema.nullable().default(null),
|
|
486
|
+
roles: z.array(teamProposalRoleSchema).min(1).max(30),
|
|
487
|
+
relationships: z.array(teamProposalRelationshipSchema).max(200).default([]),
|
|
488
|
+
stages: z.array(stageSchema).max(STAGES.length).default([]),
|
|
489
|
+
bindings: z.array(teamProposalBindingSchema).max(30).default([]),
|
|
490
|
+
}).superRefine((value, context) => {
|
|
491
|
+
const keys = new Set();
|
|
492
|
+
value.roles.forEach((role, index) => {
|
|
493
|
+
if (keys.has(role.key))
|
|
494
|
+
context.addIssue({ code: 'custom', path: ['roles', index, 'key'], message: `Duplicate role key "${role.key}"` });
|
|
495
|
+
keys.add(role.key);
|
|
496
|
+
});
|
|
497
|
+
const coordinators = value.roles.filter(role => role.coordinator).length;
|
|
498
|
+
if (coordinators !== 1)
|
|
499
|
+
context.addIssue({ code: 'custom', path: ['roles'], message: `Exactly one role must be the coordinator (found ${coordinators})` });
|
|
500
|
+
value.relationships.forEach((edge, index) => {
|
|
501
|
+
for (const end of ['from', 'to']) {
|
|
502
|
+
if (!keys.has(edge[end]))
|
|
503
|
+
context.addIssue({ code: 'custom', path: ['relationships', index, end], message: `Unknown role "${edge[end]}"` });
|
|
504
|
+
}
|
|
505
|
+
if (edge.from === edge.to)
|
|
506
|
+
context.addIssue({ code: 'custom', path: ['relationships', index], message: 'A relationship cannot point at its own role' });
|
|
507
|
+
});
|
|
508
|
+
const bound = new Set();
|
|
509
|
+
value.bindings.forEach((binding, index) => {
|
|
510
|
+
if (!keys.has(binding.role_key))
|
|
511
|
+
context.addIssue({ code: 'custom', path: ['bindings', index, 'role_key'], message: `Unknown role "${binding.role_key}"` });
|
|
512
|
+
if (bound.has(binding.role_key))
|
|
513
|
+
context.addIssue({ code: 'custom', path: ['bindings', index, 'role_key'], message: `Role "${binding.role_key}" has more than one binding` });
|
|
514
|
+
bound.add(binding.role_key);
|
|
515
|
+
});
|
|
516
|
+
});
|
|
517
|
+
/** queued: waiting for the agent (also between attempts); running: the agent is working; ready: a valid proposal; failed and cancelled are final. */
|
|
518
|
+
export const teamProposalStateSchema = z.enum(['queued', 'running', 'ready', 'failed', 'cancelled']);
|
|
519
|
+
export const teamProposalAttemptSchema = z.object({
|
|
520
|
+
attempt: z.number().int(),
|
|
521
|
+
task_id: taskIdSchema,
|
|
522
|
+
/** pending: not answered yet; invalid: the reply failed validation (error says how). */
|
|
523
|
+
outcome: z.enum(['pending', 'valid', 'invalid', 'failed', 'cancelled']),
|
|
524
|
+
error: z.string().nullable(),
|
|
525
|
+
});
|
|
526
|
+
export const teamProposalRecordSchema = z.object({
|
|
527
|
+
id: teamProposalIdSchema,
|
|
528
|
+
project_id: projectIdSchema,
|
|
529
|
+
/** The agent asked: the chosen agent, else the bound coordinator. */
|
|
530
|
+
agent_ref: agentRefSchema,
|
|
531
|
+
/** The role that agent holds in the team the proposal was based on, if any. */
|
|
532
|
+
role_key: z.string().nullable(),
|
|
533
|
+
state: teamProposalStateSchema,
|
|
534
|
+
/** One line from real records: the agent's progress, a retry and why, or the outcome. */
|
|
535
|
+
progress: z.string().nullable(),
|
|
536
|
+
/** The current attempt's Studio task (mode team_proposal). Cancel it to cancel the proposal. */
|
|
537
|
+
task_id: taskIdSchema.nullable(),
|
|
538
|
+
/** At most two: one retry after an invalid reply. */
|
|
539
|
+
attempts: z.array(teamProposalAttemptSchema),
|
|
540
|
+
/** The team the proposal was asked against. Compare with the current team before applying. */
|
|
541
|
+
basis: z.object({ current_revision: z.number().int().nullable(), draft_revision: z.number().int().nullable(), source_template: templateRefSchema.nullable() }),
|
|
542
|
+
/** The validated proposal when state is ready. */
|
|
543
|
+
proposal: teamProposalSchema.nullable(),
|
|
544
|
+
/**
|
|
545
|
+
* The proposal as a team draft body: suggested bindings filled in, knowledge kept for roles whose
|
|
546
|
+
* key matches the basis team. Nothing is applied: a person sends (parts of) it with PUT team/draft.
|
|
547
|
+
*/
|
|
548
|
+
draft_body: teamDraftBodySchema.nullable(),
|
|
549
|
+
error: z.string().nullable(),
|
|
550
|
+
created_by: z.string(),
|
|
551
|
+
created_at: isoDate,
|
|
552
|
+
updated_at: isoDate,
|
|
553
|
+
finished_at: isoDate.nullable(),
|
|
554
|
+
});
|
|
555
|
+
export const proposeTeamRequestSchema = z.object({
|
|
556
|
+
/** Ask this agent instead of the bound coordinator of the draft (else current) team. */
|
|
557
|
+
agent_ref: agentRefSchema.optional(),
|
|
558
|
+
}).strict();
|
|
559
|
+
export const teamProposalResponseSchema = teamProposalRecordSchema;
|
|
560
|
+
export const listTeamProposalsResponseSchema = z.object({ proposals: z.array(teamProposalRecordSchema) });
|
|
561
|
+
// ── Agents (through Magnus) ──
|
|
562
|
+
export const agentSchema = z.object({
|
|
563
|
+
agent_ref: agentRefSchema,
|
|
564
|
+
node_id: z.string(),
|
|
565
|
+
node_name: z.string(),
|
|
566
|
+
profile: z.string(),
|
|
567
|
+
backend: z.enum(['llamacpp', 'codex']).nullable(),
|
|
568
|
+
running: z.boolean(),
|
|
569
|
+
reachable: z.boolean(),
|
|
570
|
+
/** Running on a reachable node without a reported error. */
|
|
571
|
+
available: z.boolean(),
|
|
572
|
+
installation_version: z.string().nullable(),
|
|
573
|
+
error: z.string().nullable(),
|
|
574
|
+
/** Studio presentation name, else the cached binding name, else the profile ID. */
|
|
575
|
+
display_name: z.string(),
|
|
576
|
+
portrait: avatarPresetSchema.nullable(),
|
|
577
|
+
binding_id: bindingIdSchema.nullable(),
|
|
578
|
+
roles: z.array(z.object({ project_id: projectIdSchema, project_name: z.string(), role_key: z.string(), role_name: z.string() })),
|
|
579
|
+
});
|
|
580
|
+
export const listAgentsResponseSchema = z.object({
|
|
581
|
+
agents: z.array(agentSchema),
|
|
582
|
+
available_count: z.number().int(),
|
|
583
|
+
magnus: z.object({ state: z.enum(['ok', 'unavailable']), error: z.string().nullable() }),
|
|
584
|
+
});
|
|
585
|
+
// ── Room: layout, conversations, messages ──
|
|
586
|
+
export const seatSchema = z.object({
|
|
587
|
+
id: z.string().regex(/^[a-z0-9-]{1,40}$/),
|
|
588
|
+
kind: z.enum(['desk', 'discussion', 'review', 'shelf', 'wall']),
|
|
589
|
+
x: z.number().min(-1000).max(1000),
|
|
590
|
+
y: z.number().min(-1000).max(1000),
|
|
591
|
+
}).strict();
|
|
592
|
+
export const placementSchema = z.object({ role_key: roleKeySchema, seat_id: z.string().regex(/^[a-z0-9-]{1,40}$/) }).strict();
|
|
593
|
+
export const roomLayoutSchema = z.object({
|
|
594
|
+
project_id: projectIdSchema,
|
|
595
|
+
revision: z.number().int(),
|
|
596
|
+
seats: z.array(seatSchema),
|
|
597
|
+
placements: z.array(placementSchema),
|
|
598
|
+
zone_labels: z.record(z.string(), z.string()),
|
|
599
|
+
created_by: z.string(),
|
|
600
|
+
created_at: isoDate,
|
|
601
|
+
});
|
|
602
|
+
export const layoutResponseSchema = z.object({ layout: roomLayoutSchema.nullable() });
|
|
603
|
+
export const putLayoutRequestSchema = z.object({
|
|
604
|
+
/** The revision this edit was based on (null for the first). A newer revision answers 409. */
|
|
605
|
+
base_revision: z.number().int().min(1).nullable(),
|
|
606
|
+
seats: z.array(seatSchema).max(64),
|
|
607
|
+
placements: z.array(placementSchema).max(64),
|
|
608
|
+
zone_labels: z.record(z.string().regex(/^[a-z0-9-]{1,40}$/), z.string().trim().max(60)).refine(value => Object.keys(value).length <= 32, 'At most 32 zone labels').default({}),
|
|
609
|
+
}).strict();
|
|
610
|
+
export const conversationKindSchema = z.enum(['team', 'direct', 'discussion']);
|
|
611
|
+
export const desiredOutputSchema = z.enum(['decision', 'short_doc', 'options']);
|
|
612
|
+
/** running: rounds in progress; summarizing: the coordinator summary; stopped by a person; done. */
|
|
613
|
+
export const discussionStateSchema = z.enum(['running', 'summarizing', 'stopped', 'done']);
|
|
614
|
+
export const discussionSchema = z.object({
|
|
615
|
+
question: z.string(),
|
|
616
|
+
desired_output: desiredOutputSchema,
|
|
617
|
+
participants: z.array(roleKeySchema),
|
|
618
|
+
max_rounds: z.number().int(),
|
|
619
|
+
round: z.number().int(),
|
|
620
|
+
state: discussionStateSchema,
|
|
621
|
+
});
|
|
622
|
+
export const conversationSchema = z.object({
|
|
623
|
+
id: conversationIdSchema,
|
|
624
|
+
project_id: projectIdSchema,
|
|
625
|
+
kind: conversationKindSchema,
|
|
626
|
+
parent_id: conversationIdSchema.nullable(),
|
|
627
|
+
title: z.string(),
|
|
628
|
+
/** The role a direct conversation talks to. */
|
|
629
|
+
role_key: roleKeySchema.nullable(),
|
|
630
|
+
discussion: discussionSchema.nullable(),
|
|
631
|
+
/** Project message seq of the newest message. */
|
|
632
|
+
last_message_seq: z.number().int(),
|
|
633
|
+
created_by: z.string(),
|
|
634
|
+
created_at: isoDate,
|
|
635
|
+
updated_at: isoDate,
|
|
636
|
+
stopped_at: isoDate.nullable(),
|
|
637
|
+
});
|
|
638
|
+
const conversationTitle = z.string().trim().min(1).max(200);
|
|
639
|
+
export const createConversationRequestSchema = z.discriminatedUnion('kind', [
|
|
640
|
+
/** There is one team conversation per project; creating it again answers the existing one. */
|
|
641
|
+
z.object({ kind: z.literal('team'), title: conversationTitle.optional() }).strict(),
|
|
642
|
+
z.object({ kind: z.literal('direct'), role_key: roleKeySchema, title: conversationTitle.optional() }).strict(),
|
|
643
|
+
z.object({
|
|
644
|
+
kind: z.literal('discussion'),
|
|
645
|
+
title: conversationTitle.optional(),
|
|
646
|
+
parent_id: conversationIdSchema.optional(),
|
|
647
|
+
question: z.string().trim().min(1).max(4_000),
|
|
648
|
+
desired_output: desiredOutputSchema,
|
|
649
|
+
participants: z.array(roleKeySchema).min(1).max(8).refine(value => new Set(value).size === value.length, 'Duplicate participant'),
|
|
650
|
+
max_rounds: z.number().int().min(1).max(4).default(2),
|
|
651
|
+
}).strict(),
|
|
652
|
+
]);
|
|
653
|
+
export const listConversationsResponseSchema = z.object({ conversations: z.array(conversationSchema) });
|
|
654
|
+
export const conversationResponseSchema = conversationSchema;
|
|
655
|
+
export const messageAuthorSchema = z.discriminatedUnion('kind', [
|
|
656
|
+
z.object({ kind: z.literal('user'), user_id: z.string() }),
|
|
657
|
+
z.object({ kind: z.literal('agent'), binding_id: bindingIdSchema, role_key: z.string().nullable() }),
|
|
658
|
+
z.object({ kind: z.literal('system') }),
|
|
659
|
+
]);
|
|
660
|
+
export const messageStateSchema = z.enum(['streaming', 'complete', 'failed']);
|
|
661
|
+
/**
|
|
662
|
+
* kind: message (a person), reply (an agent's turn), summary (a discussion summary), clarification
|
|
663
|
+
* (an agent's question; links.question, links.options, links.answer_message_id), answer,
|
|
664
|
+
* decision_proposal (links.proposal, links.decision_id), handoff (links.handoff), discussion_question
|
|
665
|
+
* and system (Studio notes such as a refused hand-off). links.task_id names the Studio task.
|
|
666
|
+
*/
|
|
667
|
+
export const messageSchema = z.object({
|
|
668
|
+
id: messageIdSchema,
|
|
669
|
+
project_id: projectIdSchema,
|
|
670
|
+
conversation_id: conversationIdSchema,
|
|
671
|
+
/** Per project, so the whole transcript has one order. */
|
|
672
|
+
seq: z.number().int(),
|
|
673
|
+
author: messageAuthorSchema,
|
|
674
|
+
/** Role keys. */
|
|
675
|
+
addressees: z.array(z.string()),
|
|
676
|
+
reply_to: messageIdSchema.nullable(),
|
|
677
|
+
thread_root: messageIdSchema.nullable(),
|
|
678
|
+
kind: z.string(),
|
|
679
|
+
/** Final text. While state is streaming, live text arrives as message.delta on the project stream. */
|
|
680
|
+
body_md: z.string(),
|
|
681
|
+
attachments: z.array(fileIdSchema),
|
|
682
|
+
links: z.record(z.string(), z.unknown()),
|
|
683
|
+
ardent: z.object({ task_id: z.string(), session_id: z.string().nullable() }).nullable(),
|
|
684
|
+
state: messageStateSchema,
|
|
685
|
+
created_at: isoDate,
|
|
686
|
+
updated_at: isoDate,
|
|
687
|
+
});
|
|
688
|
+
export const listMessagesQuerySchema = z.object({
|
|
689
|
+
after: z.string().regex(/^\d{1,15}$/).optional(),
|
|
690
|
+
limit: z.string().regex(/^\d{1,3}$/).optional(),
|
|
691
|
+
});
|
|
692
|
+
export const listMessagesResponseSchema = z.object({
|
|
693
|
+
messages: z.array(messageSchema),
|
|
694
|
+
/** Pass as ?after= for the next page; null when this page reached the end. */
|
|
695
|
+
next_after: z.number().int().nullable(),
|
|
696
|
+
});
|
|
697
|
+
export const recipientSchema = z.discriminatedUnion('kind', [
|
|
698
|
+
/** Team and Coordinator start a coordinator turn (unless the text @mentions roles). */
|
|
699
|
+
z.object({ kind: z.literal('team') }).strict(),
|
|
700
|
+
z.object({ kind: z.literal('coordinator') }).strict(),
|
|
701
|
+
/** One turn per role, in this order. */
|
|
702
|
+
z.object({ kind: z.literal('roles'), roles: z.array(roleKeySchema).min(1).max(10) }).strict(),
|
|
703
|
+
]);
|
|
704
|
+
export const postMessageRequestSchema = z.object({
|
|
705
|
+
body_md: z.string().trim().min(1).max(20_000),
|
|
706
|
+
to: recipientSchema.default({ kind: 'team' }),
|
|
707
|
+
reply_to: messageIdSchema.optional(),
|
|
708
|
+
thread_root: messageIdSchema.optional(),
|
|
709
|
+
/** Project files to attach. Text files are given to the agents as context. */
|
|
710
|
+
attachments: z.array(fileIdSchema).max(10).default([]),
|
|
711
|
+
}).strict();
|
|
712
|
+
// ── Tasks ──
|
|
713
|
+
export const TASK_MODES = ['turn', 'assignment', 'discussion_turn', 'revision', 'review', 'team_proposal'];
|
|
714
|
+
export const taskModeSchema = z.enum(TASK_MODES);
|
|
715
|
+
/** The Ardent state mirrored, plus pausing (requested, not yet at a step boundary). input_required waits for a person's answer. */
|
|
716
|
+
export const taskStateSchema = z.enum(['queued', 'running', 'input_required', 'pausing', 'paused', 'completed', 'partial', 'failed', 'cancelled', 'unknown']);
|
|
717
|
+
export const taskSchema = z.object({
|
|
718
|
+
id: taskIdSchema,
|
|
719
|
+
project_id: projectIdSchema,
|
|
720
|
+
title: z.string(),
|
|
721
|
+
mode: taskModeSchema,
|
|
722
|
+
role_key: z.string().nullable(),
|
|
723
|
+
binding_id: bindingIdSchema.nullable(),
|
|
724
|
+
/** The published team revision whose rules apply to this task. */
|
|
725
|
+
assignment_revision: z.number().int().nullable(),
|
|
726
|
+
conversation_id: conversationIdSchema.nullable(),
|
|
727
|
+
trigger_message_id: messageIdSchema.nullable(),
|
|
728
|
+
instructions_md: z.string(),
|
|
729
|
+
source: z.record(z.string(), z.unknown()),
|
|
730
|
+
state: taskStateSchema,
|
|
731
|
+
/** mission: an Ardent 2.2.0 team mission; turn: a task-submit with a composed prompt (older agents). Null until Ardent accepts it. */
|
|
732
|
+
dispatch: z.enum(['mission', 'turn']).nullable(),
|
|
733
|
+
ardent: z.object({ agent_ref: z.string().nullable(), task_id: z.string().nullable(), session_id: z.string().nullable() }),
|
|
734
|
+
outcome: z.unknown(),
|
|
735
|
+
reassigned_from: taskIdSchema.nullable(),
|
|
736
|
+
/** Tasks in one ordering group start one after another. */
|
|
737
|
+
group_id: z.string().nullable(),
|
|
738
|
+
group_position: z.number().int(),
|
|
739
|
+
created_by: z.string(),
|
|
740
|
+
created_at: isoDate,
|
|
741
|
+
updated_at: isoDate,
|
|
742
|
+
finished_at: isoDate.nullable(),
|
|
743
|
+
});
|
|
744
|
+
export const listTasksQuerySchema = z.object({
|
|
745
|
+
state: z.enum(['active', 'finished', 'all']).default('all'),
|
|
746
|
+
conversation_id: conversationIdSchema.optional(),
|
|
747
|
+
});
|
|
748
|
+
export const listTasksResponseSchema = z.object({ tasks: z.array(taskSchema) });
|
|
749
|
+
export const createTaskRequestSchema = z.object({
|
|
750
|
+
title: z.string().trim().min(1).max(200),
|
|
751
|
+
instructions_md: z.string().max(20_000).default(''),
|
|
752
|
+
role_key: roleKeySchema,
|
|
753
|
+
mode: z.enum(['assignment', 'review']).default('assignment'),
|
|
754
|
+
/** Where the reply goes: this conversation, the source message's, else the team conversation. */
|
|
755
|
+
conversation_id: conversationIdSchema.optional(),
|
|
756
|
+
source_message_id: messageIdSchema.optional(),
|
|
757
|
+
}).strict();
|
|
758
|
+
export const reassignTaskRequestSchema = z.object({ role_key: roleKeySchema }).strict();
|
|
759
|
+
export const taskResponseSchema = taskSchema;
|
|
760
|
+
export const postMessageResponseSchema = z.object({ message: messageSchema, tasks: z.array(taskSchema) });
|
|
761
|
+
export const answerRequestSchema = z.object({ body_md: z.string().trim().min(1).max(20_000), option: z.string().trim().min(1).max(300).optional() }).strict();
|
|
762
|
+
export const followUpRequestSchema = z.object({ body_md: z.string().trim().max(20_000).default('') }).strict();
|
|
763
|
+
// ── Decisions ──
|
|
764
|
+
export const decisionSchema = z.object({
|
|
765
|
+
id: decisionIdSchema,
|
|
766
|
+
project_id: projectIdSchema,
|
|
767
|
+
title: z.string(),
|
|
768
|
+
statement_md: z.string(),
|
|
769
|
+
rationale_md: z.string(),
|
|
770
|
+
sources: z.array(z.object({ kind: z.string(), ref: z.string() })),
|
|
771
|
+
decided_by: z.string(),
|
|
772
|
+
superseded_by: decisionIdSchema.nullable(),
|
|
773
|
+
created_at: isoDate,
|
|
774
|
+
});
|
|
775
|
+
export const createDecisionRequestSchema = z.object({
|
|
776
|
+
title: z.string().trim().min(1).max(200),
|
|
777
|
+
statement_md: z.string().trim().min(1).max(20_000),
|
|
778
|
+
rationale_md: z.string().max(20_000).default(''),
|
|
779
|
+
/** Pin a message (for example an agent's proposal) as the decision's source. */
|
|
780
|
+
source_message_id: messageIdSchema.optional(),
|
|
781
|
+
}).strict();
|
|
782
|
+
export const supersedeDecisionRequestSchema = z.object({
|
|
783
|
+
title: z.string().trim().min(1).max(200),
|
|
784
|
+
statement_md: z.string().trim().min(1).max(20_000),
|
|
785
|
+
rationale_md: z.string().max(20_000).default(''),
|
|
786
|
+
}).strict();
|
|
787
|
+
export const listDecisionsResponseSchema = z.object({ decisions: z.array(decisionSchema) });
|
|
788
|
+
export const decisionResponseSchema = decisionSchema;
|
|
789
|
+
// ── Activity (derived from real records only) ──
|
|
790
|
+
/**
|
|
791
|
+
* offline/available come from the 30-second status probe. queued, working (only after the journal
|
|
792
|
+
* shows model_started or tool_attempt), reviewing, asking, waiting (behind another turn in its
|
|
793
|
+
* ordering group, or on a role it handed work to), paused, blocked (the agent's newest task failed,
|
|
794
|
+
* ended in an unknown Ardent state or reported itself blocked) and delivering (shortly after a
|
|
795
|
+
* verified deliverable revision) come from Studio tasks and Ardent journal events. unknown: not
|
|
796
|
+
* probed yet. When several apply, the highest wins: offline, paused, blocked, asking, reviewing,
|
|
797
|
+
* working, queued, waiting, delivering, available, unknown. Speaking is not stored: it is the live
|
|
798
|
+
* message.delta stream itself.
|
|
799
|
+
*/
|
|
800
|
+
export const activityStateSchema = z.enum(['offline', 'available', 'queued', 'working', 'reviewing', 'asking', 'waiting', 'paused', 'blocked', 'delivering', 'unknown']);
|
|
801
|
+
export const activitySchema = z.object({
|
|
802
|
+
binding_id: bindingIdSchema,
|
|
803
|
+
agent_ref: agentRefSchema,
|
|
804
|
+
state: activityStateSchema,
|
|
805
|
+
label: z.string(),
|
|
806
|
+
source: z.record(z.string(), z.unknown()),
|
|
807
|
+
since: isoDate,
|
|
808
|
+
});
|
|
809
|
+
// ── Deliverable review ──
|
|
810
|
+
/** A received revision's review status. Distinct from the task that produced it and from the file's receipt. */
|
|
811
|
+
export const reviewStatusSchema = z.enum(['unreviewed', 'changes_requested', 'accepted', 'rejected', 'superseded']);
|
|
812
|
+
export const deliverableRevisionSchema = z.object({
|
|
813
|
+
id: revisionIdSchema,
|
|
814
|
+
deliverable_id: deliverableIdSchema,
|
|
815
|
+
revision: z.number().int(),
|
|
816
|
+
/** Download through GET /blobs/{sha256}. */
|
|
817
|
+
blob_sha256: sha256Schema,
|
|
818
|
+
mime: z.string(),
|
|
819
|
+
size: z.number().int(),
|
|
820
|
+
producer_binding_id: bindingIdSchema.nullable(),
|
|
821
|
+
source_task_id: taskIdSchema.nullable(),
|
|
822
|
+
source_message_id: messageIdSchema.nullable(),
|
|
823
|
+
/** The Ardent registration: agent_ref, artifact_id, task_id and the full artifact manifest. */
|
|
824
|
+
ardent: z.record(z.string(), z.unknown()).nullable(),
|
|
825
|
+
supersedes_revision_id: revisionIdSchema.nullable(),
|
|
826
|
+
received_at: isoDate,
|
|
827
|
+
review_status: reviewStatusSchema,
|
|
828
|
+
});
|
|
829
|
+
export const deliverableSchema = z.object({
|
|
830
|
+
id: deliverableIdSchema,
|
|
831
|
+
project_id: projectIdSchema,
|
|
832
|
+
requested_deliverable_id: requestedDeliverableIdSchema.nullable(),
|
|
833
|
+
name: z.string(),
|
|
834
|
+
kind: z.string(),
|
|
835
|
+
producer_role: z.string().nullable(),
|
|
836
|
+
final_revision_id: revisionIdSchema.nullable(),
|
|
837
|
+
created_at: isoDate,
|
|
838
|
+
updated_at: isoDate,
|
|
839
|
+
revisions: z.array(deliverableRevisionSchema),
|
|
840
|
+
comments: z.object({ open: z.number().int(), resolved: z.number().int() }),
|
|
841
|
+
});
|
|
842
|
+
/** An artifact an agent registered. pending: being streamed in; failed: not stored (error says why, such as a digest mismatch). */
|
|
843
|
+
export const artifactImportSchema = z.object({
|
|
844
|
+
artifact_id: z.string(),
|
|
845
|
+
task_id: taskIdSchema,
|
|
846
|
+
agent_ref: agentRefSchema,
|
|
847
|
+
name: z.string(),
|
|
848
|
+
mime: z.string(),
|
|
849
|
+
size: z.number().int(),
|
|
850
|
+
sha256: sha256Schema,
|
|
851
|
+
state: z.enum(['pending', 'imported', 'failed']),
|
|
852
|
+
attempts: z.number().int(),
|
|
853
|
+
error: z.string().nullable(),
|
|
854
|
+
revision_id: revisionIdSchema.nullable(),
|
|
855
|
+
updated_at: isoDate,
|
|
856
|
+
});
|
|
857
|
+
export const listDeliverablesResponseSchema = z.object({ deliverables: z.array(deliverableSchema), imports: z.array(artifactImportSchema) });
|
|
858
|
+
export const deliverableResponseSchema = deliverableSchema;
|
|
859
|
+
const unit = z.number().min(0).max(1);
|
|
860
|
+
/**
|
|
861
|
+
* Where a comment points. text: UTF-16 offsets into the revision decoded as UTF-8, with the quoted
|
|
862
|
+
* text and the revision digest (Markdown, plain text, CSV, JSON, SVG source). docx: a paragraph of
|
|
863
|
+
* the stored conversion. pdf: a page, with an optional normalized rectangle and quote. image: a
|
|
864
|
+
* normalized region, with SVG viewBox coordinates when known. file: the whole file.
|
|
865
|
+
*/
|
|
866
|
+
export const commentAnchorSchema = z.discriminatedUnion('kind', [
|
|
867
|
+
z.object({ kind: z.literal('text'), start: z.number().int().min(0), end: z.number().int().min(0), quote: z.string().max(4_000), source_sha256: sha256Schema }).strict(),
|
|
868
|
+
z.object({ kind: z.literal('docx'), paragraph_id: z.string().regex(/^[A-Za-z0-9_:-]{1,128}$/), start: z.number().int().min(0), end: z.number().int().min(0), quote: z.string().max(4_000) }).strict(),
|
|
869
|
+
z.object({ kind: z.literal('pdf'), page: z.number().int().min(1).max(10_000), rect: z.object({ x: unit, y: unit, w: unit, h: unit }).strict().optional(), quote: z.string().max(4_000).optional() }).strict(),
|
|
870
|
+
z.object({ kind: z.literal('image'), x: unit, y: unit, w: unit, h: unit,
|
|
871
|
+
viewbox: z.object({ x: z.number(), y: z.number(), w: z.number().positive(), h: z.number().positive() }).strict().optional() }).strict(),
|
|
872
|
+
z.object({ kind: z.literal('file') }).strict(),
|
|
873
|
+
]);
|
|
874
|
+
export const reviewCommentSchema = z.object({
|
|
875
|
+
id: commentIdSchema,
|
|
876
|
+
project_id: projectIdSchema,
|
|
877
|
+
revision_id: revisionIdSchema,
|
|
878
|
+
anchor: commentAnchorSchema,
|
|
879
|
+
body_md: z.string(),
|
|
880
|
+
author: z.string(),
|
|
881
|
+
state: z.enum(['open', 'resolved']),
|
|
882
|
+
/** The revision task this comment was sent with. */
|
|
883
|
+
revision_task_id: taskIdSchema.nullable(),
|
|
884
|
+
/** The revision that came back from that task. Resolving stays a person's choice. */
|
|
885
|
+
addressed_in_revision_id: revisionIdSchema.nullable(),
|
|
886
|
+
created_at: isoDate,
|
|
887
|
+
resolved_at: isoDate.nullable(),
|
|
888
|
+
updated_at: isoDate.nullable(),
|
|
889
|
+
});
|
|
890
|
+
export const createCommentRequestSchema = z.object({ anchor: commentAnchorSchema, body_md: z.string().trim().min(1).max(20_000) }).strict();
|
|
891
|
+
export const listCommentsResponseSchema = z.object({ comments: z.array(reviewCommentSchema) });
|
|
892
|
+
export const commentResponseSchema = reviewCommentSchema;
|
|
893
|
+
export const reviewDecisionKindSchema = z.enum(['accepted', 'changes_requested', 'rejected']);
|
|
894
|
+
export const reviewDecisionSchema = z.object({
|
|
895
|
+
id: reviewDecisionIdSchema,
|
|
896
|
+
project_id: projectIdSchema,
|
|
897
|
+
revision_id: revisionIdSchema,
|
|
898
|
+
decision: reviewDecisionKindSchema,
|
|
899
|
+
note_md: z.string(),
|
|
900
|
+
decided_by: z.string(),
|
|
901
|
+
created_at: isoDate,
|
|
902
|
+
});
|
|
903
|
+
export const createReviewDecisionRequestSchema = z.object({ decision: reviewDecisionKindSchema, note_md: z.string().max(20_000).default('') }).strict();
|
|
904
|
+
export const reviewDecisionResponseSchema = reviewDecisionSchema;
|
|
905
|
+
export const revisionDetailResponseSchema = z.object({
|
|
906
|
+
revision: deliverableRevisionSchema,
|
|
907
|
+
deliverable: deliverableSchema,
|
|
908
|
+
comments: z.array(reviewCommentSchema),
|
|
909
|
+
decisions: z.array(reviewDecisionSchema),
|
|
910
|
+
});
|
|
911
|
+
export const setFinalRequestSchema = z.object({ revision_id: revisionIdSchema }).strict();
|
|
912
|
+
export const revisionRequestSchema = z.object({
|
|
913
|
+
/** Comments on revisions of one deliverable. */
|
|
914
|
+
comment_ids: z.array(commentIdSchema).min(1).max(50).refine(value => new Set(value).size === value.length, 'Duplicate comment'),
|
|
915
|
+
/** Defaults to the deliverable's producer role. */
|
|
916
|
+
role_key: roleKeySchema.optional(),
|
|
917
|
+
instructions_md: z.string().max(20_000).default(''),
|
|
918
|
+
}).strict();
|
|
919
|
+
export const revisionRequestResponseSchema = z.object({ message: messageSchema, task: taskSchema, comments: z.array(reviewCommentSchema) });
|
|
920
|
+
export const exportRecordSchema = z.object({
|
|
921
|
+
id: exportIdSchema,
|
|
922
|
+
project_id: projectIdSchema,
|
|
923
|
+
revision_ids: z.array(revisionIdSchema),
|
|
924
|
+
/** The zip: download through GET /blobs/{sha256}. */
|
|
925
|
+
blob_sha256: sha256Schema,
|
|
926
|
+
manifest: z.record(z.string(), z.unknown()),
|
|
927
|
+
created_by: z.string(),
|
|
928
|
+
created_at: isoDate,
|
|
929
|
+
});
|
|
930
|
+
export const createExportRequestSchema = z.object({ deliverable_ids: z.array(deliverableIdSchema).min(1).max(200).optional() }).strict();
|
|
931
|
+
export const listExportsResponseSchema = z.object({ exports: z.array(exportRecordSchema) });
|
|
932
|
+
export const exportResponseSchema = exportRecordSchema;
|
|
933
|
+
/** A DOCX converted by the canvas Word codec, stored once per file or revision so paragraph ids stay stable. */
|
|
934
|
+
export const docxDocumentResponseSchema = z.object({
|
|
935
|
+
source: z.object({ kind: z.enum(['file', 'revision']), id: z.string() }),
|
|
936
|
+
blob_sha256: sha256Schema,
|
|
937
|
+
codec: z.string(),
|
|
938
|
+
codec_version: z.string(),
|
|
939
|
+
document_sha256: sha256Schema,
|
|
940
|
+
paragraphs: z.array(z.object({ id: z.string(), text: z.string() })),
|
|
941
|
+
/** The exchange document and canvas-editor value. */
|
|
942
|
+
document: z.unknown(),
|
|
943
|
+
});
|
|
944
|
+
// ── Agent Studio ──
|
|
945
|
+
export const presentationSchema = z.object({
|
|
946
|
+
agent_ref: agentRefSchema,
|
|
947
|
+
display_name: z.string().nullable(),
|
|
948
|
+
portrait: avatarPresetSchema.nullable(),
|
|
949
|
+
avatar_file_id: fileIdSchema.nullable(),
|
|
950
|
+
updated_by: z.string().nullable(),
|
|
951
|
+
updated_at: isoDate.nullable(),
|
|
952
|
+
});
|
|
953
|
+
export const putPresentationRequestSchema = z.object({
|
|
954
|
+
display_name: z.string().trim().min(1).max(80).nullable(),
|
|
955
|
+
portrait: avatarPresetSchema.nullable(),
|
|
956
|
+
/** A project file uploaded with purpose avatar. */
|
|
957
|
+
avatar_file_id: fileIdSchema.nullable().default(null),
|
|
958
|
+
}).strict();
|
|
959
|
+
const skillName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/);
|
|
960
|
+
/** Unsaved changes to an agent. Each person has one draft per agent; Apply writes it through Magnus. */
|
|
961
|
+
export const agentDraftBodySchema = z.object({
|
|
962
|
+
soul: z.string().min(1).max(131_072).optional(),
|
|
963
|
+
identity: z.string().min(1).max(131_072).optional(),
|
|
964
|
+
/** The complete set of enabled local skills. */
|
|
965
|
+
skills_enabled: z.array(skillName).max(100).optional(),
|
|
966
|
+
/** An Emberpath alias or model name, for Preview. */
|
|
967
|
+
model: z.string().trim().min(1).max(200).optional(),
|
|
968
|
+
}).strict();
|
|
969
|
+
/** The revisions the draft was based on; Apply refuses to overwrite a newer revision. */
|
|
970
|
+
export const agentDraftBaseSchema = z.object({
|
|
971
|
+
soul_revision: sha256Schema.optional(),
|
|
972
|
+
identity_revision: sha256Schema.optional(),
|
|
973
|
+
/** Ardent's configuration revision, needed to change skills and the model. */
|
|
974
|
+
config_revision: sha256Schema.optional(),
|
|
975
|
+
}).strict();
|
|
976
|
+
export const agentDraftSchema = z.object({
|
|
977
|
+
agent_ref: agentRefSchema,
|
|
978
|
+
user_id: z.string(),
|
|
979
|
+
base: agentDraftBaseSchema,
|
|
980
|
+
draft: agentDraftBodySchema,
|
|
981
|
+
created_at: isoDate,
|
|
982
|
+
updated_at: isoDate,
|
|
983
|
+
});
|
|
984
|
+
export const agentDraftResponseSchema = z.object({ draft: agentDraftSchema.nullable() });
|
|
985
|
+
export const putAgentDraftRequestSchema = z.object({
|
|
986
|
+
/**
|
|
987
|
+
* Omitted soul and identity revisions are read from the agent through Magnus, and the configuration
|
|
988
|
+
* revision too when the draft changes skills or the model (reading it needs a Magnus ADMIN).
|
|
989
|
+
*/
|
|
990
|
+
base: agentDraftBaseSchema.default({}),
|
|
991
|
+
draft: agentDraftBodySchema,
|
|
992
|
+
}).strict();
|
|
993
|
+
export const previewRequestSchema = z.object({
|
|
994
|
+
prompt: z.string().trim().min(1).max(16_000),
|
|
995
|
+
/** Run with this person's draft (soul, identity, skills, model) instead of the saved agent. */
|
|
996
|
+
use_draft: z.boolean().default(true),
|
|
997
|
+
/** Start a fresh preview conversation instead of continuing the last one. */
|
|
998
|
+
new_session: z.boolean().default(false),
|
|
999
|
+
}).strict();
|
|
1000
|
+
export const previewAcceptedEventSchema = z.object({ task_id: z.string(), session_id: z.string().nullable() });
|
|
1001
|
+
export const previewTextEventSchema = z.object({ step: z.number().int(), text: z.string() });
|
|
1002
|
+
/** Journal progress only (sequence and kind); details stay in Ardent. */
|
|
1003
|
+
export const previewJournalEventSchema = z.object({ sequence: z.number().int(), kind: z.string() });
|
|
1004
|
+
export const previewDoneEventSchema = z.object({ task_id: z.string(), state: z.string(), result: z.string().nullable(), error: z.string().nullable() });
|
|
1005
|
+
export const previewErrorEventSchema = z.object({ code: z.string(), message: z.string() });
|
|
1006
|
+
export const APPLY_PARTS = ['soul', 'identity', 'skills', 'model'];
|
|
1007
|
+
export const applyRequestSchema = z.object({
|
|
1008
|
+
parts: z.array(z.enum(APPLY_PARTS)).min(1).max(APPLY_PARTS.length).refine(value => new Set(value).size === value.length, 'Duplicate part'),
|
|
1009
|
+
}).strict();
|
|
1010
|
+
/**
|
|
1011
|
+
* Codes of a failed part besides Magnus's own: ACTING_ADMIN_REQUIRED and ACTING_SUBJECT_UNLINKED (the
|
|
1012
|
+
* person is not a linked Magnus ADMIN), CONFIG_PATH_FORBIDDEN, CONFLICT (the agent changed since the
|
|
1013
|
+
* draft's base revision), INVALID_INPUT (Magnus or Ardent rejected the value), BASE_REVISION_MISSING,
|
|
1014
|
+
* CONFIG_REVISION_REQUIRED, UNKNOWN_SKILL and CONFIG_UNREADABLE.
|
|
1015
|
+
*/
|
|
1016
|
+
export const applyResultSchema = z.object({
|
|
1017
|
+
part: z.enum(APPLY_PARTS),
|
|
1018
|
+
/** applied; unchanged (the draft has no change for it); failed (error and code say why); unsupported (Studio cannot change it; use the Magnus console). */
|
|
1019
|
+
status: z.enum(['applied', 'unchanged', 'failed', 'unsupported']),
|
|
1020
|
+
error: z.string().nullable(),
|
|
1021
|
+
code: z.string().nullable(),
|
|
1022
|
+
/** The new Ardent revision when applied (the identity file's, or the configuration's for skills and model). */
|
|
1023
|
+
revision: z.string().nullable(),
|
|
1024
|
+
/** The applied change takes effect only after the agent's profile restarts (skills and model). */
|
|
1025
|
+
activation_required: z.boolean(),
|
|
1026
|
+
});
|
|
1027
|
+
export const applyResponseSchema = z.object({
|
|
1028
|
+
results: z.array(applyResultSchema),
|
|
1029
|
+
/** Studio tasks still running on this agent; they keep the instructions they started with. */
|
|
1030
|
+
active_tasks: z.number().int(),
|
|
1031
|
+
note: z.string().nullable(),
|
|
1032
|
+
/** What is left of the draft: applied parts are removed from it. */
|
|
1033
|
+
draft: agentDraftSchema.nullable(),
|
|
1034
|
+
/** Some applied change waits for a profile restart. */
|
|
1035
|
+
activation_required: z.boolean(),
|
|
1036
|
+
/**
|
|
1037
|
+
* Whether Studio can restart the profile. Magnus does not let Studio's service identity run
|
|
1038
|
+
* service-restart, so available is false and reason says to restart it from the Magnus console.
|
|
1039
|
+
*/
|
|
1040
|
+
restart: z.object({ available: z.boolean(), reason: z.string().nullable() }),
|
|
1041
|
+
});
|
|
1042
|
+
/**
|
|
1043
|
+
* POST /agents/{agentRef}/skills/install: a HiveSkills catalog release (the slug and the version promoted on
|
|
1044
|
+
* the channel) that Magnus fetches, checks against the catalog digest and installs onto the agent. With
|
|
1045
|
+
* enable, revision is the agent's configuration revision and the skill is enabled in the same step.
|
|
1046
|
+
*/
|
|
1047
|
+
export const installSkillRequestSchema = z.object({
|
|
1048
|
+
source: z.literal('hiveskills'),
|
|
1049
|
+
name: z.string().regex(/^[a-z0-9][a-z0-9-]{1,62}$/),
|
|
1050
|
+
version: z.string().max(64).regex(/^v?\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i),
|
|
1051
|
+
channel: z.enum(['stable', 'canary']).optional(),
|
|
1052
|
+
enable: z.boolean().optional(),
|
|
1053
|
+
revision: z.string().regex(/^[a-f0-9]{64}$/).optional(),
|
|
1054
|
+
}).strict().refine(value => !value.enable || value.revision !== undefined, { message: 'enable needs the configuration revision', path: ['revision'] });
|
|
1055
|
+
/**
|
|
1056
|
+
* What Magnus installed. changed is false when the same release was installed already. When enabling was
|
|
1057
|
+
* asked for and failed, the skill stays installed, enabled is false and enable_error says why. revision is
|
|
1058
|
+
* the new configuration revision when the skill was enabled. The change applies once the profile restarts.
|
|
1059
|
+
*/
|
|
1060
|
+
export const installSkillResponseSchema = z.object({
|
|
1061
|
+
source: z.literal('hiveskills'), name: z.string(), version: z.string(), sha256: z.string(), files: z.number().int(),
|
|
1062
|
+
changed: z.boolean(), enabled: z.boolean(), revision: z.string().nullable(), enable_error: z.string().nullable(),
|
|
1063
|
+
activation_required: z.boolean(), note: z.string().nullable(),
|
|
1064
|
+
restart: z.object({ available: z.boolean(), reason: z.string().nullable() }),
|
|
1065
|
+
});
|
|
1066
|
+
export const developmentQuerySchema = z.object({
|
|
1067
|
+
after: z.string().regex(/^[A-Za-z0-9_-]{1,400}$/).optional(),
|
|
1068
|
+
limit: z.string().regex(/^\d{1,3}$/).optional(),
|
|
1069
|
+
kind: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional(),
|
|
1070
|
+
});
|
|
1071
|
+
export const developmentCommentSchema = z.object({ id: z.string(), agent_ref: agentRefSchema, record_ref: z.string(), body_md: z.string(), author: z.string(), created_at: isoDate });
|
|
1072
|
+
/** An Ardent development record. author and epistemic say who reported it: agent_reported records are the agent's own account. */
|
|
1073
|
+
export const developmentRecordSchema = z.object({
|
|
1074
|
+
id: z.string(),
|
|
1075
|
+
agent_ref: z.string(),
|
|
1076
|
+
kind: z.string(),
|
|
1077
|
+
title: z.string(),
|
|
1078
|
+
body: z.string(),
|
|
1079
|
+
author: z.enum(['agent', 'operator', 'runtime']),
|
|
1080
|
+
epistemic: z.enum(['agent_reported', 'operator_reported', 'observed']),
|
|
1081
|
+
before_sha256: sha256Schema.nullable(),
|
|
1082
|
+
after_sha256: sha256Schema.nullable(),
|
|
1083
|
+
sources: z.array(z.object({ kind: z.string(), ref: z.string() })),
|
|
1084
|
+
created_at: z.string(),
|
|
1085
|
+
comments: z.array(developmentCommentSchema),
|
|
1086
|
+
});
|
|
1087
|
+
export const developmentResponseSchema = z.object({
|
|
1088
|
+
/** False when the agent's runtime does not publish development records; reason says why. */
|
|
1089
|
+
supported: z.boolean(),
|
|
1090
|
+
reason: z.string().nullable(),
|
|
1091
|
+
records: z.array(developmentRecordSchema),
|
|
1092
|
+
next: z.string().nullable(),
|
|
1093
|
+
});
|
|
1094
|
+
export const createDevelopmentCommentRequestSchema = z.object({
|
|
1095
|
+
body_md: z.string().trim().min(1).max(8_000),
|
|
1096
|
+
/** Also record the comment in the agent's development history (an operator note). */
|
|
1097
|
+
relay_to_agent: z.boolean().default(false),
|
|
1098
|
+
}).strict();
|
|
1099
|
+
export const createDevelopmentCommentResponseSchema = z.object({ comment: developmentCommentSchema, relayed: z.boolean(), relay_error: z.string().nullable() });
|
|
1100
|
+
const credentialFreeUrl = (value) => {
|
|
1101
|
+
try {
|
|
1102
|
+
const url = new URL(value);
|
|
1103
|
+
return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash;
|
|
1104
|
+
}
|
|
1105
|
+
catch {
|
|
1106
|
+
return false;
|
|
1107
|
+
}
|
|
1108
|
+
};
|
|
1109
|
+
/** An Emberpath alias, or an OpenAI-compatible endpoint and model. Never credentials. */
|
|
1110
|
+
export const newAgentModelSchema = z.union([
|
|
1111
|
+
z.object({ emberpath_alias: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/) }).strict(),
|
|
1112
|
+
z.object({ base_url: z.string().max(2048).refine(credentialFreeUrl, 'Expected an HTTP(S) URL without credentials, query or fragment'), model: z.string().min(1).max(200) }).strict(),
|
|
1113
|
+
]);
|
|
1114
|
+
export const newAgentRequestSchema = z.object({
|
|
1115
|
+
node_id: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
|
|
1116
|
+
profile: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
|
|
1117
|
+
api_port: z.number().int().min(1024).max(65535).optional(),
|
|
1118
|
+
/** An agent template version: its soul, identity, local skills and portrait fill what is not given. */
|
|
1119
|
+
template: templateRefSchema.optional(),
|
|
1120
|
+
soul_md: z.string().min(1).max(131_072).optional(),
|
|
1121
|
+
identity_md: z.string().min(1).max(131_072).optional(),
|
|
1122
|
+
model: newAgentModelSchema,
|
|
1123
|
+
skills: z.array(z.string().regex(/^[A-Za-z0-9_-]{1,100}$/)).max(100).optional(),
|
|
1124
|
+
artifacts_max_bytes: z.number().int().min(1024).max(67_108_864).optional(),
|
|
1125
|
+
/** Relay the operation's progress to this project's stream. */
|
|
1126
|
+
project_id: projectIdSchema.optional(),
|
|
1127
|
+
role_key: roleKeySchema.optional(),
|
|
1128
|
+
}).strict();
|
|
1129
|
+
export const agentOperationStepSchema = z.object({
|
|
1130
|
+
name: z.string(),
|
|
1131
|
+
status: z.enum(['pending', 'running', 'succeeded', 'skipped', 'failed']),
|
|
1132
|
+
started_at: z.string().nullable(),
|
|
1133
|
+
finished_at: z.string().nullable(),
|
|
1134
|
+
receipt: z.record(z.string(), z.unknown()).nullable(),
|
|
1135
|
+
error: z.string().nullable(),
|
|
1136
|
+
});
|
|
1137
|
+
/** A Magnus New Agent operation as Studio relays it. */
|
|
1138
|
+
export const agentOperationSchema = z.object({
|
|
1139
|
+
id: z.string(),
|
|
1140
|
+
agent_ref: agentRefSchema,
|
|
1141
|
+
project_id: projectIdSchema.nullable(),
|
|
1142
|
+
role_key: z.string().nullable(),
|
|
1143
|
+
kind: z.enum(['deploy', 'hivemem']),
|
|
1144
|
+
status: z.enum(['running', 'succeeded', 'failed']),
|
|
1145
|
+
steps: z.array(agentOperationStepSchema),
|
|
1146
|
+
error: z.string().nullable(),
|
|
1147
|
+
attempts: z.number().int(),
|
|
1148
|
+
created_by: z.string(),
|
|
1149
|
+
created_at: z.string(),
|
|
1150
|
+
updated_at: z.string(),
|
|
1151
|
+
completed_at: z.string().nullable(),
|
|
1152
|
+
});
|
|
1153
|
+
export const agentOperationResponseSchema = agentOperationSchema;
|
|
1154
|
+
// ── Project snapshot and stream ──
|
|
1155
|
+
export const snapshotResponseSchema = z.object({
|
|
1156
|
+
/** The stream cursor this snapshot is consistent with: reconnect with ?after=<seq>. */
|
|
1157
|
+
seq: z.number().int(),
|
|
1158
|
+
project: projectSchema,
|
|
1159
|
+
/** The same summary the project list shows: counts and last activity. */
|
|
1160
|
+
summary: projectSummarySchema,
|
|
1161
|
+
files: z.array(fileSchema),
|
|
1162
|
+
/** Link references that are not deleted. */
|
|
1163
|
+
links: z.array(referenceLinkSchema),
|
|
1164
|
+
team: teamStateSchema,
|
|
1165
|
+
conversations: z.array(conversationSchema),
|
|
1166
|
+
/** Active tasks and those waiting for an answer. */
|
|
1167
|
+
tasks: z.array(taskSchema),
|
|
1168
|
+
decisions: z.array(decisionSchema),
|
|
1169
|
+
activity: z.array(activitySchema),
|
|
1170
|
+
layout: roomLayoutSchema.nullable(),
|
|
1171
|
+
/** Team proposals that are still queued or running. */
|
|
1172
|
+
team_proposals: z.array(teamProposalRecordSchema),
|
|
1173
|
+
});
|
|
1174
|
+
export const streamQuerySchema = z.object({ after: z.string().regex(/^\d{1,15}$/).optional() });
|
|
1175
|
+
export const PROJECT_EVENT_TYPES = [
|
|
1176
|
+
'project.created', 'project.updated', 'project.archived', 'project.reopened',
|
|
1177
|
+
'file.created', 'file.updated',
|
|
1178
|
+
'team.draft.updated', 'team.revision.published',
|
|
1179
|
+
'layout.updated', 'conversation.created', 'conversation.updated', 'message.created', 'message.updated',
|
|
1180
|
+
'presence.updated', 'task.created', 'task.updated', 'decision.created', 'decision.updated',
|
|
1181
|
+
'deliverable.revision.created', 'review.comment.created', 'review.comment.updated', 'review.decision.created',
|
|
1182
|
+
'export.created', 'agent.operation.updated', 'deliverable.updated', 'artifact.import.updated',
|
|
1183
|
+
'link.created', 'link.updated', 'link.deleted', 'team.proposal.updated',
|
|
1184
|
+
];
|
|
1185
|
+
export const projectEventTypeSchema = z.enum(PROJECT_EVENT_TYPES);
|
|
1186
|
+
/** A persisted event. The SSE `id` is its seq. */
|
|
1187
|
+
export const projectEventSchema = z.object({
|
|
1188
|
+
seq: z.number().int(),
|
|
1189
|
+
project_id: projectIdSchema,
|
|
1190
|
+
type: projectEventTypeSchema,
|
|
1191
|
+
at: isoDate,
|
|
1192
|
+
payload: z.record(z.string(), z.unknown()),
|
|
1193
|
+
});
|
|
1194
|
+
export const resetEventSchema = z.object({ seq: z.number().int(), reason: z.enum(['cursor_expired', 'cursor_ahead']) });
|
|
1195
|
+
export const heartbeatEventSchema = z.object({ seq: z.number().int(), at: isoDate });
|
|
1196
|
+
/**
|
|
1197
|
+
* Live reply text, never persisted or replayed. mode append adds text to the message's current
|
|
1198
|
+
* step; replace sets the whole step (a new step, or a snapshot sent when a stream connects).
|
|
1199
|
+
* The stored message (message.updated) replaces it when the turn ends.
|
|
1200
|
+
*/
|
|
1201
|
+
export const messageDeltaEventSchema = z.object({ message_id: z.string(), text: z.string(), mode: z.enum(['append', 'replace']).optional(), step: z.number().int().optional() });
|
|
1202
|
+
// ── Health ──
|
|
1203
|
+
const checkSchema = z.object({ status: z.enum(['ok', 'unavailable']), error: z.string().nullable() });
|
|
1204
|
+
export const liveResponseSchema = z.object({ status: z.literal('ok') });
|
|
1205
|
+
export const readyResponseSchema = z.object({
|
|
1206
|
+
status: z.enum(['ready', 'not_ready']),
|
|
1207
|
+
checks: z.object({
|
|
1208
|
+
database: checkSchema,
|
|
1209
|
+
magnus: checkSchema,
|
|
1210
|
+
hivemem: checkSchema,
|
|
1211
|
+
agents: z.object({ status: z.enum(['ok', 'unavailable']), available: z.number().int() }),
|
|
1212
|
+
}),
|
|
1213
|
+
});
|
|
1214
|
+
const READ = ['ardentstudio:projects:read'];
|
|
1215
|
+
const WRITE = ['ardentstudio:projects:write'];
|
|
1216
|
+
const TEMPLATES_READ = ['ardentstudio:templates:read'];
|
|
1217
|
+
const TEMPLATES_WRITE = ['ardentstudio:templates:write'];
|
|
1218
|
+
const REVIEW = ['ardentstudio:review:write'];
|
|
1219
|
+
const AGENTS_ADMIN = ['ardentstudio:agents:admin'];
|
|
1220
|
+
export const ardentStudioBrowserRoutes = [
|
|
1221
|
+
// Health
|
|
1222
|
+
{ method: 'GET', path: '/health/live', response: liveResponseSchema, permissions: [], idempotent: false },
|
|
1223
|
+
{ method: 'GET', path: '/health/ready', response: readyResponseSchema, permissions: [], idempotent: false, note: 'Answers 503 with the same body when not ready. Checks are cached for 10 seconds.' },
|
|
1224
|
+
// Projects
|
|
1225
|
+
{ method: 'GET', path: '/projects', query: listProjectsQuerySchema, response: listProjectsResponseSchema, permissions: READ, idempotent: false, note: 'q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0.' },
|
|
1226
|
+
{ method: 'POST', path: '/projects', requestBody: 'json', request: createProjectRequestSchema, response: projectResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Creates the project HiveMem workspace; when HiveMem is unavailable hivemem.state stays pending and is retried.' },
|
|
1227
|
+
{ method: 'GET', path: '/projects/{projectId}', response: projectResponseSchema, permissions: READ, idempotent: false },
|
|
1228
|
+
{ method: 'PATCH', path: '/projects/{projectId}', requestBody: 'json', request: updateProjectRequestSchema, response: projectResponseSchema, permissions: WRITE, idempotent: true, note: 'An archived project is read-only (409) except last_area.' },
|
|
1229
|
+
{ method: 'POST', path: '/projects/{projectId}/archive', response: projectResponseSchema, permissions: WRITE, idempotent: true, note: '409 with details.tasks while Studio tasks are still active.' },
|
|
1230
|
+
{ method: 'POST', path: '/projects/{projectId}/reopen', response: projectResponseSchema, permissions: WRITE, idempotent: true },
|
|
1231
|
+
{ method: 'GET', path: '/projects/{projectId}/snapshot', response: snapshotResponseSchema, permissions: READ, idempotent: false },
|
|
1232
|
+
// Reference links
|
|
1233
|
+
{ method: 'POST', path: '/projects/{projectId}/links', requestBody: 'json', request: createLinkRequestSchema, response: linkResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'http and https only, without credentials. 409 LINK_EXISTS when the project already has this URL. Synced to the project HiveMem workspace as a knowledge source (title, URL and note; the page is not fetched).' },
|
|
1234
|
+
{ method: 'GET', path: '/projects/{projectId}/links', response: listLinksResponseSchema, permissions: READ, idempotent: false, note: 'Links that are not deleted.' },
|
|
1235
|
+
{ method: 'PATCH', path: '/links/{linkId}', requestBody: 'json', request: updateLinkRequestSchema, response: linkResponseSchema, permissions: WRITE, idempotent: true, note: 'A change queues the link for HiveMem sync again.' },
|
|
1236
|
+
{ method: 'DELETE', path: '/links/{linkId}', response: linkResponseSchema, permissions: WRITE, idempotent: true, note: 'Marks the link deleted and retires its HiveMem source.' },
|
|
1237
|
+
{ method: 'POST', path: '/links/{linkId}/reindex', response: linkResponseSchema, permissions: WRITE, idempotent: true, note: 'Queues the link for HiveMem sync again.' },
|
|
1238
|
+
// Files
|
|
1239
|
+
{ method: 'POST', path: '/projects/{projectId}/files', query: uploadFileQuerySchema, requestBody: 'raw', response: fileResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Raw body up to ARDENT_STUDIO_MAX_BLOB_BYTES (default 64 MiB) with an allowed Content-Type (UPLOAD_MIME_TYPES). References are indexed into the project HiveMem workspace.' },
|
|
1240
|
+
{ method: 'GET', path: '/projects/{projectId}/files', query: listFilesQuerySchema, response: listFilesResponseSchema, permissions: READ, idempotent: false },
|
|
1241
|
+
{ method: 'GET', path: '/blobs/{sha256}', response: null, permissions: READ, idempotent: false, note: 'Bytes as application/octet-stream with Content-Disposition attachment; the recorded type is in X-Blob-Mime. Only blobs that a project file, a deliverable revision or an export references are served.' },
|
|
1242
|
+
{ method: 'POST', path: '/files/{fileId}/reindex', response: fileResponseSchema, permissions: WRITE, idempotent: true, note: 'Queues the file for HiveMem sync again.' },
|
|
1243
|
+
// Templates
|
|
1244
|
+
{ method: 'GET', path: '/templates', query: listTemplatesQuerySchema, response: listTemplatesResponseSchema, permissions: TEMPLATES_READ, idempotent: false },
|
|
1245
|
+
{ method: 'GET', path: '/templates/{templateId}', response: templateDetailSchema, permissions: TEMPLATES_READ, idempotent: false },
|
|
1246
|
+
{ method: 'GET', path: '/templates/{templateId}/versions/{version}', response: templateVersionSchema, permissions: TEMPLATES_READ, idempotent: false },
|
|
1247
|
+
{ method: 'POST', path: '/templates', requestBody: 'json', request: createTemplateRequestSchema, response: templateDetailSchema, permissions: TEMPLATES_WRITE, idempotent: true, successStatus: 201, note: 'Templates never carry secrets; values that look like credentials are rejected.' },
|
|
1248
|
+
{ method: 'POST', path: '/templates/{templateId}/versions', requestBody: 'json', request: createTemplateVersionRequestSchema, response: templateDetailSchema, permissions: TEMPLATES_WRITE, idempotent: true, successStatus: 201, note: 'Versions are immutable. 409 when base_version is not the latest.' },
|
|
1249
|
+
{ method: 'POST', path: '/templates/{templateId}/archive', requestBody: 'json', request: archiveTemplateRequestSchema, response: templateDetailSchema, permissions: TEMPLATES_WRITE, idempotent: true },
|
|
1250
|
+
// Team assignment
|
|
1251
|
+
{ method: 'GET', path: '/projects/{projectId}/team', response: teamStateSchema, permissions: READ, idempotent: false },
|
|
1252
|
+
{ method: 'PUT', path: '/projects/{projectId}/team/draft', requestBody: 'json', request: putTeamDraftRequestSchema, response: teamStateSchema, permissions: WRITE, idempotent: true },
|
|
1253
|
+
{ method: 'POST', path: '/projects/{projectId}/team/validate', requestBody: 'json', request: validateTeamRequestSchema, response: validationResultSchema, permissions: READ, idempotent: false, note: 'Validates the given body, else the draft, else the current revision. No side effects.' },
|
|
1254
|
+
{ method: 'POST', path: '/projects/{projectId}/team/publish', requestBody: 'json', request: publishTeamRequestSchema, response: teamStateSchema, permissions: WRITE, idempotent: true, note: '409 with details.validation when the draft has errors.' },
|
|
1255
|
+
{ method: 'POST', path: '/projects/{projectId}/team/apply-template', requestBody: 'json', request: applyTemplateRequestSchema, response: teamStateSchema, permissions: WRITE, idempotent: true },
|
|
1256
|
+
{ method: 'POST', path: '/projects/{projectId}/team/propose', requestBody: 'json', request: proposeTeamRequestSchema, response: teamProposalResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Asks one agent through Magnus (a mission at studio level 2 with Ardent 2.2.0, else task-submit) for a TeamProposal JSON reply with the brief, deliverables, templates and available agents. An invalid reply is retried once with the validation error, then the proposal fails. Progress arrives as team.proposal.updated; nothing is applied. 409 NO_COORDINATOR without agent_ref and a bound coordinator, 409 PROPOSAL_IN_PROGRESS while one is queued or running, 422 UNKNOWN_AGENT, 409 AGENT_UNAVAILABLE, 503 MAGNUS_UNAVAILABLE.' },
|
|
1257
|
+
{ method: 'GET', path: '/projects/{projectId}/team/proposals', response: listTeamProposalsResponseSchema, permissions: READ, idempotent: false, note: 'Newest first, at most 20.' },
|
|
1258
|
+
{ method: 'GET', path: '/projects/{projectId}/team/proposals/{proposalId}', response: teamProposalResponseSchema, permissions: READ, idempotent: false },
|
|
1259
|
+
{ method: 'POST', path: '/projects/{projectId}/team/save-as-template', requestBody: 'json', request: saveAsTemplateRequestSchema, response: templateDetailSchema, permissions: ['ardentstudio:projects:read', 'ardentstudio:templates:write'], idempotent: true, successStatus: 201, note: 'Bindings and knowledge are not copied.' },
|
|
1260
|
+
// Agents
|
|
1261
|
+
{ method: 'GET', path: '/agents', response: listAgentsResponseSchema, permissions: READ, idempotent: false, note: 'Magnus-managed Ardent profiles. When Magnus is unavailable the list is empty and magnus.state says so.' },
|
|
1262
|
+
{ method: 'POST', path: '/agents', requestBody: 'json', request: newAgentRequestSchema, response: agentOperationResponseSchema, permissions: AGENTS_ADMIN, idempotent: true, successStatus: 201, note: 'Magnus New Agent with the acting person: Magnus also requires that person to be a Magnus ADMIN (403 ACTING_ADMIN_REQUIRED). The agent always gets HiveMem. Progress is relayed as agent.operation.updated on project_id\'s stream.' },
|
|
1263
|
+
{ method: 'GET', path: '/agents/operations/{operationId}', response: agentOperationResponseSchema, permissions: READ, idempotent: false, note: 'Operations started from Studio. Magnus\'s current view, or the last relayed one when Magnus is unreachable.' },
|
|
1264
|
+
{ method: 'GET', path: '/agents/{agentRef}/presentation', response: presentationSchema, permissions: READ, idempotent: false },
|
|
1265
|
+
{ method: 'PUT', path: '/agents/{agentRef}/presentation', requestBody: 'json', request: putPresentationRequestSchema, response: presentationSchema, permissions: WRITE, idempotent: true, note: 'Studio-only display name and portrait; the agent itself is unchanged.' },
|
|
1266
|
+
{ method: 'GET', path: '/agents/{agentRef}/draft', response: agentDraftResponseSchema, permissions: READ, idempotent: false, note: 'The calling person\'s draft.' },
|
|
1267
|
+
{ method: 'PUT', path: '/agents/{agentRef}/draft', requestBody: 'json', request: putAgentDraftRequestSchema, response: agentDraftResponseSchema, permissions: WRITE, idempotent: true },
|
|
1268
|
+
{ method: 'DELETE', path: '/agents/{agentRef}/draft', response: agentDraftResponseSchema, permissions: WRITE, idempotent: true },
|
|
1269
|
+
{
|
|
1270
|
+
method: 'POST', path: '/agents/{agentRef}/preview', requestBody: 'json', request: previewRequestSchema, response: null, permissions: WRITE, idempotent: false,
|
|
1271
|
+
events: { 'preview.accepted': previewAcceptedEventSchema, 'preview.text': previewTextEventSchema, 'preview.delta': previewTextEventSchema, 'preview.event': previewJournalEventSchema, 'preview.done': previewDoneEventSchema, 'preview.error': previewErrorEventSchema },
|
|
1272
|
+
note: 'Streams a side-effect-free Ardent preview task (no memory writes, no mission tools, no identity changes, artifacts expire). Needs the agent\'s Magnus node agent at studio level 2: otherwise 409 PREVIEW_UNAVAILABLE. Sending x-idempotency-key again streams the same preview task.',
|
|
1273
|
+
},
|
|
1274
|
+
{ method: 'POST', path: '/agents/{agentRef}/apply', requestBody: 'json', request: applyRequestSchema, response: applyResponseSchema, permissions: AGENTS_ADMIN, idempotent: true, note: 'Applies parts of the calling person\'s draft through Magnus with the acting person, who must be a linked Magnus ADMIN: soul and identity with identity-save, skills with chained skill-set against the saved configuration\'s skills.enabled (the skill list reports the running profile, which a restart updates), the model with config-save of the agent\'s config.yaml changing only the model setting. Each part is checked against its base revision. Results are per part; skill and model changes report activation_required (a profile restart, which Studio cannot run). Running tasks keep their instructions.' },
|
|
1275
|
+
{ method: 'POST', path: '/agents/{agentRef}/skills/install', requestBody: 'json', request: installSkillRequestSchema, response: installSkillResponseSchema, permissions: AGENTS_ADMIN, idempotent: true, note: 'Magnus skill-install with the acting person, who must be a linked Magnus ADMIN (403 ACTING_ADMIN_REQUIRED); the node agent needs studio 3 (409 AGENT_UPGRADE_REQUIRED). Magnus refusals keep their codes: 503 HIVESKILLS_UNCONFIGURED, 409 SKILL_VERSION_UNAVAILABLE, 409 SKILL_CONFLICT (a local skill of that name), 422 SKILL_ARCHIVE_INVALID; a Magnus without the action answers 409 MAGNUS_UPGRADE_REQUIRED.' },
|
|
1276
|
+
{ method: 'GET', path: '/agents/{agentRef}/development', query: developmentQuerySchema, response: developmentResponseSchema, permissions: READ, idempotent: false },
|
|
1277
|
+
{ method: 'POST', path: '/agents/{agentRef}/development/{recordId}/comments', requestBody: 'json', request: createDevelopmentCommentRequestSchema, response: createDevelopmentCommentResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201 },
|
|
1278
|
+
// Room
|
|
1279
|
+
{ method: 'GET', path: '/projects/{projectId}/layout', response: layoutResponseSchema, permissions: READ, idempotent: false },
|
|
1280
|
+
{ method: 'PUT', path: '/projects/{projectId}/layout', requestBody: 'json', request: putLayoutRequestSchema, response: layoutResponseSchema, permissions: WRITE, idempotent: true, note: 'Each save is a new revision. 409 when base_revision is not the latest.' },
|
|
1281
|
+
{ method: 'GET', path: '/projects/{projectId}/conversations', response: listConversationsResponseSchema, permissions: READ, idempotent: false },
|
|
1282
|
+
{ method: 'POST', path: '/projects/{projectId}/conversations', requestBody: 'json', request: createConversationRequestSchema, response: conversationResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'A discussion posts its question and starts round 1 at once: one turn per participant in order, then the next round, then a coordinator summary. Needs a published team with the participants bound (409 TEAM_NOT_READY).' },
|
|
1283
|
+
{ method: 'POST', path: '/conversations/{conversationId}/stop', response: conversationResponseSchema, permissions: WRITE, idempotent: true, note: 'Unstarted turns are cancelled; started ones are cancelled through Magnus.' },
|
|
1284
|
+
{ method: 'GET', path: '/conversations/{conversationId}/messages', query: listMessagesQuerySchema, response: listMessagesResponseSchema, permissions: READ, idempotent: false, note: 'Oldest first after ?after=<seq>; at most 200 (default 100).' },
|
|
1285
|
+
{ method: 'POST', path: '/conversations/{conversationId}/messages', requestBody: 'json', request: postMessageRequestSchema, response: postMessageResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Team or Coordinator starts a coordinator turn; roles or @role_key mentions start one turn per addressee in order. A direct conversation always goes to its role; a discussion takes notes without starting turns. 409 TEAM_NOT_READY without a published team and bound roles.' },
|
|
1286
|
+
{ method: 'POST', path: '/messages/{messageId}/answer', requestBody: 'json', request: answerRequestSchema, response: postMessageResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Answers a clarification: the answer continues the same agent session. 409 when it is already answered.' },
|
|
1287
|
+
{ method: 'POST', path: '/messages/{messageId}/follow-up', requestBody: 'json', request: followUpRequestSchema, response: postMessageResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: "Asks the agent that wrote the message to follow up on it." },
|
|
1288
|
+
// Decisions and tasks
|
|
1289
|
+
{ method: 'GET', path: '/projects/{projectId}/decisions', response: listDecisionsResponseSchema, permissions: READ, idempotent: false },
|
|
1290
|
+
{ method: 'POST', path: '/projects/{projectId}/decisions', requestBody: 'json', request: createDecisionRequestSchema, response: decisionResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Pinning is a person\'s act; an agent can only propose.' },
|
|
1291
|
+
{ method: 'POST', path: '/decisions/{decisionId}/supersede', requestBody: 'json', request: supersedeDecisionRequestSchema, response: decisionResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Creates the new decision and marks this one superseded by it. 409 when it is already superseded.' },
|
|
1292
|
+
{ method: 'GET', path: '/projects/{projectId}/tasks', query: listTasksQuerySchema, response: listTasksResponseSchema, permissions: READ, idempotent: false },
|
|
1293
|
+
{ method: 'POST', path: '/projects/{projectId}/tasks', requestBody: 'json', request: createTaskRequestSchema, response: taskResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201 },
|
|
1294
|
+
{ method: 'POST', path: '/tasks/{taskId}/pause', response: taskResponseSchema, permissions: WRITE, idempotent: true, note: 'A started task pauses at its next step boundary (state pausing, then paused); an unstarted one is held. 409 AGENT_UPGRADE_REQUIRED when the agent cannot pause.' },
|
|
1295
|
+
{ method: 'POST', path: '/tasks/{taskId}/resume', response: taskResponseSchema, permissions: WRITE, idempotent: true },
|
|
1296
|
+
{ method: 'POST', path: '/tasks/{taskId}/cancel', response: taskResponseSchema, permissions: WRITE, idempotent: true },
|
|
1297
|
+
{ method: 'POST', path: '/tasks/{taskId}/reassign', requestBody: 'json', request: reassignTaskRequestSchema, response: taskResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Cancels the task when it is still active and creates the same work for another role, with reassigned_from.' },
|
|
1298
|
+
// Deliverable review
|
|
1299
|
+
{ method: 'GET', path: '/projects/{projectId}/deliverables', response: listDeliverablesResponseSchema, permissions: READ, idempotent: false, note: 'Deliverables with every revision, plus artifact imports that are still pending or failed.' },
|
|
1300
|
+
{ method: 'GET', path: '/deliverables/{deliverableId}', response: deliverableResponseSchema, permissions: READ, idempotent: false },
|
|
1301
|
+
{ method: 'GET', path: '/revisions/{revisionId}', response: revisionDetailResponseSchema, permissions: READ, idempotent: false },
|
|
1302
|
+
{ method: 'GET', path: '/revisions/{revisionId}/comments', response: listCommentsResponseSchema, permissions: READ, idempotent: false },
|
|
1303
|
+
{ method: 'POST', path: '/revisions/{revisionId}/comments', requestBody: 'json', request: createCommentRequestSchema, response: commentResponseSchema, permissions: REVIEW, idempotent: true, successStatus: 201, note: 'The anchor kind must fit the revision type (422 ANCHOR_KIND). A text anchor must quote the revision exactly (422 ANCHOR_MISMATCH) and name its digest (409 ANCHOR_STALE). A docx anchor needs the stored conversion (409 DOCX_NOT_CONVERTED).' },
|
|
1304
|
+
{ method: 'POST', path: '/comments/{commentId}/resolve', response: commentResponseSchema, permissions: REVIEW, idempotent: true },
|
|
1305
|
+
{ method: 'POST', path: '/revisions/{revisionId}/decisions', requestBody: 'json', request: createReviewDecisionRequestSchema, response: reviewDecisionResponseSchema, permissions: REVIEW, idempotent: true, successStatus: 201, note: 'changes_requested needs a note or an open comment (422 NOTE_REQUIRED).' },
|
|
1306
|
+
{ method: 'POST', path: '/deliverables/{deliverableId}/final', requestBody: 'json', request: setFinalRequestSchema, response: deliverableResponseSchema, permissions: REVIEW, idempotent: true, note: 'One final revision per deliverable; a rejected revision cannot be final (409).' },
|
|
1307
|
+
{ method: 'POST', path: '/projects/{projectId}/revision-requests', requestBody: 'json', request: revisionRequestSchema, response: revisionRequestResponseSchema, permissions: ['ardentstudio:review:write', 'ardentstudio:projects:write'], idempotent: true, successStatus: 201, note: 'Starts a revision task for the producer role with the anchored comments as context, and links the comments to it. The revised file comes back as the next revision, superseding this one.' },
|
|
1308
|
+
{ method: 'GET', path: '/projects/{projectId}/exports', response: listExportsResponseSchema, permissions: READ, idempotent: false },
|
|
1309
|
+
{ method: 'POST', path: '/projects/{projectId}/exports', requestBody: 'json', request: createExportRequestSchema, response: exportResponseSchema, permissions: REVIEW, idempotent: true, successStatus: 201, note: 'A zip of the final revisions with manifest.json (Ardent manifest fields, review status and decisions). Deliverables without a final revision are listed as excluded; none at all answers 409 NOTHING_FINAL.' },
|
|
1310
|
+
{ method: 'GET', path: '/files/{fileId}/docx', response: docxDocumentResponseSchema, permissions: READ, idempotent: false, note: 'Answers 501 DOCX_CONVERTER_UNAVAILABLE until the canvas Word codec package is installed.' },
|
|
1311
|
+
{ method: 'GET', path: '/revisions/{revisionId}/docx', response: docxDocumentResponseSchema, permissions: READ, idempotent: false, note: 'Answers 501 DOCX_CONVERTER_UNAVAILABLE until the canvas Word codec package is installed.' },
|
|
1312
|
+
// Stream
|
|
1313
|
+
{
|
|
1314
|
+
method: 'GET', path: '/projects/{projectId}/stream', query: streamQuerySchema, response: null, permissions: READ, idempotent: false,
|
|
1315
|
+
events: { '*': projectEventSchema, reset: resetEventSchema, heartbeat: heartbeatEventSchema, 'message.delta': messageDeltaEventSchema },
|
|
1316
|
+
note: 'Persisted events carry their seq as the SSE id and replay after ?after=. reset means the cursor is older than retained events (or ahead of them): refetch the snapshot. message.delta (live reply text) has no id; on connect each streaming message gets one replace delta with its current text. heartbeat every 15 s. The stream closes when the token expires or its session ends; reconnect with a fresh token.',
|
|
1317
|
+
},
|
|
1318
|
+
];
|