@lincyaw/kernel 1.0.0-rc.80 → 1.0.0-rc.81

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": "@lincyaw/kernel",
3
- "version": "1.0.0-rc.80",
3
+ "version": "1.0.0-rc.81",
4
4
  "description": "Presmium's shared kernel: the IR and plugin contracts, the service registry, anchors and checks",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/authoring.ts CHANGED
@@ -34,7 +34,7 @@ export const DOCUMENT_CHANGE_JSON_SCHEMA: Schema = {
34
34
  operation('replaceAsset', { asset: ref('Asset') }),
35
35
  ] },
36
36
  DocumentChange: {
37
- ...object({ id, baseDocumentVersion: { type: 'string', minLength: 1, maxLength: 128 }, replacement: ref('TeachingDocument'), operations: { type: 'array', minItems: 1, maxItems: 1000, items: ref('DocumentOperation') }, fileChanges: { type: 'array', maxItems: 15, items: object({ path: { type: 'string', minLength: 1 }, content: { type: 'string' }, base: { type: ['string', 'null'] } }) } }, ['id', 'baseDocumentVersion']),
37
+ ...object({ id, baseDocumentVersion: { type: 'string', minLength: 1, maxLength: 128 }, replacement: ref('TeachingDocument'), operations: { type: 'array', minItems: 1, maxItems: 1000, items: ref('DocumentOperation') }, fileChanges: { type: 'array', maxItems: 15, items: object({ path: { type: 'string', minLength: 1, description: 'Workspace-relative path within the selected document, including its directory prefix. For document papers/re-search, use papers/re-search/scenes/story.ts. Scene implementation paths inside lecture.json are document-relative instead.' }, content: { type: 'string' }, base: { type: ['string', 'null'] } }) } }, ['id', 'baseDocumentVersion']),
38
38
  oneOf: [{ required: ['replacement'], not: { required: ['operations'] } }, { required: ['operations'], not: { required: ['replacement'] } }],
39
39
  },
40
40
  },
@@ -20,7 +20,7 @@ export interface DocumentMediaUploads {
20
20
  }
21
21
  export type DocumentMediaLocation = { path: string, upload?: never } | { upload: string, path?: never }
22
22
  export type DocumentMediaFile = ({ path: string, upload?: never, name?: never } | { upload: string, name: string, path?: never }) & { sha256: string, byteLength: number }
23
- export const MEDIA_LOCATION_PROPERTIES = { path: { type: 'string', minLength: 1, maxLength: 1024 }, upload: { type: 'string', pattern: '^[a-f0-9]{64}$' } } as const
23
+ export const MEDIA_LOCATION_PROPERTIES = { path: { type: 'string', minLength: 1, maxLength: 1024, description: 'Workspace-relative path to a regular file within the selected document, including its directory prefix; for document papers/re-search, use papers/re-search/figures/result.png. Workspace cache files outside that document are unavailable; stage the file inside the document or use a ready upload reference.' }, upload: { type: 'string', pattern: '^[a-f0-9]{64}$' } } as const
24
24
  export const MEDIA_LOCATION_CHOICES = [{ required: ['path'], not: { required: ['upload'] } }, { required: ['upload'], not: { required: ['path'] } }] as const
25
25
  export const mediaFileSchema = (maxBytes: number) => ({ type: 'object', additionalProperties: false,
26
26
  properties: { ...MEDIA_LOCATION_PROPERTIES, name: { type: 'string', minLength: 1, maxLength: 200 }, sha256: { type: 'string', pattern: '^[a-f\\d]{64}$' }, byteLength: { type: 'integer', minimum: 1, maximum: maxBytes } },
@@ -239,6 +239,7 @@ export interface PageDeleteAnswer { document: string, selected: string, retained
239
239
 
240
240
  /** @experimental One version-checked file in an authoring transaction; null creates a new file exclusively. */
241
241
  export interface SourceTransactionChange {
242
+ /** Workspace-relative, including the selected document directory for document-scoped changes. */
242
243
  path: string
243
244
  content: string
244
245
  base: string | null
package/src/node/index.ts CHANGED
@@ -28,8 +28,10 @@ export { validateProjectPlan, validateProjectApply } from './projects.ts'
28
28
  export { validateDocumentWorkspaceImageInspect, validateDocumentWorkspaceImageImport } from './document-image.ts'
29
29
  export { systemLocale } from './locale.ts'
30
30
  export { OperatorSpeechSettings, operatorSpeechSecrets, SpeechSettingsError, validateSpeechSettingsChange } from './operator-speech.ts'
31
- export { devStateFile, readServiceState, removeServiceState, serveStateDir } from './service-state.ts'
31
+ export { devStateFile, findWorkspaceServiceState, readServiceState, removeServiceState, serveStateDir } from './service-state.ts'
32
32
  export type { ServiceState } from './service-state.ts'
33
+ export { tryAcquireServiceHostLease } from './service-lease.ts'
34
+ export type { ServiceHostLease } from './service-lease.ts'
33
35
  export { validateWorkspaceReviewQuery, validateWorkspaceReviewChange } from './workspace-review.ts'
34
36
  export { validateSourceList, validateSourceRead, validateSourceEdit } from './workspace-source.ts'
35
37
  export { validateChangesQuery, validateWorkspaceChangesRequest } from './workspace-changes.ts'
@@ -0,0 +1,34 @@
1
+ import { mkdirSync, realpathSync } from 'node:fs'
2
+ import { createRequire } from 'node:module'
3
+ import { join } from 'node:path'
4
+ import { serveStateDir } from './service-state.ts'
5
+
6
+ const lockfile = createRequire(import.meta.url)('proper-lockfile') as {
7
+ lock(file: string, options: { realpath: boolean, retries: number, onCompromised(error: Error): void }): Promise<() => Promise<void>>
8
+ }
9
+
10
+ /** One workspace writer across Studio, serve and MCP processes. */
11
+ export interface ServiceHostLease {
12
+ readonly root: string
13
+ /** Losing the underlying lock requires closing the host before accepting more work. */
14
+ readonly signal: AbortSignal
15
+ release(): Promise<void>
16
+ }
17
+
18
+ /** One attempt; callers may wait for the existing host's published state instead of obtaining its lease. */
19
+ export async function tryAcquireServiceHostLease(root: string, env: NodeJS.ProcessEnv = process.env): Promise<ServiceHostLease | undefined> {
20
+ const canonical = realpathSync(root), directory = serveStateDir(canonical, env)
21
+ mkdirSync(directory, { recursive: true })
22
+ const controller = new AbortController()
23
+ let unlock: () => Promise<void>
24
+ try {
25
+ unlock = await lockfile.lock(join(directory, 'host'), { realpath: false, retries: 0, onCompromised: error => controller.abort(error) })
26
+ } catch (error) {
27
+ if ((error as NodeJS.ErrnoException).code === 'ELOCKED') return undefined
28
+ throw error
29
+ }
30
+ let releasing: Promise<void> | undefined
31
+ return { root: canonical, signal: controller.signal,
32
+ release: () => releasing ??= unlock().catch(error => { if (!controller.signal.aborted) throw error }),
33
+ }
34
+ }
@@ -1,7 +1,7 @@
1
1
  import { createHash } from 'node:crypto'
2
- import { readFileSync, rmSync } from 'node:fs'
2
+ import { readFileSync, realpathSync, rmSync } from 'node:fs'
3
3
  import { homedir } from 'node:os'
4
- import { join } from 'node:path'
4
+ import { dirname, join, resolve } from 'node:path'
5
5
  import { isRecord } from '../errors.ts'
6
6
 
7
7
  /** What a running Presmium server records for local clients: its address, its MCP endpoint and token, its process. */
@@ -10,6 +10,8 @@ export interface ServiceState {
10
10
  mcp: string
11
11
  token: string
12
12
  pid: number
13
+ /** Local launcher credential for Studio reuse; never include it in MCP tool results. */
14
+ launcherToken?: string
13
15
  }
14
16
 
15
17
  /** The state directory of the workspace service (`presmium serve`, and the one `presmium studio` starts) of `root`. */
@@ -37,12 +39,25 @@ export function readServiceState(file: string): ServiceState | undefined {
37
39
  try {
38
40
  const state: unknown = JSON.parse(readFileSync(file, 'utf8'))
39
41
  if (!isRecord(state) || typeof state.url !== 'string' || typeof state.mcp !== 'string' || typeof state.token !== 'string' || typeof state.pid !== 'number') return undefined
40
- return alive(state.pid) ? { url: state.url, mcp: state.mcp, token: state.token, pid: state.pid } : undefined
42
+ return alive(state.pid) ? { url: state.url, mcp: state.mcp, token: state.token, pid: state.pid, ...typeof state.launcherToken === 'string' && state.launcherToken ? { launcherToken: state.launcherToken } : {} } : undefined
41
43
  } catch {
42
44
  return undefined
43
45
  }
44
46
  }
45
47
 
48
+ /** Find the nearest existing workspace host and retain its root for a later host election. */
49
+ export function findWorkspaceServiceState(directory: string, env: NodeJS.ProcessEnv = process.env): { root: string, state: ServiceState } | undefined {
50
+ let root: string
51
+ try { root = realpathSync(resolve(directory)) } catch { return undefined }
52
+ for (;;) {
53
+ const state = readServiceState(join(serveStateDir(root, env), 'server.json'))
54
+ if (state) return { root, state }
55
+ const parent = dirname(root)
56
+ if (parent === root) return undefined
57
+ root = parent
58
+ }
59
+ }
60
+
46
61
  /** Removes `file` when it is still this process's: a server that stopped leaves no address behind. */
47
62
  export function removeServiceState(file: string, pid = process.pid): void {
48
63
  try {