@crossworks/client-types 0.400.11 → 0.400.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.400.11",
3
+ "version": "0.400.14",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -9,7 +9,7 @@
9
9
  "./*": "./src/*.ts"
10
10
  },
11
11
  "devDependencies": {
12
- "@types/node": "^26.6.4"
12
+ "@types/node": "^26.6.5"
13
13
  },
14
14
  "license": "SEE LICENSE IN LICENSE.md",
15
15
  "repository": {
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The login's Desk: where each widget and desk icon sits on the client's
3
+ * grid, and the desk's few settings. Kept on the login's own profile row
4
+ * and served by its own route, GET and PUT /api/profile/home-desk. The
5
+ * CLIENT owns the meaning (which ids exist, each widget's bounds); the brain
6
+ * only keeps the shape sound and the size bounded (projectHomeDesk), so a new
7
+ * widget needs no brain release.
8
+ */
9
+ export type HomeDeskItem = { id: string; x: number; y: number; w: number; h: number };
10
+ export type HomeDesk = {
11
+ v: 1;
12
+ items: HomeDeskItem[];
13
+ /** Items a kind widget lists, by tree kind. */
14
+ counts: Record<string, number>;
15
+ /** Pinned items as desk icons. */
16
+ icons: boolean;
17
+ clock: 'digital' | 'analog';
18
+ };
19
+
20
+ /**
21
+ * GET /api/profile/home-desk, a PUT that landed (200), and a PUT that lost
22
+ * (409, the desk another device saved since): the stored desk and its
23
+ * version. `homeDesk` null and `version` 0 until the login saves one.
24
+ */
25
+ export type HomeDeskState = { homeDesk: HomeDesk | null; version: number };
26
+
27
+ /**
28
+ * PUT /api/profile/home-desk: replace the desk, compare-and-set. `version`
29
+ * is the one this client last read or saved; the save lands (and the
30
+ * version goes up by one) only while the stored version still equals it.
31
+ * `loginId` is the login the desk belongs to (the shell's `loginId`): a save
32
+ * for any login but the session's is a 403 `{ error, code:
33
+ * 'login-mismatch' }`, so a desk is never saved over another login's.
34
+ */
35
+ export type HomeDeskPutBody = { homeDesk: HomeDesk; version: number; loginId: string };
@@ -65,7 +65,7 @@ export type MemberHomeApp = {
65
65
  };
66
66
 
67
67
  /**
68
- * GET /api/member/home: the pinned home app (null = the built-in home, and
68
+ * GET /api/member/home: the pinned home app (null = the built-in Desk, and
69
69
  * then `hub` is null too) and what its `host.hub.get()` answers. A section's
70
70
  * token is a page id; an app card's token is an app id.
71
71
  *
@@ -79,13 +79,13 @@ export type MemberHomeData<THub = unknown> =
79
79
 
80
80
  /**
81
81
  * GET /api/home?ws=<id>: the landing page of a workspace, for every login
82
- * (task d78e7bde). Without `ws` it is "All my workspaces": the Built-in
83
- * home over every workspace of the login, never a home app.
82
+ * (task d78e7bde). Without `ws` it is "All my workspaces": the built-in
83
+ * Desk over every workspace of the login, never a home app.
84
84
  *
85
85
  * `ws` echoes the workspace asked for (null: all). `homeApp` is the
86
86
  * workspace's home app when the workspace still holds it, its published
87
- * build is green and the login may run it; null means the Built-in home.
88
- * `hub` is always there: the data of the Built-in home and what a home
87
+ * build is green and the login may run it; null means the built-in Desk.
88
+ * `hub` is always there: the data of the built-in Desk and what a home
89
89
  * app's `host.hub.get()` answers, read in the login's scope and kept to
90
90
  * what the workspace reads (sections are its newest pages, counts its items
91
91
  * per kind, apps the other apps it holds that the login may run). A
@@ -0,0 +1,200 @@
1
+ /**
2
+ * The messenger (Messenger V1, plan page d8954876, sections 11 and 12):
3
+ * direct chats and groups between the logins of one brain, under
4
+ * /api/messenger/*. The chat with an assistant stays in assistant_messages;
5
+ * the list shows each such thread as a row of kind 'agent' beside the
6
+ * people chats.
7
+ *
8
+ * Every number that orders a chat is a seq: the conversation's last_seq,
9
+ * a message's seq, a participant's read cursor. Clocks never order.
10
+ */
11
+
12
+ /** A conversation: two logins, or a group. */
13
+ export type MessengerConversationKind = 'direct' | 'group';
14
+
15
+ /** A row of the one list: a people chat, a group, or an agent thread. */
16
+ export type MessengerRowKind = MessengerConversationKind | 'agent';
17
+
18
+ export type MessengerAuthorKind = 'login' | 'agent' | 'system';
19
+
20
+ export type MessengerParticipantKind = 'login' | 'agent';
21
+
22
+ /** An agent reply's state (Phase 3); a person's message is always
23
+ * 'complete'. */
24
+ export type MessengerMessageStatus = 'complete' | 'pending' | 'failed';
25
+
26
+ /** The last line of a conversation, kept in its row by the send. */
27
+ export type MessengerPreview = {
28
+ authorName: string | null;
29
+ /** The first 140 characters of the body ('' for a deleted message). */
30
+ text: string;
31
+ authorKind: MessengerAuthorKind;
32
+ };
33
+
34
+ export type MessengerParticipant = {
35
+ kind: MessengerParticipantKind;
36
+ /** The login id or the agent id. */
37
+ id: string;
38
+ name: string;
39
+ /** A group admin. */
40
+ admin: boolean;
41
+ /** ISO, or null while the participant is in the chat. */
42
+ leftAt: string | null;
43
+ };
44
+
45
+ /** One row of GET /api/messenger/conversations. */
46
+ export type MessengerListRow = {
47
+ kind: MessengerRowKind;
48
+ /** The conversation id, or the agent id for an agent thread. */
49
+ id: string;
50
+ title: string;
51
+ /** null for an agent thread (its order is by time). */
52
+ lastSeq: number | null;
53
+ /** ISO, null when nothing was said yet. */
54
+ lastMessageAt: string | null;
55
+ preview: MessengerPreview | null;
56
+ unread: number;
57
+ /** A message mentions me past my read cursor. */
58
+ mention: boolean;
59
+ muted: boolean;
60
+ favourite: boolean;
61
+ /** People and the group's agent; empty for an agent thread. */
62
+ participants: MessengerParticipant[];
63
+ /** An agent thread's agent slug (it opens today's chat screen). */
64
+ agentSlug?: string;
65
+ };
66
+
67
+ export type MessengerListResponse = { rows: MessengerListRow[] };
68
+
69
+ /** GET /api/messenger/c/:id. */
70
+ export type MessengerConversation = {
71
+ id: string;
72
+ kind: MessengerConversationKind;
73
+ title: string | null;
74
+ createdBy: string | null;
75
+ createdAt: string;
76
+ archivedAt: string | null;
77
+ lastSeq: number;
78
+ lastMessageAt: string | null;
79
+ /** The bound workspace (Phase 3), or null. */
80
+ workspaceId: string | null;
81
+ /** The group's agent (Phase 3), or null. */
82
+ agentId: string | null;
83
+ participants: MessengerParticipant[];
84
+ /** My own participant row. */
85
+ me: {
86
+ admin: boolean;
87
+ lastReadSeq: number;
88
+ clearedBeforeSeq: number;
89
+ muted: boolean;
90
+ /** Set once I left: I read up to here and nothing after. */
91
+ leftSeq: number | null;
92
+ };
93
+ };
94
+
95
+ export type MessengerMention = { kind: MessengerParticipantKind; id: string };
96
+
97
+ export type MessengerReaction = { emoji: string; count: number; mine: boolean };
98
+
99
+ export type MessengerMessage = {
100
+ id: string;
101
+ conversationId: string;
102
+ seq: number;
103
+ authorKind: MessengerAuthorKind;
104
+ /** The login or agent id; null for a system line. */
105
+ authorId: string | null;
106
+ /** The author's name when the message was sent. */
107
+ authorName: string | null;
108
+ /** How it was sent: an OAuth client name, a key label, a peer name. */
109
+ via: string | null;
110
+ /** '' once deleted. */
111
+ body: string;
112
+ /** Attachment ids (Phase 4). */
113
+ attachments: string[];
114
+ mentions: MessengerMention[];
115
+ replyToSeq: number | null;
116
+ clientMsgId: string | null;
117
+ status: MessengerMessageStatus;
118
+ editedAt: string | null;
119
+ deletedAt: string | null;
120
+ createdAt: string;
121
+ reactions: MessengerReaction[];
122
+ };
123
+
124
+ /** GET /api/messenger/c/:id/messages: oldest first in the window, `limit`
125
+ * (default 20, at most 100) at a time. */
126
+ export type MessengerMessagesResponse = {
127
+ messages: MessengerMessage[];
128
+ /** The last seq I may read; with after_seq and `hasMore`, the highest seq
129
+ * of this page instead (the next after_seq). */
130
+ lastSeq: number;
131
+ /** More messages exist past this page: below the lowest seq returned
132
+ * (no cursor, or before_seq), or above the highest (after_seq). */
133
+ hasMore: boolean;
134
+ };
135
+
136
+ /** POST /api/messenger/conversations. */
137
+ export type MessengerCreateRequest = {
138
+ kind: MessengerConversationKind;
139
+ /** Login ids besides me. A direct chat names exactly one; a group may
140
+ * name none (a group of one, "message yourself"). */
141
+ participants: string[];
142
+ title?: string;
143
+ };
144
+
145
+ export type MessengerCreateResponse = {
146
+ conversation: MessengerConversation;
147
+ /** false when a direct chat with that login already existed. */
148
+ created: boolean;
149
+ };
150
+
151
+ /** POST /api/messenger/c/:id/messages. */
152
+ export type MessengerSendRequest = {
153
+ body: string;
154
+ mentions?: MessengerMention[];
155
+ replyToSeq?: number | null;
156
+ clientMsgId?: string | null;
157
+ attachments?: string[];
158
+ };
159
+
160
+ export type MessengerSendResponse = {
161
+ message: MessengerMessage;
162
+ /** false when this clientMsgId was already stored (the same row). */
163
+ created: boolean;
164
+ };
165
+
166
+ /** One entry of GET /api/messenger/directory. */
167
+ export type MessengerDirectoryEntry = {
168
+ kind: MessengerParticipantKind;
169
+ id: string;
170
+ name: string;
171
+ /** Active in the last two minutes (logins only). */
172
+ online: boolean;
173
+ /** An agent's slug (agents only). */
174
+ slug?: string;
175
+ };
176
+
177
+ export type MessengerDirectoryResponse = { entries: MessengerDirectoryEntry[] };
178
+
179
+ /** GET /api/messenger/unread: the badge. */
180
+ export type MessengerUnreadResponse = {
181
+ total: number;
182
+ /** People chats and groups. */
183
+ messenger: number;
184
+ /** Agent threads (assistant replies after my read cursor). */
185
+ agents: number;
186
+ };
187
+
188
+ export type MessengerFavouriteKind = 'conversation' | 'agent';
189
+
190
+ /** The events of GET /api/messenger/stream (ids and seq, never text). */
191
+ export type MessengerStreamEvent =
192
+ | { type: 'message'; c: string; seq: number; kind: 'new' | 'edit' | 'delete' }
193
+ | { type: 'read'; c: string; seq: number; loginId: string }
194
+ | { type: 'participants'; c: string }
195
+ | { type: 'reaction'; c: string; seq: number }
196
+ | { type: 'typing'; c: string; loginId: string }
197
+ /** A group's history was deleted: load the chat again, a deleted message
198
+ * raises no message event. No seq: a leaver must not learn how far the
199
+ * chat went after it left. */
200
+ | { type: 'history'; c: string };
@@ -0,0 +1,52 @@
1
+ /**
2
+ * @mantle/client-types · present checks
3
+ *
4
+ * The image check overview of a traced P&ID canvas (DWG bones phase 6):
5
+ * GET /api/presents/:id/checks. The brain reads the circuit and drawing
6
+ * tables the canvas's data names (circuit_trace writes them) and returns
7
+ * the latest sealed answer of each guess from those tables' Checks tabs.
8
+ * The app shows it beside the canvas, outside its frame. An image check is
9
+ * a help, not a guarantee: `note` says so in one line, and the panel shows
10
+ * it. Crops are ordinary Files ids, opened with the viewer's own rights;
11
+ * no image bytes are inlined.
12
+ */
13
+
14
+ /** One answered guess: the latest sealed Checks row of its key. */
15
+ export type PresentCheckItemDTO = {
16
+ kind: 'join' | 'end' | 'link' | 'valve';
17
+ /** The drawing table it was asked on (its title is the sheet's). */
18
+ tableId: string;
19
+ sheet: string;
20
+ question: string;
21
+ answer: 'yes' | 'no' | 'unsure';
22
+ /** After a no: what the image named instead (a valve type, a tag, a
23
+ * word like "break"). */
24
+ alternative?: string;
25
+ reason: string;
26
+ model: string;
27
+ /** ISO time the check ran. */
28
+ checkedAt: string;
29
+ /** File ids of the close-up crops, in order. */
30
+ crops: string[];
31
+ /** File id of the sheet overview the model saw with them. */
32
+ overview?: string;
33
+ };
34
+
35
+ /** One circuit's image checks. */
36
+ export type PresentCircuitChecksDTO = {
37
+ circuit: string;
38
+ counts: { checked: number; no: number; unsure: number };
39
+ items: PresentCheckItemDTO[];
40
+ /** More answers than `items` carries (the rest are in the Checks tabs). */
41
+ more?: number;
42
+ };
43
+
44
+ export type PresentChecksDTO = {
45
+ /** Whether the canvas is a traced P&ID: false hides the panel. */
46
+ traced: boolean;
47
+ /** "Image checks help; they are not a guarantee. Verify on the drawing." */
48
+ note: string;
49
+ circuits: PresentCircuitChecksDTO[];
50
+ /** What could not be read or is left out, in plain words. */
51
+ limits: string[];
52
+ };
package/src/dto/rows.ts CHANGED
@@ -522,6 +522,11 @@ export type ProfilePreferences = {
522
522
  * once, so one the owner removes later stays removed. Written by the
523
523
  * reconcile alone. */
524
524
  contentKindGroupsGranted?: Record<string, string[]>;
525
+ /** What the boot reconcile has granted each workspace assistant for
526
+ * delegation, per agent id (reconcileWorkspaceDelegation):
527
+ * `group:delegation` and `delegate:<slug>`, each once, so one the owner
528
+ * removes later stays removed. Written by the reconcile alone. */
529
+ workspaceDelegationGranted?: Record<string, string[]>;
525
530
  /** When true, outbound/egress tools (email_send, web_fetch, web_search)
526
531
  * fired during an UNATTENDED heartbeat run park for operator approval
527
532
  * instead of executing inline. Only tools that reach OUT are gated — the
@@ -1,13 +1,14 @@
1
1
  /**
2
2
  * Optional services: the box services an admin can switch on and off from
3
- * the dashboard (sandboxes, media, the local embedder and, on a core box,
4
- * the doc helpers). GET /api/services returns a
3
+ * the dashboard (sandboxes, the local embedder and, on a core box, the
4
+ * PDF-export helper). The parser service is core, never switched. GET
5
+ * /api/services returns a
5
6
  * {@link ServicesView}; POST /api/services/:name {enable} asks the updater
6
7
  * sidecar to switch one; GET /api/services/status is the progress poll.
7
8
  */
8
9
 
9
10
  /** Each name is also the service's compose profile. */
10
- export type OptionalServiceName = 'sandboxes' | 'media' | 'local-embedder' | 'helpers';
11
+ export type OptionalServiceName = 'sandboxes' | 'local-embedder' | 'helpers';
11
12
 
12
13
  /**
13
14
  * - `off`: the compose profile is not active (the resting state).
package/src/dto/shell.ts CHANGED
@@ -14,7 +14,12 @@ import type { ShellWorkspace, WorkspaceArea } from './workspaces';
14
14
  export type ShellRole = LoginRole;
15
15
 
16
16
  /** What this brain can do, so a client branches on capability, not version. */
17
- export type ShellFeatures = { recallV2: boolean };
17
+ export type ShellFeatures = {
18
+ recallV2: boolean;
19
+ /** The tree's custom order: the `custom` sort, `ordered` and `mayOrder` on
20
+ * a folder page, POST /api/tree/:kind/place. Absent from a brain before it. */
21
+ treeCustomOrder?: boolean;
22
+ };
18
23
 
19
24
  export type Shell = {
20
25
  role: ShellRole;
package/src/dto/views.ts CHANGED
@@ -662,16 +662,27 @@ export type SystemHealth = {
662
662
  attachmentBytes: number | null;
663
663
  filesDisk: DiskInfo | null;
664
664
  };
665
- /** Tier-2 document parser fallback (.odt / .pptx / .doc / .rtf / .epub /
666
- * …) — sibling docker service. `up: false` means the fallback path
667
- * degrades cleanly to `no_text_layer` on every new ingest of those
668
- * formats; in-process parsers (pdf/docx/xlsx/text) keep working. */
665
+ /** The parser service: the one container that reads every untrusted file
666
+ * (documents, CAD drawings, images for thumbnails and vision, audio out
667
+ * of uploaded video). Core, always on, no switch. `up: false` means file
668
+ * reading fails for now: ingest retries, a chat attachment says it could
669
+ * not be read. `versions` are the readers and tools its image carries;
670
+ * `running` / `queued` its jobs at the time of the probe. */
671
+ parser: {
672
+ up: boolean;
673
+ versions: Record<string, string>;
674
+ running: number | null;
675
+ queued: number | null;
676
+ };
677
+ /** @deprecated The parser service replaced Apache Tika (2026-10). Mirrors
678
+ * `parser.up` so a client built before it still renders; remove once the
679
+ * paired client reads `parser`. */
669
680
  tika: {
670
681
  up: boolean;
671
682
  version: string | null;
672
683
  };
673
684
  /** The browser sidecar (browserless/chromium) — the Pages → PDF export
674
- * engine, a sibling docker service like Tika. `up: false` means PDF
685
+ * engine, a sibling docker service. `up: false` means PDF
675
686
  * downloads 503 until it's back (Markdown/Word unaffected); `up: null`
676
687
  * means BROWSER_WS_ENDPOINT isn't configured (e.g. detached dev). */
677
688
  browser: {
@@ -705,21 +716,14 @@ export type SystemHealth = {
705
716
  running: number | null;
706
717
  disk: { usedBytes: number | null; budgetBytes: number } | null;
707
718
  };
708
- /** Media sidecar (yt-dlp + ffmpeg) — the video_ingest fetch/transcode
709
- * engine, profile-gated like sandboxes, so `up: null` (muted pill) is the
710
- * resting state on a box without the `media` compose profile. Versions
711
- * come from its /healthz — that is what makes a stale or failed yt-dlp
712
- * self-update VISIBLE instead of silently breaking downloads. */
719
+ /** @deprecated The media sidecar was removed with the parser service
720
+ * (2026-10): always `up: null` (a muted pill) so a client built before it
721
+ * still renders; remove once the paired client reads `parser`. */
713
722
  media: {
714
723
  up: boolean | null;
715
724
  ytDlpVersion: string | null;
716
725
  ffmpegVersion: string | null;
717
- /** null on images built before the CAD tier (v0.232.92) — DWF renders
718
- * fall back to embedded thumbnails without it. */
719
726
  ezdwfVersion: string | null;
720
- /** null on images built before the DWG tier (v0.232.99) — with either of
721
- * these missing the UI should show "DWG tier missing" (DWG parsing and
722
- * rendering both need the sidecar; absence means the whole format). */
723
727
  dwg2dxfVersion: string | null;
724
728
  ezdxfVersion: string | null;
725
729
  };
@@ -117,14 +117,14 @@ export type WorkspaceDetailResponse = {
117
117
  * or removed, only cloned to use elsewhere. */
118
118
  hasHistory: boolean;
119
119
  /** The workspace's landing page (task d78e7bde): its home app, or null
120
- * for the Built-in home. Absent from an older brain. */
120
+ * for the built-in Desk. Absent from an older brain. */
121
121
  landingApp?: WorkspaceLandingApp | null;
122
122
  };
123
123
 
124
124
  /**
125
125
  * A workspace's home app, as its screen shows it. `held`: the workspace
126
126
  * still holds the app; false is a pointer left from before (the landing
127
- * page shows the Built-in home), with no id or title: only a clear
127
+ * page shows the built-in Desk), with no id or title: only a clear
128
128
  * (`landingAppId: null`) makes sense then. `appId` and `title` are named
129
129
  * only to a user of the workspace (an Admin user outside it gets null for
130
130
  * both). `ready`: a green published build, so the landing page shows it.
@@ -145,7 +145,7 @@ export type WorkspaceLandingApp = {
145
145
  * user (assistant: area 'assistants'). The landing page (`landingAppId`): a Moderator of this
146
146
  * workspace only, to an app the workspace holds with a green published
147
147
  * build (409 `landing_app_not_held` or `landing_app_not_ready`). `null`
148
- * clears (the Built-in home). Answers the updated Workspace. */
148
+ * clears (the built-in Desk). Answers the updated Workspace. */
149
149
  export type WorkspacePatchBody = {
150
150
  name?: string;
151
151
  description?: string;
package/src/index.ts CHANGED
@@ -35,6 +35,7 @@ export * from './dto/views';
35
35
  export * from './dto/recall';
36
36
  export * from './dto/contact-shares';
37
37
  export * from './dto/services';
38
+ export * from './dto/present-checks';
38
39
  // Types only; ACCESS_LEVELS (runtime) is the `@mantle/client-types/dto/access` subpath.
39
40
  export type {
40
41
  AccessItemView,
@@ -105,6 +106,31 @@ export type {
105
106
  MemberInviteState,
106
107
  } from './dto/member-invites';
107
108
  export type { MemberMcpClient, MemberMcpConnector, MemberMcpView } from './dto/member-mcp';
109
+ export type {
110
+ MessengerAuthorKind,
111
+ MessengerConversation,
112
+ MessengerConversationKind,
113
+ MessengerCreateRequest,
114
+ MessengerCreateResponse,
115
+ MessengerDirectoryEntry,
116
+ MessengerDirectoryResponse,
117
+ MessengerFavouriteKind,
118
+ MessengerListResponse,
119
+ MessengerListRow,
120
+ MessengerMention,
121
+ MessengerMessage,
122
+ MessengerMessageStatus,
123
+ MessengerMessagesResponse,
124
+ MessengerParticipant,
125
+ MessengerParticipantKind,
126
+ MessengerPreview,
127
+ MessengerReaction,
128
+ MessengerRowKind,
129
+ MessengerSendRequest,
130
+ MessengerSendResponse,
131
+ MessengerStreamEvent,
132
+ MessengerUnreadResponse,
133
+ } from './dto/messenger';
108
134
  export type {
109
135
  BulkDeleteCascadeResponse,
110
136
  BulkDeleteFilesResponse,
@@ -227,6 +253,8 @@ export type {
227
253
  } from './dto/workspaces';
228
254
  // GET /api/shell: the one shell, for every login (W5c).
229
255
  export type { Shell, ShellFeatures, ShellRole } from './dto/shell';
256
+ // GET and PUT /api/profile/home-desk: the login's Desk, compare-and-set.
257
+ export type { HomeDesk, HomeDeskItem, HomeDeskPutBody, HomeDeskState } from './dto/home-desk';
230
258
  export type {
231
259
  GrantAddBody,
232
260
  GrantContactShare,
package/src/kinds.test.ts CHANGED
@@ -132,91 +132,91 @@ describe('derived lists, pinned to their value before the registry', () => {
132
132
  root: 'files',
133
133
  nodeType: 'file',
134
134
  shareable: true,
135
- sorts: ['name', 'updated'],
135
+ sorts: ['custom', 'name', 'updated'],
136
136
  },
137
137
  notes: {
138
138
  kind: 'notes',
139
139
  root: 'notes',
140
140
  nodeType: 'note',
141
141
  shareable: true,
142
- sorts: ['updated', 'name'],
142
+ sorts: ['custom', 'updated', 'name'],
143
143
  },
144
144
  pages: {
145
145
  kind: 'pages',
146
146
  root: 'pages',
147
147
  nodeType: 'page',
148
148
  shareable: true,
149
- sorts: ['updated', 'name'],
149
+ sorts: ['custom', 'updated', 'name'],
150
150
  },
151
151
  draw: {
152
152
  kind: 'draw',
153
153
  root: 'draw',
154
154
  nodeType: 'draw',
155
155
  shareable: true,
156
- sorts: ['updated', 'name'],
156
+ sorts: ['custom', 'updated', 'name'],
157
157
  },
158
158
  tables: {
159
159
  kind: 'tables',
160
160
  root: 'tables',
161
161
  nodeType: 'table',
162
162
  shareable: true,
163
- sorts: ['updated', 'name'],
163
+ sorts: ['custom', 'updated', 'name'],
164
164
  },
165
165
  formulas: {
166
166
  kind: 'formulas',
167
167
  root: 'formulas',
168
168
  nodeType: 'formula',
169
169
  shareable: true,
170
- sorts: ['name', 'updated'],
170
+ sorts: ['custom', 'name', 'updated'],
171
171
  },
172
172
  apps: {
173
173
  kind: 'apps',
174
174
  root: 'apps',
175
175
  nodeType: 'app',
176
176
  shareable: true,
177
- sorts: ['name', 'updated'],
177
+ sorts: ['custom', 'name', 'updated'],
178
178
  },
179
179
  tasks: {
180
180
  kind: 'tasks',
181
181
  root: 'tasks',
182
182
  nodeType: 'task',
183
183
  shareable: false,
184
- sorts: ['due', 'updated', 'name'],
184
+ sorts: ['custom', 'due', 'updated', 'name'],
185
185
  },
186
186
  events: {
187
187
  kind: 'events',
188
188
  root: 'events',
189
189
  nodeType: 'event',
190
190
  shareable: false,
191
- sorts: ['start', 'name'],
191
+ sorts: ['custom', 'start', 'name'],
192
192
  },
193
193
  contacts: {
194
194
  kind: 'contacts',
195
195
  root: 'contacts',
196
196
  nodeType: 'contact',
197
197
  shareable: false,
198
- sorts: ['name', 'updated'],
198
+ sorts: ['custom', 'name', 'updated'],
199
199
  },
200
200
  secrets: {
201
201
  kind: 'secrets',
202
202
  root: 'secrets',
203
203
  nodeType: 'secret',
204
204
  shareable: false,
205
- sorts: ['name', 'updated'],
205
+ sorts: ['custom', 'name', 'updated'],
206
206
  },
207
207
  recall: {
208
208
  kind: 'recall',
209
209
  root: 'recall',
210
210
  nodeType: 'recall',
211
211
  shareable: false,
212
- sorts: ['name', 'updated'],
212
+ sorts: ['custom', 'name', 'updated'],
213
213
  },
214
214
  present: {
215
215
  kind: 'present',
216
216
  root: 'present',
217
217
  nodeType: 'present',
218
218
  shareable: true,
219
- sorts: ['updated', 'name'],
219
+ sorts: ['custom', 'updated', 'name'],
220
220
  },
221
221
  });
222
222
  });
package/src/tree.ts CHANGED
@@ -44,8 +44,11 @@ export const TREE_FOLDER_NAME_MAX = 60;
44
44
  export const TREE_SEARCH_MAX = 200;
45
45
 
46
46
  /** The orders a folder's items can be listed in. Folders always keep their
47
- * own manual order (rank, then name). */
48
- export const TREE_SORTS = ['name', 'updated', 'start', 'due'] as const;
47
+ * own manual order (rank, then name). `custom` is the order people set by
48
+ * dragging (`data.tree_rank`, one for everyone): a folder that has one lists by
49
+ * it, then by name; one that has none lists in the kind's first other sort,
50
+ * so `custom` changes nothing until someone orders the folder. */
51
+ export const TREE_SORTS = ['name', 'updated', 'start', 'due', 'custom'] as const;
49
52
  export type TreeSort = (typeof TREE_SORTS)[number];
50
53
 
51
54
  export function isTreeSort(v: unknown): v is TreeSort {
@@ -68,7 +71,9 @@ export type TreeKindSpec = {
68
71
  /** Whether a folder of this kind may be shared below admin. The kinds that
69
72
  * are admin-only forever (the type ceiling) never are. */
70
73
  shareable: boolean;
71
- /** The item orders offered, the first being the default. */
74
+ /** The item orders offered, the first being the default: `custom` first
75
+ * for every kind, then the registry's own (the first of those is what an
76
+ * unordered folder lists in). */
72
77
  sorts: readonly TreeSort[];
73
78
  };
74
79
 
@@ -87,7 +92,7 @@ export const TREE_KIND_SPECS: Readonly<Record<TreeKind, TreeKindSpec>> = Object.
87
92
  root: tree.root,
88
93
  nodeType,
89
94
  shareable: tree.shareable,
90
- sorts: tree.sorts,
95
+ sorts: ['custom', ...tree.sorts],
91
96
  },
92
97
  ]),
93
98
  ) as Record<TreeKind, TreeKindSpec>;
@@ -195,6 +200,15 @@ export type TreeFolderPage = {
195
200
  folders: TreeFolder[];
196
201
  items: TreeItem[];
197
202
  sort: TreeSort;
203
+ /** Asked with `sort=custom`: the folder has a custom order (an item it
204
+ * lists carries a rank), so its items are in that order. Absent when they
205
+ * are in the kind's other sort, and from a brain before it. */
206
+ ordered?: boolean;
207
+ /** The caller may set this folder's order, of its items and its
208
+ * subfolders (POST /api/tree/:kind/place, a folder's `after`): Write on
209
+ * the folder, or an Admin scope at the top level. Absent from a brain
210
+ * before it. */
211
+ mayOrder?: boolean;
198
212
  /** Pass back as `cursor` for the next page of items; null at the end. */
199
213
  nextCursor: string | null;
200
214
  /** Asked with `?ws=<id>` (ListWsEcho): the items are only those that
@@ -57,6 +57,11 @@ export type Capability = { available: boolean; detail: string };
57
57
 
58
58
  /** Brain-readiness snapshot. */
59
59
  export type Capabilities = {
60
+ /** The parser service: reads every untrusted file the brain receives
61
+ * (documents, CAD, images, audio). Core: always expected up. */
62
+ parser: Capability;
63
+ /** @deprecated The parser replaced Apache Tika (2026-10); mirrors
64
+ * `parser` for a client older than it. */
60
65
  tika: Capability;
61
66
  vision: Capability;
62
67
  extractor: Capability;
@@ -64,8 +69,8 @@ export type Capabilities = {
64
69
  summarizer: Capability;
65
70
  reflector: Capability;
66
71
  stt: Capability;
67
- /** The media sidecar (yt-dlp + ffmpeg) behind video_ingest — profile-gated,
68
- * so "unavailable" is the normal resting state on a box without it. */
72
+ /** @deprecated The media sidecar was removed with the parser service
73
+ * (2026-10); always unavailable, for a client older than it. */
69
74
  media: Capability;
70
75
  };
71
76