adula 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/README.md +1 -1
  2. package/build/agent/capabilities.md +2 -3
  3. package/build/agent/skills/adula-frontend-design/SKILL.md +5 -3
  4. package/build/commands/adula_assistant_prune.d.ts +10 -0
  5. package/build/commands/adula_assistant_prune.js +12 -0
  6. package/build/commands/backup_open.d.ts +16 -0
  7. package/build/commands/backup_open.js +48 -0
  8. package/build/commands/backup_restore_test.js +3 -0
  9. package/build/commands/backup_seal.d.ts +12 -0
  10. package/build/commands/backup_seal.js +36 -0
  11. package/build/commands/backup_services.d.ts +3 -1
  12. package/build/commands/doctor.js +18 -1
  13. package/build/commands/install.js +6 -0
  14. package/build/commands/main.d.ts +2 -2
  15. package/build/commands/main.js +6 -0
  16. package/build/commands/resource_migration.js +12 -3
  17. package/build/commands/resource_snapshot.js +18 -4
  18. package/build/database/migrations/1770000000051_comment_notifications.d.ts +5 -0
  19. package/build/database/migrations/1770000000051_comment_notifications.js +10 -0
  20. package/build/database/migrations/1770000000054_cloud_backups.d.ts +5 -0
  21. package/build/database/migrations/1770000000054_cloud_backups.js +10 -0
  22. package/build/database/migrations/1770000000055_ai_assistant.d.ts +5 -0
  23. package/build/database/migrations/1770000000055_ai_assistant.js +10 -0
  24. package/build/database/migrations/1770000000056_appearance.d.ts +5 -0
  25. package/build/database/migrations/1770000000056_appearance.js +10 -0
  26. package/build/index.d.ts +36 -6
  27. package/build/index.js +18 -3
  28. package/build/src/admin/controller.js +18 -4
  29. package/build/src/admin/resource/editor.d.ts +1 -0
  30. package/build/src/admin/resource/editor.js +26 -4
  31. package/build/src/admin/resource/export.d.ts +21 -4
  32. package/build/src/admin/resource/export.js +117 -36
  33. package/build/src/admin/resource/lifecycle.d.ts +2 -0
  34. package/build/src/admin/resource/query.d.ts +14 -3
  35. package/build/src/admin/resource/query.js +98 -11
  36. package/build/src/admin/resource/read.d.ts +3 -0
  37. package/build/src/admin/resource/read.js +75 -14
  38. package/build/src/admin/resource/shared.d.ts +16 -0
  39. package/build/src/admin/resource/shared.js +47 -4
  40. package/build/src/admin/resource/write.js +37 -8
  41. package/build/src/admin/resource_service.d.ts +17 -3
  42. package/build/src/admin/resource_service.js +16 -2
  43. package/build/src/admin/resource_tools.d.ts +111 -0
  44. package/build/src/admin/resource_tools.js +139 -0
  45. package/build/src/ai/assistant.d.ts +100 -0
  46. package/build/src/ai/assistant.js +487 -0
  47. package/build/src/ai/client.d.ts +49 -0
  48. package/build/src/ai/client.js +85 -0
  49. package/build/src/ai/prompt.d.ts +23 -0
  50. package/build/src/ai/prompt.js +83 -0
  51. package/build/src/ai/settings.d.ts +56 -0
  52. package/build/src/ai/settings.js +214 -0
  53. package/build/src/ai/usage.d.ts +16 -0
  54. package/build/src/ai/usage.js +33 -0
  55. package/build/src/appearance/appearance.d.ts +134 -0
  56. package/build/src/appearance/appearance.js +461 -0
  57. package/build/src/appearance/colors.d.ts +43 -0
  58. package/build/src/appearance/colors.js +99 -0
  59. package/build/src/appearance/logo.d.ts +32 -0
  60. package/build/src/appearance/logo.js +112 -0
  61. package/build/src/auth/actor_store.d.ts +5 -1
  62. package/build/src/auth/actor_store.js +8 -4
  63. package/build/src/backups/archive.d.ts +52 -0
  64. package/build/src/backups/archive.js +362 -0
  65. package/build/src/backups/cloud_backups.d.ts +133 -0
  66. package/build/src/backups/cloud_backups.js +650 -0
  67. package/build/src/backups/doctor.d.ts +7 -0
  68. package/build/src/backups/doctor.js +55 -0
  69. package/build/src/backups/providers.d.ts +81 -0
  70. package/build/src/backups/providers.js +470 -0
  71. package/build/src/collaboration/assignments.d.ts +24 -2
  72. package/build/src/collaboration/assignments.js +88 -32
  73. package/build/src/collaboration/record_collaboration.d.ts +19 -1
  74. package/build/src/collaboration/record_collaboration.js +109 -37
  75. package/build/src/collaboration/shared.d.ts +10 -2
  76. package/build/src/collaboration/shared.js +14 -1
  77. package/build/src/commands/capabilities.js +1 -1
  78. package/build/src/commands/doctor.d.ts +10 -0
  79. package/build/src/commands/doctor.js +31 -1
  80. package/build/src/commands/snapshot.d.ts +14 -0
  81. package/build/src/commands/snapshot.js +23 -0
  82. package/build/src/core/administrators.js +19 -3
  83. package/build/src/core/avatar_image.d.ts +33 -0
  84. package/build/src/core/avatar_image.js +278 -0
  85. package/build/src/core/mail_settings.d.ts +83 -0
  86. package/build/src/core/mail_settings.js +274 -0
  87. package/build/src/core/mail_test.d.ts +16 -0
  88. package/build/src/core/mail_test.js +81 -6
  89. package/build/src/core/message_templates.d.ts +8 -0
  90. package/build/src/core/message_templates.js +12 -3
  91. package/build/src/core/roles.js +24 -7
  92. package/build/src/core/saved_views.js +55 -24
  93. package/build/src/core/settings.d.ts +2 -2
  94. package/build/src/core/settings.js +15 -4
  95. package/build/src/core/ui_preferences.d.ts +6 -0
  96. package/build/src/core/ui_preferences.js +12 -1
  97. package/build/src/core/user_avatars.d.ts +79 -0
  98. package/build/src/core/user_avatars.js +186 -0
  99. package/build/src/core/user_preferences.d.ts +36 -0
  100. package/build/src/core/user_preferences.js +125 -0
  101. package/build/src/core/users.d.ts +2 -0
  102. package/build/src/core/users.js +4 -2
  103. package/build/src/database/schema.d.ts +46 -0
  104. package/build/src/database/schema.js +182 -0
  105. package/build/src/database/schema_diff.d.ts +16 -2
  106. package/build/src/database/schema_diff.js +40 -7
  107. package/build/src/integrations/api_client.js +18 -3
  108. package/build/src/integrations/imports.d.ts +16 -4
  109. package/build/src/integrations/imports.js +36 -8
  110. package/build/src/integrations/openapi.js +15 -4
  111. package/build/src/integrations/outbound.d.ts +43 -0
  112. package/build/src/integrations/outbound.js +98 -17
  113. package/build/src/integrations/print.d.ts +2 -1
  114. package/build/src/integrations/print.js +7 -3
  115. package/build/src/integrations/print_templates.js +3 -1
  116. package/build/src/integrations/xlsx.d.ts +41 -0
  117. package/build/src/integrations/xlsx.js +519 -0
  118. package/build/src/languages/ar.js +22 -0
  119. package/build/src/languages/ar_ui.d.ts +143 -14
  120. package/build/src/languages/ar_ui.js +145 -14
  121. package/build/src/languages/en.js +22 -0
  122. package/build/src/languages/en_ui.js +144 -14
  123. package/build/src/lists/dashboards.d.ts +42 -0
  124. package/build/src/lists/dashboards.js +49 -0
  125. package/build/src/mcp/tools.js +9 -104
  126. package/build/src/resource/define_resource.js +7 -0
  127. package/build/src/resource/types.d.ts +9 -0
  128. package/build/src/workflows/delegations.d.ts +15 -1
  129. package/build/src/workflows/delegations.js +49 -10
  130. package/build/src/workflows/engine.d.ts +11 -0
  131. package/build/src/workflows/engine.js +29 -7
  132. package/package.json +5 -1
@@ -4,13 +4,13 @@ import type { Action, RecordData, SerializedRecord } from '../resource/types.js'
4
4
  import type { Actor } from '../auth/ability.js';
5
5
  import type { ResourceDescription, ResourceNavigation } from './presentation.js';
6
6
  import type { AttachmentPreviewOptions } from '../attachments/attachment_service.js';
7
- import { type CsvExport, type ExportOptions } from './resource/export.js';
7
+ import { type CsvExport, type ExportOptions, type XlsxExport } from './resource/export.js';
8
8
  import type { AggregateOptions, AggregateRow, ListOptions } from './resource/query.js';
9
9
  import type { SystemSaveOptions } from './resource/write.js';
10
10
  export { canQueryField } from './resource/shared.js';
11
11
  export type { AggregateOptions, AggregateRow, ListOptions, ListFilterScalar, ListFilterValue, } from './resource/query.js';
12
- export { EXPORT_ROW_LIMIT } from './resource/export.js';
13
- export type { CsvExport, ExportOptions } from './resource/export.js';
12
+ export { EXPORT_ROW_LIMIT, guardFormula } from './resource/export.js';
13
+ export type { CsvExport, ExportOptions, XlsxExport } from './resource/export.js';
14
14
  export type { SystemSaveOptions } from './resource/write.js';
15
15
  /**
16
16
  * Authorized reads and writes of registered resources. The work is done by the modules
@@ -68,6 +68,11 @@ export declare class ResourceService {
68
68
  rows: AggregateRow[];
69
69
  truncated: boolean;
70
70
  }>;
71
+ /**
72
+ * Tag names used on records the actor may view, at most `limit` (1-200), for tag
73
+ * suggestions. Authorization is list()'s: rules, organization scope and soft delete.
74
+ */
75
+ tagNames(name: string, actor: Actor, limit?: number): Promise<string[]>;
71
76
  /**
72
77
  * Titles of records the actor may view, read under the actor's field access (#32).
73
78
  * Records the actor cannot view are left out; callers fall back to the record id.
@@ -126,6 +131,7 @@ export declare class ResourceService {
126
131
  fields: string[];
127
132
  actorId: number;
128
133
  actorName: string | null;
134
+ actorAvatarUrl: string | null;
129
135
  actorEmail: string | null;
130
136
  createdAt: string;
131
137
  }[]>;
@@ -145,6 +151,7 @@ export declare class ResourceService {
145
151
  fields: string[];
146
152
  actorId: number;
147
153
  actorName: string | null;
154
+ actorAvatarUrl: string | null;
148
155
  actorEmail: string | null;
149
156
  createdAt: string;
150
157
  }[];
@@ -162,6 +169,7 @@ export declare class ResourceService {
162
169
  fields: string[];
163
170
  actorId: number;
164
171
  actorName: string | null;
172
+ actorAvatarUrl: string | null;
165
173
  actorEmail: string | null;
166
174
  createdAt: string;
167
175
  }[];
@@ -199,6 +207,7 @@ export declare class ResourceService {
199
207
  options: Record<string, {
200
208
  value: string;
201
209
  label: string;
210
+ avatarUrl?: string | null;
202
211
  }[]>;
203
212
  relationSearch: Record<string, boolean>;
204
213
  orgUnits: {
@@ -240,6 +249,11 @@ export declare class ResourceService {
240
249
  * Every export is recorded in the activity log (`core.exports`, `exported`).
241
250
  */
242
251
  export(name: string, actor: Actor, options?: ExportOptions): Promise<CsvExport>;
252
+ /**
253
+ * The same export as an Excel workbook: one right-to-left sheet with a bold header, typed
254
+ * numbers, amounts and dates, the same limit and an audit entry with `format: 'xlsx'`.
255
+ */
256
+ exportXlsx(name: string, actor: Actor, options?: ExportOptions): Promise<XlsxExport>;
243
257
  /**
244
258
  * Amend-by-copy: a cancelled document is copied into a new draft that points to
245
259
  * it through amended_from_id, together with its inline lines. The original stays
@@ -4,9 +4,9 @@ import * as form from './resource/editor.js';
4
4
  import * as write from './resource/write.js';
5
5
  import { transition } from './resource/lifecycle.js';
6
6
  import { restore } from './resource/trash.js';
7
- import { exportCsv } from './resource/export.js';
7
+ import { exportCsv, exportXlsx, } from './resource/export.js';
8
8
  export { canQueryField } from './resource/shared.js';
9
- export { EXPORT_ROW_LIMIT } from './resource/export.js';
9
+ export { EXPORT_ROW_LIMIT, guardFormula } from './resource/export.js';
10
10
  /**
11
11
  * Authorized reads and writes of registered resources. The work is done by the modules
12
12
  * under ./resource (query, read, editor, write, lifecycle); this class keeps the public
@@ -63,6 +63,13 @@ export class ResourceService {
63
63
  async aggregate(name, actor, options = {}) {
64
64
  return query.aggregate(this.context, name, actor, options);
65
65
  }
66
+ /**
67
+ * Tag names used on records the actor may view, at most `limit` (1-200), for tag
68
+ * suggestions. Authorization is list()'s: rules, organization scope and soft delete.
69
+ */
70
+ async tagNames(name, actor, limit = 200) {
71
+ return query.tagNames(this.context, name, actor, Math.max(1, Math.min(200, Math.floor(Number(limit)) || 200)));
72
+ }
66
73
  /**
67
74
  * Titles of records the actor may view, read under the actor's field access (#32).
68
75
  * Records the actor cannot view are left out; callers fall back to the record id.
@@ -161,6 +168,13 @@ export class ResourceService {
161
168
  async export(name, actor, options = {}) {
162
169
  return exportCsv(this.context, name, actor, options);
163
170
  }
171
+ /**
172
+ * The same export as an Excel workbook: one right-to-left sheet with a bold header, typed
173
+ * numbers, amounts and dates, the same limit and an audit entry with `format: 'xlsx'`.
174
+ */
175
+ async exportXlsx(name, actor, options = {}) {
176
+ return exportXlsx(this.context, name, actor, options);
177
+ }
164
178
  /**
165
179
  * Amend-by-copy: a cancelled document is copied into a new draft that points to
166
180
  * it through amended_from_id, together with its inline lines. The original stays
@@ -0,0 +1,111 @@
1
+ import type { ResourceRuntime } from './controller.js';
2
+ import type { ListOptions } from './resource_service.js';
3
+ /**
4
+ * The resource tool surface shared by MCP and the built-in assistant: one argument
5
+ * parser, one dispatcher and one error mapping, so both reach ResourceService through
6
+ * the same path. Nothing here imports the optional MCP package.
7
+ */
8
+ export type ResourceToolAction = 'list' | 'show' | 'editor' | 'create' | 'update' | 'delete' | 'submit' | 'cancel';
9
+ export type ResourceToolCall = {
10
+ write: boolean;
11
+ resource: string;
12
+ action: ResourceToolAction;
13
+ id?: number;
14
+ options?: ListOptions;
15
+ input?: Record<string, unknown>;
16
+ version?: unknown;
17
+ };
18
+ export type ResourceToolError = {
19
+ status: number;
20
+ code: string;
21
+ message?: string;
22
+ messages?: unknown;
23
+ };
24
+ /**
25
+ * Validates tool arguments against a fixed whitelist. The actor never comes from the
26
+ * arguments: unknown keys (an `actorId`, a role) are refused.
27
+ */
28
+ export declare function parseResourceToolArgs(runtime: Pick<ResourceRuntime, 'registry'>, value: unknown, write: boolean): ResourceToolCall;
29
+ /** Runs a parsed call through ResourceService as `runtime.actor`. */
30
+ export declare function runResourceTool(runtime: ResourceRuntime, call: ResourceToolCall): Promise<unknown>;
31
+ /** Maps a failure to a wire-safe error: no SQL, credentials or stack traces. */
32
+ export declare function resourceToolError(error: unknown): ResourceToolError;
33
+ /** JSON Schema of the read tool's arguments. */
34
+ export declare const RESOURCE_READ_SCHEMA: {
35
+ readonly type: "object";
36
+ readonly additionalProperties: false;
37
+ readonly properties: {
38
+ readonly resource: {
39
+ readonly type: "string";
40
+ };
41
+ readonly action: {
42
+ readonly type: "string";
43
+ readonly enum: readonly ["list", "show", "editor"];
44
+ };
45
+ readonly id: {
46
+ readonly type: "integer";
47
+ readonly minimum: 1;
48
+ };
49
+ readonly options: {
50
+ readonly type: "object";
51
+ readonly properties: {
52
+ readonly limit: {
53
+ readonly type: "integer";
54
+ readonly minimum: 1;
55
+ readonly maximum: 100;
56
+ };
57
+ readonly cursor: {
58
+ readonly type: "string";
59
+ };
60
+ readonly search: {
61
+ readonly type: "string";
62
+ };
63
+ readonly sort: {
64
+ readonly type: "string";
65
+ };
66
+ readonly direction: {
67
+ readonly type: "string";
68
+ readonly enum: readonly ["asc", "desc"];
69
+ };
70
+ readonly filters: {
71
+ readonly type: "object";
72
+ readonly properties: {};
73
+ readonly additionalProperties: true;
74
+ };
75
+ readonly estimate: {
76
+ readonly type: "boolean";
77
+ };
78
+ };
79
+ readonly additionalProperties: false;
80
+ };
81
+ };
82
+ readonly required: readonly ["resource", "action"];
83
+ };
84
+ /** JSON Schema of the write tool's arguments. */
85
+ export declare const RESOURCE_WRITE_SCHEMA: {
86
+ readonly type: "object";
87
+ readonly additionalProperties: false;
88
+ readonly properties: {
89
+ readonly resource: {
90
+ readonly type: "string";
91
+ };
92
+ readonly action: {
93
+ readonly type: "string";
94
+ readonly enum: readonly ["create", "update", "delete", "submit", "cancel"];
95
+ };
96
+ readonly id: {
97
+ readonly type: "integer";
98
+ readonly minimum: 1;
99
+ };
100
+ readonly input: {
101
+ readonly type: "object";
102
+ readonly properties: {};
103
+ readonly additionalProperties: true;
104
+ };
105
+ readonly version: {
106
+ readonly type: "integer";
107
+ readonly minimum: 1;
108
+ };
109
+ };
110
+ readonly required: readonly ["resource", "action"];
111
+ };
@@ -0,0 +1,139 @@
1
+ import { AdulaError } from './errors.js';
2
+ const READ_KEYS = ['resource', 'action', 'id', 'options'];
3
+ const WRITE_KEYS = ['resource', 'action', 'id', 'input', 'version'];
4
+ const LIST_KEYS = ['limit', 'cursor', 'search', 'sort', 'direction', 'filters', 'estimate'];
5
+ function object(value) {
6
+ if (!value || typeof value !== 'object' || Array.isArray(value))
7
+ throw new AdulaError(422, 'E_INPUT', 'Expected an object');
8
+ return value;
9
+ }
10
+ function recordId(value) {
11
+ if (!Number.isSafeInteger(value) || Number(value) < 1)
12
+ throw new AdulaError(422, 'E_ID', 'Expected a positive integer record ID');
13
+ return Number(value);
14
+ }
15
+ /**
16
+ * Validates tool arguments against a fixed whitelist. The actor never comes from the
17
+ * arguments: unknown keys (an `actorId`, a role) are refused.
18
+ */
19
+ export function parseResourceToolArgs(runtime, value, write) {
20
+ const args = object(value);
21
+ const accepted = write ? WRITE_KEYS : READ_KEYS;
22
+ if (Object.keys(args).some((key) => !accepted.includes(key)))
23
+ throw new AdulaError(422, 'E_INPUT', 'Unknown tool argument');
24
+ if (typeof args.resource !== 'string' ||
25
+ !runtime.registry.all().some((r) => r.name === args.resource))
26
+ throw new AdulaError(404, 'E_NOT_FOUND', 'الكيان غير موجود');
27
+ const resource = args.resource;
28
+ if (!write && args.action === 'list') {
29
+ const options = args.options === undefined ? {} : object(args.options);
30
+ if (Object.keys(options).some((key) => !LIST_KEYS.includes(key)))
31
+ throw new AdulaError(422, 'E_INPUT', 'Unknown list option');
32
+ for (const key of ['cursor', 'search', 'sort'])
33
+ if (options[key] !== undefined && typeof options[key] !== 'string')
34
+ throw new AdulaError(422, 'E_INPUT', `Invalid ${key}`);
35
+ if ((options.limit !== undefined && !Number.isSafeInteger(options.limit)) ||
36
+ (options.direction !== undefined && !['asc', 'desc'].includes(String(options.direction))) ||
37
+ (options.estimate !== undefined && typeof options.estimate !== 'boolean'))
38
+ throw new AdulaError(422, 'E_INPUT', 'Invalid list options');
39
+ if (options.filters !== undefined)
40
+ object(options.filters);
41
+ return { write, resource, action: 'list', options: options };
42
+ }
43
+ if (!write && args.action === 'show')
44
+ return { write, resource, action: 'show', id: recordId(args.id) };
45
+ if (!write && args.action === 'editor')
46
+ return {
47
+ write,
48
+ resource,
49
+ action: 'editor',
50
+ ...(args.id === undefined ? {} : { id: recordId(args.id) }),
51
+ };
52
+ if (write && (args.action === 'create' || args.action === 'update')) {
53
+ if (args.action === 'create' && args.id !== undefined)
54
+ throw new AdulaError(422, 'E_INPUT', 'Create cannot specify an ID');
55
+ return {
56
+ write,
57
+ resource,
58
+ action: args.action,
59
+ input: object(args.input),
60
+ ...(args.action === 'update' ? { id: recordId(args.id) } : {}),
61
+ };
62
+ }
63
+ if (write && (args.action === 'delete' || args.action === 'submit' || args.action === 'cancel'))
64
+ return { write, resource, action: args.action, id: recordId(args.id), version: args.version };
65
+ throw new AdulaError(422, 'E_ACTION', 'Unsupported resource action');
66
+ }
67
+ /** Runs a parsed call through ResourceService as `runtime.actor`. */
68
+ export async function runResourceTool(runtime, call) {
69
+ const { resources, actor } = runtime;
70
+ const name = call.resource;
71
+ switch (call.action) {
72
+ case 'list':
73
+ return resources.list(name, actor, call.options ?? {});
74
+ case 'show':
75
+ return resources.show(name, call.id, actor);
76
+ case 'editor':
77
+ return resources.editor(name, actor, call.id);
78
+ case 'create':
79
+ case 'update':
80
+ return {
81
+ data: await resources.save(name, actor, call.input ?? {}, call.action === 'update' ? call.id : undefined),
82
+ };
83
+ default:
84
+ return {
85
+ data: await resources.transition(name, call.id, actor, call.action, call.version),
86
+ };
87
+ }
88
+ }
89
+ /** Maps a failure to a wire-safe error: no SQL, credentials or stack traces. */
90
+ export function resourceToolError(error) {
91
+ if (error instanceof AdulaError)
92
+ return { status: error.status, code: error.code, message: error.message };
93
+ if (error?.code === 'E_VALIDATION_ERROR')
94
+ return {
95
+ status: 422,
96
+ code: 'E_VALIDATION_ERROR',
97
+ messages: error.messages,
98
+ };
99
+ if (['23505', '23503', '23502'].includes(error?.code ?? ''))
100
+ return { status: 422, code: 'E_CONSTRAINT', message: 'تحقق من القيم والسجلات المرتبطة' };
101
+ return { status: 500, code: 'E_INTERNAL', message: 'تعذر إتمام العملية' };
102
+ }
103
+ /** JSON Schema of the read tool's arguments. */
104
+ export const RESOURCE_READ_SCHEMA = {
105
+ type: 'object',
106
+ additionalProperties: false,
107
+ properties: {
108
+ resource: { type: 'string' },
109
+ action: { type: 'string', enum: ['list', 'show', 'editor'] },
110
+ id: { type: 'integer', minimum: 1 },
111
+ options: {
112
+ type: 'object',
113
+ properties: {
114
+ limit: { type: 'integer', minimum: 1, maximum: 100 },
115
+ cursor: { type: 'string' },
116
+ search: { type: 'string' },
117
+ sort: { type: 'string' },
118
+ direction: { type: 'string', enum: ['asc', 'desc'] },
119
+ filters: { type: 'object', properties: {}, additionalProperties: true },
120
+ estimate: { type: 'boolean' },
121
+ },
122
+ additionalProperties: false,
123
+ },
124
+ },
125
+ required: ['resource', 'action'],
126
+ };
127
+ /** JSON Schema of the write tool's arguments. */
128
+ export const RESOURCE_WRITE_SCHEMA = {
129
+ type: 'object',
130
+ additionalProperties: false,
131
+ properties: {
132
+ resource: { type: 'string' },
133
+ action: { type: 'string', enum: ['create', 'update', 'delete', 'submit', 'cancel'] },
134
+ id: { type: 'integer', minimum: 1 },
135
+ input: { type: 'object', properties: {}, additionalProperties: true },
136
+ version: { type: 'integer', minimum: 1 },
137
+ },
138
+ required: ['resource', 'action'],
139
+ };
@@ -0,0 +1,100 @@
1
+ import type { Knex } from 'knex';
2
+ import type { Actor } from '../auth/ability.js';
3
+ import type { ResourceRegistry } from '../resource/registry.js';
4
+ import type { ResourceService } from '../admin/resource_service.js';
5
+ import { type ChatClient } from './client.js';
6
+ import { type AssistantSettings } from './settings.js';
7
+ export declare const ASSISTANT_SUBJECT = "core.ai";
8
+ export declare const MESSAGE_LIMIT = 4000;
9
+ export declare const HISTORY_ENTRIES = 20;
10
+ export declare const HISTORY_CHARACTERS = 24000;
11
+ export declare const LIST_ROW_LIMIT = 20;
12
+ export declare const PROPOSAL_TTL_MINUTES = 10;
13
+ export type AssistantProposal = {
14
+ id: string;
15
+ resource: string;
16
+ resourceLabel: string;
17
+ action: string;
18
+ recordId: number | null;
19
+ recordTitle: string | null;
20
+ input: Record<string, unknown> | null;
21
+ before: Record<string, unknown> | null;
22
+ version: number | null;
23
+ expiresAt: string;
24
+ };
25
+ export type AssistantTurnResult = {
26
+ reply: string;
27
+ proposals: AssistantProposal[];
28
+ usage: {
29
+ remainingToday: number;
30
+ };
31
+ };
32
+ export type AssistantStatus = {
33
+ available: boolean;
34
+ noticeAccepted: boolean;
35
+ };
36
+ type HistoryItem = {
37
+ role: 'user' | 'assistant';
38
+ content: string;
39
+ };
40
+ /** Validates a turn body: only the new message and prior user/assistant text. */
41
+ export declare function parseTurnInput(value: unknown): {
42
+ message: string;
43
+ history: HistoryItem[];
44
+ };
45
+ /**
46
+ * The built-in assistant (ADR 052). Every tool call runs through the shared resource tool
47
+ * runner as the signed-in actor; the model can only propose writes, which run when the
48
+ * user confirms them in a separate request.
49
+ */
50
+ export declare class Assistant {
51
+ private db;
52
+ private registry;
53
+ private resources;
54
+ private settings;
55
+ private client;
56
+ private options;
57
+ constructor(db: Knex, registry: ResourceRegistry, resources: ResourceService, settings: AssistantSettings, client: ChatClient, options?: {
58
+ now?: () => Date;
59
+ });
60
+ private now;
61
+ /** Whether the role rules grant `use` on `core.ai` (administrators always pass). */
62
+ canUse(actor: Actor): boolean;
63
+ status(actor: Actor): Promise<AssistantStatus>;
64
+ private noticeAccepted;
65
+ /** Permission, configuration and key; the provider key is returned for this call only. */
66
+ private usable;
67
+ /** Records that the user read the provider notice; an impersonator cannot accept it. */
68
+ acceptNotice(actor: Actor): Promise<void>;
69
+ startConversation(actor: Actor): Promise<{
70
+ id: number;
71
+ }>;
72
+ turn(actor: Actor, conversationId: number, body: unknown): Promise<AssistantTurnResult>;
73
+ private conversation;
74
+ private runtime;
75
+ private audit;
76
+ /**
77
+ * Runs one model tool call. Names, argument whitelist and the actor are fixed here;
78
+ * nothing in the arguments or in earlier tool output can widen them.
79
+ */
80
+ private runTool;
81
+ /** Stores a proposal for the user to confirm. No ResourceService write happens here. */
82
+ private propose;
83
+ /** Atomically takes the user's own unexpired proposal; null when there is none. */
84
+ private take;
85
+ /** Runs a proposal the user confirmed, through ResourceService as the user. */
86
+ confirm(actor: Actor, conversationId: number, id: string): Promise<unknown>;
87
+ reject(actor: Actor, conversationId: number, id: string): Promise<void>;
88
+ /** Sends one minimal request with the stored key; returns only a failure category. */
89
+ testConnection(): Promise<{
90
+ ok: boolean;
91
+ category: string | null;
92
+ }>;
93
+ /** Retention: conversation metadata after 30 days, used proposals after a day, usage after 90. */
94
+ prune(now?: Date): Promise<{
95
+ conversations: number;
96
+ proposals: number;
97
+ usage: number;
98
+ }>;
99
+ }
100
+ export {};