neotoma 0.22.0 → 0.22.2

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 (118) hide show
  1. package/dist/actions.d.ts +13 -0
  2. package/dist/actions.d.ts.map +1 -1
  3. package/dist/actions.js +236 -93
  4. package/dist/actions.js.map +1 -1
  5. package/dist/cli/index.d.ts.map +1 -1
  6. package/dist/cli/index.js +11 -0
  7. package/dist/cli/index.js.map +1 -1
  8. package/dist/config.d.ts +13 -0
  9. package/dist/config.d.ts.map +1 -1
  10. package/dist/config.js +90 -0
  11. package/dist/config.js.map +1 -1
  12. package/dist/docs/api/rest_api.md +81 -0
  13. package/dist/docs/developer/getting_started.md +45 -0
  14. package/dist/docs/developer/mcp/proxy.md +48 -28
  15. package/dist/docs/developer/npm_scripts.md +10 -4
  16. package/dist/docs/infrastructure/client_instance_deployment.md +50 -2
  17. package/dist/docs/operations/configuration.md +44 -1
  18. package/dist/docs/security/advisories/2026-08-26-jwt-bearer-unverified-fallback-auth-bypass.md +59 -0
  19. package/dist/docs/security/advisories/README.md +1 -0
  20. package/dist/docs/security/practices.md +5 -1
  21. package/dist/docs/subsystems/agent_session_architecture.md +69 -0
  22. package/dist/docs/subsystems/usage_digest.md +127 -0
  23. package/dist/docs/testing/automated_test_catalog.md +49 -26
  24. package/dist/docs/testing/testing_standard.md +1 -1
  25. package/dist/middleware/aauth_admission.js +1 -1
  26. package/dist/middleware/aauth_admission.js.map +1 -1
  27. package/dist/middleware/db_abort_context.d.ts +24 -0
  28. package/dist/middleware/db_abort_context.d.ts.map +1 -0
  29. package/dist/middleware/db_abort_context.js +41 -0
  30. package/dist/middleware/db_abort_context.js.map +1 -0
  31. package/dist/proxy/mcp_stdio_proxy.d.ts +134 -6
  32. package/dist/proxy/mcp_stdio_proxy.d.ts.map +1 -1
  33. package/dist/proxy/mcp_stdio_proxy.js +373 -17
  34. package/dist/proxy/mcp_stdio_proxy.js.map +1 -1
  35. package/dist/repositories/sqlite/local_db_adapter.d.ts.map +1 -1
  36. package/dist/repositories/sqlite/local_db_adapter.js +20 -0
  37. package/dist/repositories/sqlite/local_db_adapter.js.map +1 -1
  38. package/dist/repositories/sqlite/sqlite_client.d.ts.map +1 -1
  39. package/dist/repositories/sqlite/sqlite_client.js +10 -0
  40. package/dist/repositories/sqlite/sqlite_client.js.map +1 -1
  41. package/dist/repositories/worker/worker_file_database.d.ts +135 -1
  42. package/dist/repositories/worker/worker_file_database.d.ts.map +1 -1
  43. package/dist/repositories/worker/worker_file_database.js +726 -27
  44. package/dist/repositories/worker/worker_file_database.js.map +1 -1
  45. package/dist/server.d.ts.map +1 -1
  46. package/dist/server.js +182 -77
  47. package/dist/server.js.map +1 -1
  48. package/dist/services/attachment_resolution.d.ts +149 -0
  49. package/dist/services/attachment_resolution.d.ts.map +1 -0
  50. package/dist/services/attachment_resolution.js +206 -0
  51. package/dist/services/attachment_resolution.js.map +1 -0
  52. package/dist/services/attachment_resolution_sqlite.d.ts +57 -0
  53. package/dist/services/attachment_resolution_sqlite.d.ts.map +1 -0
  54. package/dist/services/attachment_resolution_sqlite.js +75 -0
  55. package/dist/services/attachment_resolution_sqlite.js.map +1 -0
  56. package/dist/services/entity_queries.d.ts.map +1 -1
  57. package/dist/services/entity_queries.js +85 -23
  58. package/dist/services/entity_queries.js.map +1 -1
  59. package/dist/services/entity_snapshot_at_time.d.ts.map +1 -1
  60. package/dist/services/entity_snapshot_at_time.js +23 -3
  61. package/dist/services/entity_snapshot_at_time.js.map +1 -1
  62. package/dist/services/file_input_diagnostics.d.ts +89 -0
  63. package/dist/services/file_input_diagnostics.d.ts.map +1 -0
  64. package/dist/services/file_input_diagnostics.js +174 -0
  65. package/dist/services/file_input_diagnostics.js.map +1 -0
  66. package/dist/services/interpretation.d.ts.map +1 -1
  67. package/dist/services/interpretation.js +22 -8
  68. package/dist/services/interpretation.js.map +1 -1
  69. package/dist/services/mcp_auth.d.ts +19 -3
  70. package/dist/services/mcp_auth.d.ts.map +1 -1
  71. package/dist/services/mcp_auth.js +23 -33
  72. package/dist/services/mcp_auth.js.map +1 -1
  73. package/dist/services/mcp_oauth.d.ts +14 -1
  74. package/dist/services/mcp_oauth.d.ts.map +1 -1
  75. package/dist/services/mcp_oauth.js +86 -1
  76. package/dist/services/mcp_oauth.js.map +1 -1
  77. package/dist/services/raw_storage.d.ts.map +1 -1
  78. package/dist/services/raw_storage.js +14 -2
  79. package/dist/services/raw_storage.js.map +1 -1
  80. package/dist/services/readiness.d.ts +85 -0
  81. package/dist/services/readiness.d.ts.map +1 -0
  82. package/dist/services/readiness.js +93 -0
  83. package/dist/services/readiness.js.map +1 -0
  84. package/dist/services/route_shadowing.d.ts +67 -0
  85. package/dist/services/route_shadowing.d.ts.map +1 -0
  86. package/dist/services/route_shadowing.js +126 -0
  87. package/dist/services/route_shadowing.js.map +1 -0
  88. package/dist/services/schema_definitions.d.ts.map +1 -1
  89. package/dist/services/schema_definitions.js +171 -0
  90. package/dist/services/schema_definitions.js.map +1 -1
  91. package/dist/services/schema_lag_repair.d.ts.map +1 -1
  92. package/dist/services/schema_lag_repair.js +32 -12
  93. package/dist/services/schema_lag_repair.js.map +1 -1
  94. package/dist/services/schema_registry.d.ts.map +1 -1
  95. package/dist/services/schema_registry.js +12 -5
  96. package/dist/services/schema_registry.js.map +1 -1
  97. package/dist/services/snapshot_computation.d.ts.map +1 -1
  98. package/dist/services/snapshot_computation.js +12 -8
  99. package/dist/services/snapshot_computation.js.map +1 -1
  100. package/dist/services/subscriptions/sse_hub.d.ts.map +1 -1
  101. package/dist/services/subscriptions/sse_hub.js +19 -1
  102. package/dist/services/subscriptions/sse_hub.js.map +1 -1
  103. package/dist/shared/action_handlers/entity_handlers.d.ts.map +1 -1
  104. package/dist/shared/action_handlers/entity_handlers.js +110 -26
  105. package/dist/shared/action_handlers/entity_handlers.js.map +1 -1
  106. package/dist/shared/action_schemas.d.ts +6 -6
  107. package/dist/shared/contract_mappings.d.ts.map +1 -1
  108. package/dist/shared/contract_mappings.js +8 -1
  109. package/dist/shared/contract_mappings.js.map +1 -1
  110. package/dist/shared/openapi_types.d.ts +108 -3
  111. package/dist/shared/openapi_types.d.ts.map +1 -1
  112. package/dist/tool_definitions.d.ts.map +1 -1
  113. package/dist/tool_definitions.js +18 -13
  114. package/dist/tool_definitions.js.map +1 -1
  115. package/openapi.yaml +83 -3
  116. package/package.json +2 -1
  117. package/skills/status/SKILL.md +0 -1
  118. package/skills/where/SKILL.md +315 -0
@@ -30,7 +30,10 @@ export interface paths {
30
30
  path?: never;
31
31
  cookie?: never;
32
32
  };
33
- /** Health check */
33
+ /**
34
+ * Liveness check
35
+ * @description Reports that the process is running. Does NOT touch the database — it returns 200 throughout a total read outage, so it must not be used as a health check or as evidence the server can serve requests. Use /ready for that.
36
+ */
34
37
  get: operations["healthCheck"];
35
38
  put?: never;
36
39
  post?: never;
@@ -40,6 +43,26 @@ export interface paths {
40
43
  patch?: never;
41
44
  trace?: never;
42
45
  };
46
+ "/ready": {
47
+ parameters: {
48
+ query?: never;
49
+ header?: never;
50
+ path?: never;
51
+ cookie?: never;
52
+ };
53
+ /**
54
+ * Readiness check
55
+ * @description Runs a bounded real read against the database. Returns 503 when that read errors or exceeds NEOTOMA_READY_DB_TIMEOUT_MS (default 20s). This is the endpoint Fly health checks target. A 200 means the process is up and the database completed a trivial indexed read within the bound; it does not prove that heavier queries or writes succeed.
56
+ */
57
+ get: operations["readinessCheck"];
58
+ put?: never;
59
+ post?: never;
60
+ delete?: never;
61
+ options?: never;
62
+ head?: never;
63
+ patch?: never;
64
+ trace?: never;
65
+ };
43
66
  "/openapi.yaml": {
44
67
  parameters: {
45
68
  query?: never;
@@ -2270,6 +2293,19 @@ export interface paths {
2270
2293
  export type webhooks = Record<string, never>;
2271
2294
  export interface components {
2272
2295
  schemas: {
2296
+ /** @description Result of the /ready database probe. */
2297
+ ReadinessResult: {
2298
+ /** @description True only when the database completed the probe read. */
2299
+ ok?: boolean;
2300
+ checks?: {
2301
+ /** @enum {string} */
2302
+ database?: "ok" | "failed";
2303
+ };
2304
+ /** @description Probe duration, reported on success and failure alike. Degradation is progressive, so the trend matters as much as the verdict. */
2305
+ latency_ms?: number;
2306
+ /** @description Failure reason. Present only when ok is false. */
2307
+ error?: string;
2308
+ };
2273
2309
  FileUrlResponse: {
2274
2310
  /** @description Signed URL for accessing the file */
2275
2311
  url?: string;
@@ -4102,7 +4138,7 @@ export interface operations {
4102
4138
  };
4103
4139
  requestBody?: never;
4104
4140
  responses: {
4105
- /** @description Server is healthy */
4141
+ /** @description Process is running */
4106
4142
  200: {
4107
4143
  headers: {
4108
4144
  [name: string]: unknown;
@@ -4115,6 +4151,35 @@ export interface operations {
4115
4151
  };
4116
4152
  };
4117
4153
  };
4154
+ readinessCheck: {
4155
+ parameters: {
4156
+ query?: never;
4157
+ header?: never;
4158
+ path?: never;
4159
+ cookie?: never;
4160
+ };
4161
+ requestBody?: never;
4162
+ responses: {
4163
+ /** @description Server is ready to serve reads */
4164
+ 200: {
4165
+ headers: {
4166
+ [name: string]: unknown;
4167
+ };
4168
+ content: {
4169
+ "application/json": components["schemas"]["ReadinessResult"];
4170
+ };
4171
+ };
4172
+ /** @description Database read failed or timed out */
4173
+ 503: {
4174
+ headers: {
4175
+ [name: string]: unknown;
4176
+ };
4177
+ content: {
4178
+ "application/json": components["schemas"]["ReadinessResult"];
4179
+ };
4180
+ };
4181
+ };
4182
+ };
4118
4183
  getOpenApiSpec: {
4119
4184
  parameters: {
4120
4185
  query?: never;
@@ -4209,13 +4274,53 @@ export interface operations {
4209
4274
  };
4210
4275
  requestBody?: never;
4211
4276
  responses: {
4212
- /** @description Redirect to authorization URL */
4277
+ /**
4278
+ * @description Redirect to the authorization URL, or to /mcp/oauth/key-auth when
4279
+ * NEOTOMA_REQUIRE_KEY_FOR_OAUTH is set and the request carries no valid
4280
+ * key session.
4281
+ */
4213
4282
  302: {
4214
4283
  headers: {
4215
4284
  [name: string]: unknown;
4216
4285
  };
4217
4286
  content?: never;
4218
4287
  };
4288
+ /**
4289
+ * @description Authorization refused before any redirect. The body is a plain-text
4290
+ * sentence addressed to the human in the browser, NOT an ErrorEnvelope:
4291
+ * this endpoint is reached by a user-agent mid-OAuth-redirect, so the
4292
+ * response is rendered directly in the address bar. A JSON envelope
4293
+ * would be read by nobody at this point in the flow. Machine clients
4294
+ * MUST treat any 400 here as a terminal refusal of the authorization
4295
+ * request and MUST NOT parse the body; the reason is carried by the
4296
+ * server's structured warn log, not by this response.
4297
+ *
4298
+ * Emitted for: a missing `redirect_uri`; a missing `state`; a missing
4299
+ * or non-S256 PKCE challenge on a non-OpenAI redirect; a `dev_stub`
4300
+ * request while dev_stub is disabled; and a `redirect_uri` that is not
4301
+ * on the tunnel allowlist (built-in entries plus any exact callback
4302
+ * URLs configured in NEOTOMA_OAUTH_TRUSTED_CALLBACK_URLS).
4303
+ */
4304
+ 400: {
4305
+ headers: {
4306
+ [name: string]: unknown;
4307
+ };
4308
+ content: {
4309
+ "text/plain": string;
4310
+ };
4311
+ };
4312
+ /**
4313
+ * @description Authorization failed unexpectedly. Plain-text body, for the same
4314
+ * browser-facing reason as the 400 above.
4315
+ */
4316
+ 500: {
4317
+ headers: {
4318
+ [name: string]: unknown;
4319
+ };
4320
+ content: {
4321
+ "text/plain": string;
4322
+ };
4323
+ };
4219
4324
  };
4220
4325
  };
4221
4326
  mcpOAuthToken: {