@ricajs/contracts 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.
Files changed (58) hide show
  1. package/LICENSE +661 -0
  2. package/README.md +153 -2
  3. package/action-review.d.ts +120 -0
  4. package/action-review.js +40 -0
  5. package/auto-review.d.ts +32 -0
  6. package/auto-review.js +14 -0
  7. package/commitments.d.ts +87 -0
  8. package/commitments.js +33 -0
  9. package/deployment-plugins.d.ts +7 -0
  10. package/deployment-plugins.js +2 -0
  11. package/health.d.ts +7 -0
  12. package/health.js +1 -0
  13. package/local-users.d.ts +17 -0
  14. package/local-users.js +6 -0
  15. package/management.d.ts +640 -0
  16. package/management.js +235 -0
  17. package/memory.d.ts +14 -0
  18. package/memory.js +1 -0
  19. package/model-provider.d.ts +40 -0
  20. package/model-provider.js +10 -0
  21. package/package.json +93 -3
  22. package/plans.d.ts +50 -0
  23. package/plans.js +20 -0
  24. package/platform-reader.d.ts +26 -0
  25. package/platform-reader.js +9 -0
  26. package/platform-reply-executor.d.ts +13 -0
  27. package/platform-reply-executor.js +3 -0
  28. package/plugin-status.d.ts +277 -0
  29. package/plugin-status.js +54 -0
  30. package/run-continuity.d.ts +84 -0
  31. package/run-continuity.js +1 -0
  32. package/schedules.d.ts +46 -0
  33. package/schedules.js +18 -0
  34. package/simulation-follow-up.d.ts +35 -0
  35. package/simulation-follow-up.js +29 -0
  36. package/simulation-observability.d.ts +223 -0
  37. package/simulation-observability.js +85 -0
  38. package/simulation-platform.d.ts +33 -0
  39. package/simulation-platform.js +7 -0
  40. package/source/action-review.ts +45 -0
  41. package/source/auto-review.ts +22 -0
  42. package/source/commitments.ts +39 -0
  43. package/source/deployment-plugins.ts +4 -0
  44. package/source/health.ts +4 -0
  45. package/source/local-users.ts +8 -0
  46. package/source/management.ts +246 -0
  47. package/source/memory.ts +15 -0
  48. package/source/model-provider.ts +29 -0
  49. package/source/package.json +43 -0
  50. package/source/plans.ts +22 -0
  51. package/source/platform-reader.ts +27 -0
  52. package/source/platform-reply-executor.ts +10 -0
  53. package/source/plugin-status.ts +67 -0
  54. package/source/run-continuity.ts +60 -0
  55. package/source/schedules.ts +22 -0
  56. package/source/simulation-follow-up.ts +35 -0
  57. package/source/simulation-observability.ts +94 -0
  58. package/source/simulation-platform.ts +39 -0
@@ -0,0 +1,246 @@
1
+ import { simulationPlatformId } from './simulation-platform.js'
2
+ import { z } from '@hono/zod-openapi'
3
+
4
+ export const resourceId = z.uuid().transform((value) => value.toLowerCase())
5
+ const slug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
6
+ const text = z.string().trim().min(1).max(240).regex(/^[^\p{Cc}]+$/u)
7
+ const shortText = text.max(120)
8
+ export const reasonInput = z.strictObject({ reason: text })
9
+ const optionalReasonInput = reasonInput.partial()
10
+ export const maxAiDisclosureLength = 3000
11
+ export const coreProfile = z.strictObject({
12
+ name: shortText.optional(),
13
+ aiDisclosure: z.string().trim().min(1).max(maxAiDisclosureLength)
14
+ .refine((value) => !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/u.test(value)),
15
+ dailyModelBudget: z.number().int().min(1024).max(100_000_000).optional(),
16
+ fictionalBackground: text.optional(),
17
+ values: z.array(shortText).max(16).optional(),
18
+ privacyRules: z.array(text).max(16).optional(),
19
+ })
20
+ const timezone = z.string().min(1).max(80).refine((timeZone) => {
21
+ try {
22
+ new Intl.DateTimeFormat('en', { timeZone })
23
+ return !/^[+-]/.test(timeZone)
24
+ } catch {
25
+ return false
26
+ }
27
+ })
28
+ const stateDeltas = z.array(z.number().min(-0.15).max(0.15)).length(7)
29
+ const stateRule = z.strictObject({
30
+ motivationHalfLifeHours: z.number().min(1).max(168),
31
+ affectHalfLifeHours: z.number().min(1).max(168),
32
+ deltas: z.strictObject({ POST: stateDeltas, MENTION: stateDeltas, REPLY: stateDeltas }),
33
+ })
34
+ const energyLevel = z.enum(['LOW', 'NORMAL', 'HIGH'])
35
+ export const dailyEnergyInput = reasonInput.extend({ utcDay: z.iso.date(), energy: energyLevel })
36
+ export const dailyEnergyView = z.object({
37
+ id: resourceId, utcDay: z.iso.date(), energy: energyLevel,
38
+ approvedAt: z.iso.datetime({ offset: true }),
39
+ })
40
+
41
+ export const maxIdentityWritingPromptLength = 4000
42
+
43
+ export const identityProfile = z.strictObject({
44
+ displayName: shortText.optional(),
45
+ timezone: timezone.optional(),
46
+ stateRule: stateRule.optional(),
47
+ duplicateReview: z.strictObject({
48
+ similarityPercent: z.number().int().min(65).max(100),
49
+ windowHours: z.number().int().min(1).max(168),
50
+ }).optional(),
51
+ autonomousGoal: z.strictObject({
52
+ topic: z.literal('REVIEW_INTERACTIONS'),
53
+ maxDays: z.number().int().min(1).max(7),
54
+ budget: z.number().int().min(1).max(100),
55
+ }).optional(),
56
+ writingStyle: z.enum(['neutral', 'formal', 'casual', 'concise']).optional(),
57
+ draftModelProfile: z.union([resourceId, z.literal('simulated')]).optional(),
58
+ writingPrompt: z.string().trim().min(1).max(maxIdentityWritingPromptLength)
59
+ .refine((value) => !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/u.test(value)).optional(),
60
+ })
61
+ export const characterInput = z.strictObject({
62
+ slug,
63
+ timezone,
64
+ coreProfile,
65
+ })
66
+ export const coreInput = optionalReasonInput.extend({ coreProfile })
67
+ export const identityInput = z.strictObject({ slug, roleProfile: identityProfile })
68
+ export const identityUpdate = optionalReasonInput.extend({ roleProfile: identityProfile })
69
+ export const simulationAccountRegistration = z.strictObject({
70
+ platform: simulationPlatformId,
71
+ instanceKey: shortText,
72
+ remoteAccountId: text,
73
+ })
74
+ export const accountInput = simulationAccountRegistration.extend({ identityId: resourceId })
75
+ export const accountBindingInput = z.strictObject({ registrationId: resourceId, identityId: resourceId })
76
+
77
+ export const accountRegistrationView = z.strictObject({
78
+ id: resourceId, platform: z.string(),
79
+ instanceKey: z.string(), remoteAccountId: z.string(),
80
+ })
81
+ export const automationEligibilityView = z.object({
82
+ accountId: resourceId, identityId: resourceId, bindingVersion: z.number().int(),
83
+ eligible: z.literal(false),
84
+ reasons: z.array(z.enum(['BINDING_INACTIVE', 'SIMULATION_ONLY', 'UNSUPPORTED_ADAPTER', 'EXTERNAL_AUTO_DISABLED'])),
85
+ })
86
+
87
+ export const controlInput = optionalReasonInput.extend({
88
+ scope: z.enum(['CHARACTER', 'IDENTITY', 'ACCOUNT']),
89
+ scopeId: resourceId,
90
+ operation: z.enum(['PAUSE', 'RESUME', 'REVOKE_ACCOUNT']),
91
+ })
92
+ export const membershipInput = reasonInput.extend({
93
+ subject: z.string().min(1).max(512).regex(/^[^\p{Cc}]+$/u),
94
+ action: z.enum(['GRANT', 'REVOKE']),
95
+ }).strict()
96
+ export const identityReflectionView = z.object({
97
+ identityId: resourceId, utcDay: z.iso.date(), coreVersion: z.number().int(), identityVersion: z.number().int(),
98
+ createdAt: z.iso.datetime({ offset: true }), candidateBeliefId: resourceId.nullable(),
99
+ fictionalProfile: z.object({ kind: z.literal('FICTIONAL_PROFILE'), present: z.boolean() }),
100
+ observedActivity: z.object({ kind: z.literal('OBSERVED_ACTIVITY'), simulatedReceipts: z.number().int().nonnegative() }),
101
+ unverifiedExternal: z.object({ kind: z.literal('UNVERIFIED_EXTERNAL'), inboundMessages: z.number().int().nonnegative() }),
102
+ })
103
+
104
+ const beliefKind = z.enum(['OPINION', 'PREFERENCE'])
105
+ const beliefEvidence = z.object({
106
+ memoryId: resourceId, memoryRevision: z.number().int().min(1).max(2_147_483_647),
107
+ direction: z.enum(['SUPPORT', 'OPPOSE']), weight: z.number().min(0).max(1),
108
+ })
109
+ export const beliefInput = reasonInput.extend({
110
+ kind: beliefKind, statement: z.string().trim().min(1).max(1000), evidence: z.array(beliefEvidence).min(1).max(16),
111
+ })
112
+ export const beliefRestoreInput = reasonInput.extend({ restoreVersion: z.number().int().min(1).max(2_147_483_647) })
113
+ export const beliefView = z.object({
114
+ id: resourceId, identityId: resourceId, version: z.number().int(), kind: beliefKind,
115
+ status: z.enum(['PENDING', 'ACTIVE', 'DISPUTED', 'INVALIDATED']),
116
+ statement: z.string().nullable(), confidence: z.number().nullable(), reason: z.string().nullable(),
117
+ restoredFrom: z.number().int().nullable(), createdAt: z.iso.datetime({ offset: true }),
118
+ evidence: z.array(beliefEvidence.extend({ sourceId: resourceId })),
119
+ remainingEvidence: z.object({
120
+ supportingSources: z.number().int().nonnegative(), opposingSources: z.number().int().nonnegative(),
121
+ confidence: z.number().min(0).max(1),
122
+ }).nullable(),
123
+ })
124
+
125
+ const goalStatus = z.enum(['DRAFT', 'ACTIVE', 'PAUSED', 'DONE', 'CANCELED', 'EXPIRED'])
126
+ export const manualGoalInput = reasonInput.extend({
127
+ title: text, status: z.enum(['DRAFT', 'ACTIVE', 'PAUSED', 'DONE', 'CANCELED']),
128
+ priority: z.number().int().min(0).max(100), budget: z.number().int().min(1).max(100),
129
+ dueAt: z.iso.datetime(), nextStep: text.optional(),
130
+ })
131
+ export const manualGoalView = z.object({
132
+ id: resourceId, identityId: resourceId, version: z.number().int(), origin: z.enum(['ADMIN', 'SELF']),
133
+ topic: z.literal('REVIEW_INTERACTIONS').nullable(), reflectionDay: z.iso.date().nullable(),
134
+ title: z.string(), status: goalStatus, priority: z.number().int(), budget: z.number().int(),
135
+ dueAt: z.iso.datetime({ offset: true }), nextStep: z.string().nullable(), createdAt: z.iso.datetime({ offset: true }),
136
+ })
137
+
138
+ export const contactBoundaryInput = reasonInput.extend({ blocked: z.boolean() })
139
+ export const contactBoundaryView = z.object({
140
+ id: resourceId, accountId: resourceId, version: z.number().int(), blocked: z.boolean(),
141
+ changedAt: z.iso.datetime({ offset: true }).nullable(), reason: z.string().nullable(),
142
+ })
143
+
144
+ export const memoryCorrectionInput = reasonInput.extend({
145
+ content: z.string().trim().min(1).max(1500).refine((content) => !content.includes('\0')),
146
+ })
147
+ export const memoryProvenanceView = z.object({
148
+ id: resourceId, revision: z.number().int(), status: z.enum(['ACTIVE', 'REVOKED']),
149
+ parentMemoryId: resourceId.nullable(),
150
+ sources: z.array(z.object({
151
+ id: resourceId, kind: z.string(), classification: z.enum(['PUBLIC','PERSONAL','CONFIDENTIAL','RESTRICTED']),
152
+ revokedAt: z.iso.datetime({ offset: true }).nullable(),
153
+ })),
154
+ corrections: z.array(z.object({
155
+ revision: z.number().int(), actorId: z.string(), reason: z.string(), createdAt: z.iso.datetime({ offset: true }),
156
+ })),
157
+ })
158
+
159
+ export const memoryGrantInput = reasonInput.extend({
160
+ memoryId: resourceId,
161
+ recipientIdentityId: resourceId,
162
+ recipientAccountId: resourceId.optional(),
163
+ recipientConversationId: resourceId.optional(),
164
+ recipientContactId: resourceId.optional(),
165
+ purpose: z.enum(['INTERNAL_CONTEXT', 'DECISION_SUPPORT', 'PUBLIC_REFERENCE', 'PRIVATE_REPLY']),
166
+ audience: resourceId.optional(),
167
+ validFrom: z.iso.datetime(),
168
+ validUntil: z.iso.datetime(),
169
+ })
170
+ export const listQuery = z.object({
171
+ limit: z.string().regex(/^(?:[1-9][0-9]?|100)$/).optional(),
172
+ cursor: resourceId.optional(),
173
+ })
174
+ export const memoryListQuery = listQuery.extend({
175
+ identityId: resourceId.optional(),
176
+ scope: z.enum(['CORE', 'IDENTITY', 'ACCOUNT', 'CONVERSATION']).optional(),
177
+ status: z.enum(['ACTIVE', 'REVOKED']).optional(),
178
+ })
179
+ export const grantListQuery = listQuery.extend({ memoryId: resourceId.optional() })
180
+ export const memberListQuery = listQuery.omit({ cursor: true }).extend({ after: membershipInput.shape.subject.optional() })
181
+ export const memberPage = z.object({
182
+ items: z.array(z.object({ subject: membershipInput.shape.subject })),
183
+ nextCursor: membershipInput.shape.subject.nullable(),
184
+ })
185
+ export const conversationListQuery = listQuery.extend({
186
+ accountId: resourceId,
187
+ channel: z.enum(['PUBLIC', 'PRIVATE']).optional(),
188
+ })
189
+ export const conversationOption = z.object({
190
+ id: resourceId, channel: z.enum(['PUBLIC', 'PRIVATE']), privateContactId: resourceId.nullable(),
191
+ contactLabel: z.string().nullable(),
192
+ })
193
+ export const beliefSummary = beliefView.pick({ id: true, version: true, kind: true })
194
+ export const contactSummary = contactBoundaryView.pick({ id: true, accountId: true, version: true, blocked: true })
195
+ .extend({ label: z.string().nullable() })
196
+
197
+ export const auditQuery = listQuery.extend({ runId: resourceId.optional(), targetId: resourceId.optional(), order: z.enum(['asc', 'desc']).optional() })
198
+ export const idempotencyHeader = z.object({
199
+ 'idempotency-key': z.string().regex(/^[a-zA-Z0-9._:-]{1,128}$/),
200
+ })
201
+ export const versionHeader = z.object({ 'if-match': z.string() })
202
+ export const errorResponse = z.object({
203
+ error: z.object({ code: z.string(), message: z.string(), requestId: z.uuid() }),
204
+ })
205
+ export const commandResponse = z.object({
206
+ id: z.uuid(),
207
+ requestId: z.uuid(),
208
+ version: z.number().int().optional(),
209
+ status: z.string().optional(),
210
+ authEpoch: z.number().int().optional(),
211
+ })
212
+ export const characterView = z.object({
213
+ id: z.uuid(), slug: z.string(), timezone: z.string(), status: z.string(),
214
+ version: z.number().int().nullable(), profile: coreProfile.nullable(),
215
+ })
216
+ export const characterWorkspaceView = characterView.extend({
217
+ simulationPlatforms: z.array(accountInput.shape.platform),
218
+ })
219
+ export const identityView = z.object({
220
+ id: z.uuid(), slug: z.string(), status: z.string(),
221
+ version: z.number().int().nullable(), profile: identityProfile.nullable(),
222
+ })
223
+ export const accountView = z.object({
224
+ id: z.uuid(), identityId: z.uuid(), platform: z.string(), instanceKey: z.string(),
225
+ status: z.string(), version: z.number().int(),
226
+ })
227
+ export const memoryView = z.object({
228
+ id: z.uuid(), identityId: z.uuid().nullable(), accountId: z.uuid().nullable(),
229
+ conversationId: z.uuid().nullable(), scope: z.string(), visibility: z.string(),
230
+ status: z.string(), createdAt: z.iso.datetime(), expiresAt: z.iso.datetime().nullable(),
231
+ })
232
+ export const memoryDetailView = z.object({ memory: memoryView, provenance: memoryProvenanceView })
233
+ export const grantView = z.object({
234
+ id: z.uuid(), memoryId: z.uuid(), recipientIdentityId: z.uuid(),
235
+ recipientAccountId: z.uuid().nullable(), recipientConversationId: z.uuid().nullable(),
236
+ recipientContactId: z.uuid().nullable(), purpose: z.string(), audience: z.string().nullable(),
237
+ validFrom: z.iso.datetime(), validUntil: z.iso.datetime(), revokedAt: z.iso.datetime().nullable(),
238
+ })
239
+ export const auditView = z.object({
240
+ id: z.uuid(), operation: z.string(), actorId: z.string(), targetId: z.uuid(),
241
+ requestId: z.uuid(), digest: z.string(), createdAt: z.iso.datetime(),
242
+ })
243
+
244
+ export function pageView<T extends z.ZodType>(item: T) {
245
+ return z.object({ items: z.array(item), nextCursor: z.string().nullable() })
246
+ }
@@ -0,0 +1,15 @@
1
+ export type MemoryCandidate = {
2
+ id: string
3
+ content: string
4
+ revision: number
5
+ importance: number
6
+ confidence: number
7
+ createdAt: Date
8
+ scope: 'CORE' | 'IDENTITY' | 'ACCOUNT' | 'CONVERSATION'
9
+ sameConversation: boolean
10
+ }
11
+
12
+ export type RankedMemory = MemoryCandidate & {
13
+ score: number
14
+ estimatedTokens: number
15
+ }
@@ -0,0 +1,29 @@
1
+ import type { RunContinuity, RunTime } from './run-continuity.js'
2
+ import type { PublicReplyReview } from './auto-review.js'
3
+
4
+ export const maxSimulatedTextLength = 4_000
5
+
6
+ export class ModelProviderError extends Error {
7
+ constructor(readonly code: 'HTTP_ERROR' | 'REQUEST_FAILED' | 'INVALID_OUTPUT', readonly status?: number) {
8
+ super(code)
9
+ }
10
+ }
11
+
12
+ export type ModelEvidence = Readonly<{ id: string; revision: number; content: string }>
13
+
14
+ type ModelInput = Readonly<{
15
+ text: string
16
+ evidence: readonly ModelEvidence[]
17
+ }>
18
+
19
+ export type WritingStyle = 'neutral' | 'formal' | 'casual' | 'concise'
20
+ export type ModelAttribution = Readonly<{ characterId: string; identityId: string; platform: string }>
21
+
22
+ export type ModelProvider = Readonly<{
23
+ hostedProvider?: string
24
+ hostedModel?: string
25
+ review?(prompt: string, reply: PublicReplyReview, signal: AbortSignal, attribution?: ModelAttribution): Promise<unknown>
26
+ decide(input: ModelInput & Readonly<{ context: RunContinuity }>, signal: AbortSignal): Promise<unknown>
27
+ write(input: ModelInput & Readonly<{ style: WritingStyle; time: RunTime; corePrompt?: string; identityPrompt?: string;
28
+ suggestFollowUp?: boolean; attribution?: ModelAttribution }>, signal: AbortSignal): Promise<unknown>
29
+ }>
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@ricajs/contracts",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "exports": {
7
+ "./model-provider": "./model-provider.ts",
8
+ "./run-continuity": "./run-continuity.ts",
9
+ "./simulation-platform": "./simulation-platform.ts",
10
+ "./platform-reader": "./platform-reader.ts",
11
+ "./platform-reply-executor": "./platform-reply-executor.ts",
12
+ "./management": "./management.ts",
13
+ "./deployment-plugins": "./deployment-plugins.ts",
14
+ "./health": "./health.ts",
15
+ "./action-review": "./action-review.ts",
16
+ "./local-users": "./local-users.ts",
17
+ "./plugin-status": "./plugin-status.ts",
18
+ "./simulation-observability": "./simulation-observability.ts",
19
+ "./plans": "./plans.ts",
20
+ "./commitments": "./commitments.ts",
21
+ "./schedules": "./schedules.ts",
22
+ "./auto-review": "./auto-review.ts",
23
+ "./simulation-follow-up": "./simulation-follow-up.ts",
24
+ "./memory": "./memory.ts"
25
+ },
26
+ "dependencies": {
27
+ "@hono/zod-openapi": "^1.6.3",
28
+ "@ricajs/plugin-host": "workspace:*"
29
+ },
30
+ "license": "AGPL-3.0-only",
31
+ "engines": {
32
+ "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
33
+ },
34
+ "repository": {
35
+ "type": "git",
36
+ "url": "git+https://github.com/ifrvn/rica.git",
37
+ "directory": "packages/contracts"
38
+ },
39
+ "publishConfig": {
40
+ "access": "public",
41
+ "registry": "https://registry.npmjs.org/"
42
+ }
43
+ }
@@ -0,0 +1,22 @@
1
+ import { z } from '@hono/zod-openapi'
2
+ import { resourceId } from './management.js'
3
+ import { scheduleUpdate } from './schedules.js'
4
+
5
+ export const planningTask = z.string().trim().min(1).max(300).refine((value) => !value.includes('\0'))
6
+ const participantInput = z.strictObject({ identityId: resourceId, accountId: resourceId, task: planningTask })
7
+ export const planInput = scheduleUpdate.extend({
8
+ title: z.string().trim().min(1).max(72).regex(/^[^\p{Cc}]+$/u),
9
+ participants: z.array(participantInput).min(1).max(20).refine((items) =>
10
+ new Set(items.map(({ identityId }) => identityId)).size === items.length, 'Select each identity once'),
11
+ })
12
+ export const planStateInput = z.strictObject({ enabled: z.boolean() })
13
+ export const planView = planInput.extend({
14
+ id: resourceId,
15
+ version: z.number().int().positive(),
16
+ source: z.enum(['MANUAL', 'AI']),
17
+ humanEdited: z.boolean(),
18
+ participants: z.array(participantInput.extend({
19
+ platform: z.string(), accountStatus: z.string(), nextAt: z.iso.datetime().nullable(),
20
+ lastRunId: resourceId.nullable(),
21
+ })),
22
+ })
@@ -0,0 +1,27 @@
1
+ export type PlatformEventPage = Readonly<{
2
+ items: readonly Readonly<{
3
+ seq: string
4
+ type: 'POST_REPLIED' | 'COMMENT_REPLIED' | 'AGENT_MENTIONED'
5
+ postId: string
6
+ commentId: string | null
7
+ createdAt: string
8
+ }>[]
9
+ nextCursor: string
10
+ hasMore: boolean
11
+ historyLost: boolean
12
+ }>
13
+
14
+ export type PlatformEventReader = Readonly<{
15
+ endpoint: string
16
+ verify(): Promise<{ id: string; pollIntervalSeconds: number }>
17
+ readEvents(cursor: string | null): Promise<PlatformEventPage>
18
+ }>
19
+
20
+ export type PlatformReadFailure = 'CREDENTIAL_INVALID' | 'ACCESS_DENIED' | 'RATE_LIMITED'
21
+ | 'SERVICE_UNAVAILABLE' | 'COMMUNITY_CLOSED'
22
+
23
+ export class PlatformReadError<Reason extends string = PlatformReadFailure> extends Error {
24
+ constructor(readonly reason: Reason, readonly retrySeconds = 0) {
25
+ super(reason)
26
+ }
27
+ }
@@ -0,0 +1,10 @@
1
+ import { PlatformReadError, type PlatformReadFailure } from './platform-reader.js'
2
+
3
+ export type PlatformReplyExecutor = Readonly<{
4
+ endpoint: string
5
+ verify(): Promise<{ id: string }>
6
+ readTarget(postId: string): Promise<{ isLocked: boolean }>
7
+ sendReply(postId: string, idempotencyKey: string, content: string): Promise<string>
8
+ }>
9
+
10
+ export class PlatformReplyError extends PlatformReadError<PlatformReadFailure | 'POST_LOCKED'> {}
@@ -0,0 +1,67 @@
1
+ import { z } from '@hono/zod-openapi'
2
+
3
+ const pluginService = z.string().regex(/^[a-z0-9-]{1,80}$/)
4
+ export type PluginService = z.infer<typeof pluginService>
5
+
6
+ const pluginIdentity = z.strictObject({
7
+ id: z.string().regex(/^[a-z0-9-]{1,80}$/),
8
+ version: z.string().regex(/^\d+\.\d+\.\d+$/),
9
+ contractVersion: z.number().int().positive(),
10
+ kind: z.enum(['platform', 'model', 'platform-reader', 'platform-reply-executor']),
11
+ })
12
+ export type PluginMetadata = z.infer<typeof pluginIdentity>
13
+
14
+ const releaseVersion = z.string().regex(/^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/u)
15
+ const releaseUrl = z.url({ protocol: /^https$/ }).max(2048).refine((value) => {
16
+ const url = new URL(value)
17
+ return !url.username && !url.password && !url.search && !url.hash
18
+ })
19
+ const releaseComponent = pluginIdentity.extend({ version: releaseVersion })
20
+ export const pluginReleaseManifest = z.strictObject({
21
+ schemaVersion: z.literal(1),
22
+ ricaVersion: releaseVersion,
23
+ releaseUrl,
24
+ components: z.array(releaseComponent).min(1).max(100).refine((entries) =>
25
+ new Set(entries.map(({ kind, id }) => kind + '/' + id)).size === entries.length),
26
+ })
27
+
28
+ const pluginUpgrade = z.object({
29
+ id: pluginIdentity.shape.id,
30
+ components: z.array(z.object({
31
+ service: pluginService,
32
+ current: pluginIdentity,
33
+ target: releaseComponent.nullable(),
34
+ problem: z.enum(['MISSING_COMPONENT', 'INCOMPATIBLE_CONTRACT', 'DOWNGRADE']).nullable(),
35
+ })),
36
+ })
37
+ export const pluginReleaseView = z.discriminatedUnion('status', [
38
+ z.object({ status: z.enum(['UNCONFIGURED', 'UNAVAILABLE']) }),
39
+ z.object({
40
+ status: z.literal('AVAILABLE'), ricaVersion: releaseVersion, releaseUrl,
41
+ upgrades: z.array(pluginUpgrade), aligned: z.array(pluginUpgrade),
42
+ }),
43
+ ])
44
+ export type PluginReleaseView = z.infer<typeof pluginReleaseView>
45
+
46
+ export const pluginDiagnostic = z.enum([
47
+ 'UNKNOWN_PLUGIN', 'DUPLICATE_SELECTION', 'INVALID_CONFIG', 'MISSING_SERVICE', 'START_FAILED',
48
+ 'INCOMPATIBLE_CONTRACT', 'DUPLICATE_PLUGIN', 'INVALID_MANIFEST', 'DEPENDENCY_UNAVAILABLE', 'OPERATION_FAILED',
49
+ ])
50
+ export type PluginDiagnostic = z.infer<typeof pluginDiagnostic>
51
+
52
+ export const pluginReport = z.strictObject({
53
+ status: z.enum(['READY', 'COMPLETED', 'FAILED']),
54
+ observedAt: z.iso.datetime(),
55
+ plugins: z.array(pluginIdentity).max(20),
56
+ diagnostic: pluginDiagnostic.optional(),
57
+ })
58
+ export type PluginReport = z.infer<typeof pluginReport>
59
+
60
+ export const pluginStatusView = z.object({
61
+ release: pluginReleaseView.optional(),
62
+ services: z.array(z.object({
63
+ service: pluginService,
64
+ catalog: z.array(pluginIdentity),
65
+ report: pluginReport.nullable(),
66
+ })),
67
+ })
@@ -0,0 +1,60 @@
1
+ export type RunTime = Readonly<{
2
+ occurredAt: string
3
+ now: string
4
+ timezone: string
5
+ localDate: string
6
+ eventLocalDate: string
7
+ localHour: number
8
+ }>
9
+
10
+ export type IdentityState = Readonly<{
11
+ revision: number | null
12
+ ruleVersion: number
13
+ configurationVersion: number | null
14
+ sharedEnergy: 'LOW' | 'NORMAL' | 'HIGH'
15
+ motivation: { exploration: number; expression: number; social: number; rest: number }
16
+ affect: { pleasure: number; arousal: number; energy: number }
17
+ }>
18
+
19
+ export type SubjectiveBelief = Readonly<{
20
+ id: string
21
+ version: number
22
+ kind: 'OPINION' | 'PREFERENCE'
23
+ statement: string
24
+ confidence: number
25
+ subjective: true
26
+ }>
27
+
28
+ export type Continuity = {
29
+ runId: string
30
+ characterId: string
31
+ identityId: string
32
+ accountId: string
33
+ triggerId: string
34
+ bindingVersion: number
35
+ mode: 'SIMULATION'
36
+ platform: string
37
+ instanceKey: string
38
+ conversationId: string | null
39
+ contactId: string | null
40
+ occurredAt: string
41
+ now: string
42
+ timezone: string
43
+ recent: readonly { kind: string; occurredAt: string }[]
44
+ nextCommitmentAt: string | null
45
+ nextScheduleAt: string | null
46
+ relationship: { confirmedInteractions: number; lastConfirmedAt: string | null } | null
47
+ goals: readonly { id: string; version: number; origin: 'ADMIN' | 'SELF'; title: string; budget: number; priority: number; dueAt: string; nextStep: string | null }[]
48
+ self: {
49
+ coreVersion: number
50
+ name: string | null
51
+ fictionalBackground: string | null
52
+ facts: readonly { id: string; revision: number; content: string }[]
53
+ }
54
+ }
55
+
56
+ export type RunContinuity = Omit<Continuity, 'occurredAt' | 'now' | 'timezone'> & {
57
+ time: RunTime
58
+ identityState: IdentityState
59
+ beliefs: readonly SubjectiveBelief[]
60
+ }
@@ -0,0 +1,22 @@
1
+ import { z } from '@hono/zod-openapi'
2
+ import { characterInput, resourceId } from './management.js'
3
+
4
+ const scheduleRule = z.discriminatedUnion('kind', [
5
+ z.strictObject({ kind: z.literal('DAILY'), localTime: z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d$/) }),
6
+ z.strictObject({ kind: z.literal('REMINDER'), dueAt: z.iso.datetime() }),
7
+ ])
8
+
9
+ export const scheduleUpdate = z.strictObject({
10
+ zone: characterInput.shape.timezone, enabled: z.boolean(), rule: scheduleRule,
11
+ })
12
+
13
+ export const scheduleInput = scheduleUpdate.extend({
14
+ scheduleKey: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
15
+ accountId: resourceId, conversationId: resourceId, contactId: resourceId.optional(),
16
+ })
17
+
18
+ export const scheduleView = scheduleUpdate.extend({
19
+ id: resourceId, scheduleKey: z.string(), accountId: resourceId,
20
+ conversationId: resourceId, contactId: resourceId.nullable(),
21
+ version: z.number().int(), commitmentId: resourceId.nullable(), nextAt: z.iso.datetime().nullable(),
22
+ })
@@ -0,0 +1,35 @@
1
+ import { z } from '@hono/zod-openapi'
2
+ import { planningTask } from './plans.js'
3
+
4
+ const fields = {
5
+ kind: z.enum(['PLAN', 'COMMITMENT']),
6
+ title: z.string().trim().min(1).max(72).regex(/^[^\p{Cc}]+$/u),
7
+ task: planningTask,
8
+ dueAt: z.iso.datetime().optional(),
9
+ dailyAt: z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d$/).optional(),
10
+ }
11
+ const timing = ({ kind, dueAt, dailyAt }: {
12
+ kind: 'PLAN' | 'COMMITMENT'; dueAt?: string; dailyAt?: string
13
+ }) => dailyAt ? kind === 'PLAN' && !dueAt : !!dueAt
14
+ const platform = z.string().regex(/^[a-z0-9-]{1,80}$/u)
15
+ const participantTask = z.strictObject({ platform, task: planningTask })
16
+
17
+ export const modelFollowUp = z.strictObject({
18
+ ...fields,
19
+ additionalTasks: z.array(participantTask).max(2).optional(),
20
+ collaboratorPlatforms: z.array(platform).max(2).optional(),
21
+ }).refine(timing).refine(({ kind, additionalTasks, collaboratorPlatforms }) =>
22
+ kind === 'PLAN' ? !collaboratorPlatforms?.length : !additionalTasks?.length)
23
+
24
+ export const simulationFollowUp = z.strictObject({
25
+ ...fields,
26
+ participants: z.array(z.strictObject({
27
+ platform,
28
+ task: planningTask.optional(),
29
+ identityId: z.uuid(),
30
+ accountId: z.uuid(),
31
+ identity: z.string(),
32
+ account: z.string(),
33
+ })).max(2).optional(),
34
+ zone: z.string().optional(),
35
+ }).refine(timing).refine(({ dailyAt, zone }) => !dailyAt || !!zone)