helloagents 3.0.37 → 3.0.39

package/scripts/runtime-scope.mjs

@@ -4,7 +4,15 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import { dirname, join, normalize, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
-import { resolveProjectSessionToken, resolveSessionToken } from './session-token.mjs'
+import {
+  PROJECT_CONVERSATION_PAYLOAD_KEYS,
+  PROJECT_SESSION_PAYLOAD_KEYS,
+  PROJECT_THREAD_PAYLOAD_KEYS,
+  resolveProjectSessionAliasToken,
+  resolveProjectSessionToken,
+  resolveSessionToken,
+  sanitizeSessionToken,
+} from './session-token.mjs'
 import { USER_RUNTIME_MAX_AGE_MS } from './runtime-ttl.mjs'
 import { cleanupUserRuntimeRoot, getUserRuntimeRoot } from './runtime-user-cleanup.mjs'
 import { FULL_CARRIER_PROFILE_MARKER } from './cli-utils.mjs'
@@ -14,6 +22,7 @@ export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 export const PROJECT_ARTIFACTS_DIR_NAME = 'artifacts'
 export const EVENTS_FILE_NAME = 'events.jsonl'
 export const ACTIVE_SESSION_FILE_NAME = 'active.json'
+export const PROJECT_RUNTIME_FILE_NAME = 'runtime.json'
 export const DEFAULT_STATE_SESSION_TOKEN = 'default'
 export const USER_RUNTIME_DIR_NAME = 'runtime'
 export { cleanupUserRuntimeRoot, getUserRuntimeRoot, USER_RUNTIME_MAX_AGE_MS }
@@ -329,10 +338,50 @@ function resolvePayloadSessionToken(payload = {}) {
   })
 }
 
+function readRawPayloadValue(payload = {}, key = '') {
+  if (!payload || typeof payload !== 'object') return ''
+  const value = payload[key]
+  if (typeof value === 'string') return value.trim()
+  if (typeof value === 'number') return String(value)
+  return ''
+}
+
+function readPayloadSessionIdentity(payload = {}) {
+  const groups = [
+    ['session', PROJECT_SESSION_PAYLOAD_KEYS],
+    ['conversation', PROJECT_CONVERSATION_PAYLOAD_KEYS],
+    ['thread', PROJECT_THREAD_PAYLOAD_KEYS],
+  ]
+
+  for (const [kind, keys] of groups) {
+    for (const key of keys) {
+      const value = sanitizeRuntimeSegment(sanitizeSessionToken(readRawPayloadValue(payload, key)), '')
+      if (value) return { kind, token: value }
+    }
+  }
+
+  return { kind: '', token: '' }
+}
+
 function resolveEnvSessionToken(env = process.env) {
   return resolveProjectSessionToken({ payload: {}, env })
 }
 
+function resolveEnvSessionAliasToken(env = process.env) {
+  return resolveProjectSessionAliasToken({ env })
+}
+
+function resolveProjectSessionHostHint({ env = process.env, ppid = process.ppid } = {}) {
+  const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
+  if (envToken) return `host:${envToken}`
+
+  const envAliasToken = sanitizeRuntimeSegment(resolveEnvSessionAliasToken(env), '')
+  if (envAliasToken) return `alias:${envAliasToken}`
+
+  const parentToken = sanitizeRuntimeSegment(String(ppid || '').trim(), '')
+  return parentToken ? `ppid:${parentToken}` : ''
+}
+
 function resolveTransientSessionToken({ payload = {}, env = process.env, ppid = process.ppid } = {}) {
   return resolveSessionToken({
     payload,
@@ -342,11 +391,40 @@ function resolveTransientSessionToken({ payload = {}, env = process.env, ppid =
   })
 }
 
+function buildScopedSessionToken(kind = '', raw = '') {
+  const normalizedKind = sanitizeRuntimeSegment(kind, 'session')
+  const value = sanitizeRuntimeSegment(String(raw || '').trim(), '')
+  if (!value) return ''
+  return `${normalizedKind}-${value}`
+}
+
+function buildSessionAliasKeys({ payload = {}, env = process.env } = {}) {
+  const keys = []
+  const payloadIdentity = readPayloadSessionIdentity(payload)
+  if (payloadIdentity.token) {
+    keys.push(`${payloadIdentity.kind}:${payloadIdentity.token}`)
+  }
+
+  const envSession = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
+  if (envSession && !payloadIdentity.token) keys.push(`host:${envSession}`)
+
+  const payloadAlias = sanitizeRuntimeSegment(sanitizeSessionToken(payload?._helloagentsSessionAlias), '')
+  if (payloadAlias) keys.push(`alias:${payloadAlias}`)
+
+  const envAlias = sanitizeRuntimeSegment(resolveEnvSessionAliasToken(env), '')
+  if (envAlias && envSession && envAlias === envSession) {
+    return [...new Set(keys.filter(Boolean))]
+  }
+  if (envAlias) keys.push(`alias:${envAlias}`)
+
+  return [...new Set(keys.filter(Boolean))]
+}
+
 function getActiveSessionPath(activationDir) {
   return join(activationDir, PROJECT_SESSIONS_DIR_NAME, ACTIVE_SESSION_FILE_NAME)
 }
 
-function resolveActiveSessionToken({ activationDir, projectRoot, workspace, now = Date.now() } = {}) {
+function readActiveProjectSession({ activationDir, projectRoot, workspace, now = Date.now() } = {}) {
   const active = readJsonFile(getActiveSessionPath(activationDir), null)
   if (!active || typeof active !== 'object') return ''
   if (active.cwd && !samePath(active.cwd, projectRoot)) return ''
@@ -357,42 +435,77 @@ function resolveActiveSessionToken({ activationDir, projectRoot, workspace, now
   const updatedAt = Date.parse(active.updatedAt || '')
   if (!Number.isFinite(updatedAt) || now - updatedAt > USER_RUNTIME_MAX_AGE_MS) return ''
 
-  return sanitizeRuntimeSegment(active.session, '')
+  return active
 }
 
 function resolveActiveAliasSession({ activationDir, projectRoot, workspace, alias, now = Date.now() } = {}) {
   if (!alias) return ''
-  const active = readJsonFile(getActiveSessionPath(activationDir), null)
+  const active = readActiveProjectSession({
+    activationDir,
+    projectRoot,
+    workspace,
+    now,
+  })
   if (!active || typeof active !== 'object') return ''
-  if (active.cwd && !samePath(active.cwd, projectRoot)) return ''
 
-  const activeWorkspace = sanitizeRuntimeSegment(active.workspace || active.branch || '', '')
-  if (activeWorkspace && activeWorkspace !== workspace) return ''
+  const aliases = active.aliases && typeof active.aliases === 'object' ? active.aliases : {}
+  const mapped = sanitizeRuntimeSegment(aliases[alias], '')
+  if (mapped) return mapped
+  if (
+    Object.prototype.hasOwnProperty.call(aliases, alias)
+    && resolveActiveSessionToken(active, join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace)) === DEFAULT_STATE_SESSION_TOKEN
+  ) {
+    return DEFAULT_STATE_SESSION_TOKEN
+  }
+  return ''
+}
 
-  const updatedAt = Date.parse(active.updatedAt || '')
-  if (!Number.isFinite(updatedAt) || now - updatedAt > USER_RUNTIME_MAX_AGE_MS) return ''
+function choosePreferredProjectSession(activeSession = '', candidates = []) {
+  for (const candidate of candidates) {
+    if (!candidate) continue
+    if (activeSession && candidate === activeSession) return candidate
+  }
+  return candidates.find(Boolean) || ''
+}
 
-  const aliases = active.aliases && typeof active.aliases === 'object' ? active.aliases : {}
-  return sanitizeRuntimeSegment(aliases[alias], '')
+function resolveActiveSessionToken(active = {}, workspaceDir = '') {
+  const session = sanitizeRuntimeSegment(active?.session || '', '')
+  if (session) return session
+
+  const defaultStatePath = workspaceDir
+    ? join(workspaceDir, DEFAULT_STATE_SESSION_TOKEN, 'STATE.md')
+    : ''
+  return defaultStatePath && existsSync(defaultStatePath)
+    ? DEFAULT_STATE_SESSION_TOKEN
+    : ''
 }
 
-export function writeActiveProjectSession(scope, { host = '', source = '', env = process.env } = {}) {
-  if (!scope?.active || !scope.activationDir || !scope.session) return ''
+export function writeActiveProjectSession(scope, { host = '', source = '', payload = {}, env = process.env, ppid = process.ppid } = {}) {
+  if (!scope?.active || !scope.activationDir || !scope.workspace) return ''
 
   const activePath = getActiveSessionPath(scope.activationDir)
   const current = readJsonFile(activePath, null) || {}
-  const aliases = current.aliases && typeof current.aliases === 'object' ? current.aliases : {}
-  const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
-  if (envToken && envToken !== scope.session) aliases[envToken] = scope.session
-
+  const aliases = current.aliases && typeof current.aliases === 'object' ? { ...current.aliases } : {}
+  const session = scope.session || DEFAULT_STATE_SESSION_TOKEN
+  const sessionMode = scope.session
+    ? scope.sessionMode
+    : 'default'
+  const hostHint = resolveProjectSessionHostHint({ env, ppid }) || current.hostHint || ''
+  const aliasKeys = buildSessionAliasKeys({ payload, env })
+  for (const aliasKey of aliasKeys) {
+    aliases[aliasKey] = session
+    const [, aliasValue = ''] = String(aliasKey).split(':')
+    if (aliasValue) aliases[aliasValue] = session
+  }
   writeJsonFileAtomic(activePath, {
     version: 1,
     cwd: scope.cwd,
     workspace: scope.workspace || scope.branch,
-    session: scope.session,
-    sessionMode: scope.sessionMode,
+    session,
+    sessionMode,
     host,
     source,
+    ...(hostHint ? { hostHint } : {}),
     aliases,
     ...(current.cleanupCheckedAt ? { cleanupCheckedAt: current.cleanupCheckedAt } : {}),
     updatedAt: new Date().toISOString(),
@@ -400,60 +513,121 @@ export function writeActiveProjectSession(scope, { host = '', source = '', env =
   return activePath
 }
 
-function chooseProjectSession({ payload, env, activationDir, projectRoot, workspace }) {
-  const payloadToken = sanitizeRuntimeSegment(resolvePayloadSessionToken(payload), '')
-  if (payloadToken) return { session: payloadToken, sessionMode: 'host-session' }
-
-  const payloadAlias = sanitizeRuntimeSegment(payload?._helloagentsSessionAlias, '')
-  const payloadAliasToken = resolveActiveAliasSession({
+function chooseProjectSession({ payload, env, ppid, activationDir, projectRoot, workspace }) {
+  const workspaceDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace)
+  const active = readActiveProjectSession({
     activationDir,
     projectRoot,
     workspace,
-    alias: payloadAlias,
   })
-  if (payloadAliasToken) return { session: payloadAliasToken, sessionMode: 'active-session' }
+  const activeSession = resolveActiveSessionToken(active, workspaceDir)
+  const payloadIdentity = readPayloadSessionIdentity(payload)
+  const payloadToken = payloadIdentity.token
+  const payloadAlias = sanitizeRuntimeSegment(sanitizeSessionToken(payload?._helloagentsSessionAlias), '')
+  const payloadAliases = [
+    payloadIdentity.token ? `${payloadIdentity.kind}:${payloadIdentity.token}` : '',
+    payloadAlias ? `alias:${payloadAlias}` : '',
+  ].filter(Boolean)
+  const payloadMappedSession = choosePreferredProjectSession(
+    activeSession,
+    payloadAliases.map((alias) => resolveActiveAliasSession({
+      activationDir,
+      projectRoot,
+      workspace,
+      alias,
+    })),
+  )
+  if (payloadMappedSession) {
+    return { session: payloadMappedSession, sessionMode: 'active-session' }
+  }
 
   const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
-  const aliasToken = resolveActiveAliasSession({
-    activationDir,
-    projectRoot,
-    workspace,
-    alias: envToken,
-  })
-  if (aliasToken) return { session: aliasToken, sessionMode: 'active-session' }
+  const envAliasToken = sanitizeRuntimeSegment(resolveEnvSessionAliasToken(env), '')
+  const envMappedSession = choosePreferredProjectSession(
+    activeSession,
+    [
+      envToken ? resolveActiveAliasSession({
+        activationDir,
+        projectRoot,
+        workspace,
+        alias: `host:${envToken}`,
+      }) : '',
+      envAliasToken ? resolveActiveAliasSession({
+        activationDir,
+        projectRoot,
+        workspace,
+        alias: `alias:${envAliasToken}`,
+      }) : '',
+    ],
+  )
+  if (envMappedSession) return { session: envMappedSession, sessionMode: 'active-session' }
+
+  if (
+    activeSession === DEFAULT_STATE_SESSION_TOKEN
+    && active?.hostHint
+    && active.hostHint === resolveProjectSessionHostHint({ env, ppid })
+    && (payloadToken || payloadAlias || envToken || envAliasToken)
+  ) {
+    return {
+      session: activeSession,
+      sessionMode: 'active-session',
+    }
+  }
 
-  if (envToken) return { session: envToken, sessionMode: 'host-session' }
+  if (payloadToken) {
+    return {
+      session: buildScopedSessionToken('host', payloadToken),
+      sessionMode: 'host-session',
+    }
+  }
+  if (payloadAlias) {
+    return {
+      session: buildScopedSessionToken('alias', payloadAlias),
+      sessionMode: 'alias-session',
+    }
+  }
 
-  const activeToken = resolveActiveSessionToken({ activationDir, projectRoot, workspace })
-  if (activeToken) return { session: activeToken, sessionMode: 'active-session' }
+  if (envToken) {
+    return {
+      session: buildScopedSessionToken('host', envToken),
+      sessionMode: 'host-session',
+    }
+  }
 
-  return { session: DEFAULT_STATE_SESSION_TOKEN, sessionMode: 'default' }
-}
+  if (envAliasToken) {
+    return {
+      session: buildScopedSessionToken('alias', envAliasToken),
+      sessionMode: 'alias-session',
+    }
+  }
 
-function removeLegacyProjectArtifacts(activationDir) {
-  if (!activationDir) return
-  const artifactsDir = join(activationDir, PROJECT_ARTIFACTS_DIR_NAME)
-  if (!existsSync(artifactsDir)) return
-  try {
-    rmSync(artifactsDir, { recursive: true, force: true })
-  } catch {}
+  const source = String(payload?.source || '').trim().toLowerCase()
+  if ((source === 'resume' || source === 'compact') && activeSession) {
+    return {
+      session: activeSession,
+      sessionMode: 'active-session',
+    }
+  }
+
+  return { session: '', sessionMode: 'unidentified' }
 }
 
 export function getProjectSessionScope(cwd, options = {}) {
   const normalizedCwd = normalizePath(cwd || process.cwd())
   const projectRoot = getProjectRoot(normalizedCwd)
-  const { payload = {}, env = process.env } = normalizeRuntimeOptions(options)
+  const { payload = {}, env = process.env, ppid = process.ppid } = normalizeRuntimeOptions(options)
   const activationDir = getProjectActivationDir(projectRoot)
-  removeLegacyProjectArtifacts(activationDir)
   const workspace = resolveWorkspaceName(projectRoot)
   const { session, sessionMode } = chooseProjectSession({
     payload,
     env,
+    ppid,
     activationDir,
     projectRoot,
     workspace,
   })
-  const sessionDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace, session)
+  const workspaceDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace)
+  const sessionDir = session ? join(workspaceDir, session) : join(workspaceDir, DEFAULT_STATE_SESSION_TOKEN)
 
   return {
     cwd: projectRoot,
@@ -464,10 +638,12 @@ export function getProjectSessionScope(cwd, options = {}) {
     sessionMode,
     activationDir,
     sessionDir,
+    workspaceDir,
     statePath: join(sessionDir, 'STATE.md'),
     eventsPath: join(sessionDir, EVENTS_FILE_NAME),
     artifactsDir: join(sessionDir, PROJECT_ARTIFACTS_DIR_NAME),
-    key: `${projectRoot}::${workspace}::${session}`,
+    runtimePath: join(sessionDir, PROJECT_RUNTIME_FILE_NAME),
+    key: `${projectRoot}::${workspace}::${session || DEFAULT_STATE_SESSION_TOKEN}`,
   }
 }
 
@@ -497,6 +673,7 @@ function buildTransientRuntimeDir(cwd, options = {}) {
     statePath: join(getUserRuntimeRoot(), hash, 'STATE.md'),
     eventsPath: join(getUserRuntimeRoot(), hash, EVENTS_FILE_NAME),
     artifactsDir: join(getUserRuntimeRoot(), hash, PROJECT_ARTIFACTS_DIR_NAME),
+    runtimePath: join(getUserRuntimeRoot(), hash, PROJECT_RUNTIME_FILE_NAME),
     key: `${normalizedCwd}::transient::${token}`,
   }
 }

package/scripts/session-capsule.mjs

@@ -31,6 +31,18 @@ function buildEmptyCapsule(scope) {
   }
 }
 
+function readRuntimeDocument(filePath) {
+  const payload = readJsonFile(filePath, null)
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null
+  }
+  return payload
+}
+
+function writeRuntimeDocument(filePath, payload) {
+  writeJsonFileAtomic(filePath, payload)
+}
+
 function normalizeOptions(options = {}) {
   if (!options || typeof options !== 'object') return {}
   if (options.payload && typeof options.payload === 'object') return options
@@ -41,7 +53,7 @@ function normalizeOptions(options = {}) {
 }
 
 function getEventSessionAlias(eventPayload = {}) {
-  return eventPayload.sessionId || eventPayload.session_id || eventPayload['session-id'] || ''
+  return eventPayload.sessionAlias || eventPayload.session_alias || eventPayload['session-alias'] || eventPayload._helloagentsSessionAlias || ''
 }
 
 function getScope(cwd, options = {}) {
@@ -84,7 +96,7 @@ function shouldMaterializeSessionState(options = {}) {
 }
 
 export function getSessionCapsulePath(cwd = process.cwd(), options = {}) {
-  return getScope(cwd, options).statePath
+  return getScope(cwd, options).runtimePath
 }
 
 export function getSessionEventsPath(cwd = process.cwd(), options = {}) {
@@ -102,15 +114,14 @@ export function getSessionArtifactPath(cwd, fileName, options = {}) {
 export function getSessionArtifactRelativePath(cwd, fileName, options = {}) {
   const scope = getScope(cwd, options)
   if (scope.scope === 'project-session') {
-    return `.helloagents/sessions/${scope.workspace || scope.branch}/${scope.session}/artifacts/${fileName}`
+    return `.helloagents/sessions/${scope.workspace || scope.branch}/${scope.session || 'default'}/artifacts/${fileName}`
   }
   return `~/.helloagents/runtime/${basename(scope.sessionDir)}/artifacts/${fileName}`
 }
 
 export function readSessionCapsule(cwd = process.cwd(), options = {}) {
   const scope = getScope(cwd, options)
-  const { metadata } = readStateDocument(scope.statePath)
-  const capsule = metadata && typeof metadata === 'object' ? metadata : null
+  const capsule = readRuntimeDocument(scope.runtimePath)
   if (!capsule || Array.isArray(capsule)) return buildEmptyCapsule(scope)
   return {
     ...buildEmptyCapsule(scope),
@@ -165,12 +176,16 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
   }
-  writeStateDocument(scope.statePath, {
-    metadata: nextCapsule,
-    body: currentDocument.body,
-  })
+  writeRuntimeDocument(scope.runtimePath, nextCapsule)
+  if (hasBody) {
+    writeStateDocument(scope.statePath, {
+      body: currentDocument.body,
+    })
+  }
   writeActiveProjectSession(scope, {
+    payload: normalizedOptions.payload,
     env: normalizedOptions.env,
+    ppid: normalizedOptions.ppid,
   })
   return nextCapsule
 }
@@ -197,8 +212,8 @@ export function writeCapsuleSection(cwd, section, value, options = {}) {
 }
 
 export function clearCapsuleSection(cwd, section, options = {}) {
-  const statePath = getSessionCapsulePath(cwd, options)
-  if (!existsSync(statePath)) return false
+  const runtimePath = getSessionCapsulePath(cwd, options)
+  if (!existsSync(runtimePath)) return false
 
   const capsule = readSessionCapsule(cwd, options)
   if (!Object.prototype.hasOwnProperty.call(capsule, section)) return false
@@ -229,7 +244,9 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
   writeActiveProjectSession(scope, {
     host: eventPayload.host || '',
     source: eventPayload.source || eventName,
+    payload: scopedOptions.payload,
     env: scopedOptions.env,
+    ppid: scopedOptions.ppid,
   })
   if (!shouldRecordSessionEvents(scopedOptions)) return ''
 
@@ -289,7 +306,11 @@ export function clearSessionArtifact(cwd, fileName, options = {}) {
 }
 
 export function removeSessionCapsule(cwd, options = {}) {
-  removeRuntimeFile(getSessionCapsulePath(cwd, options))
+  const scope = getScope(cwd, options)
+  removeRuntimeFile(scope.runtimePath)
+  if (scope.scope !== 'project-session') {
+    removeRuntimeFile(scope.statePath)
+  }
 }
 
 function shouldRecordSessionEvents(options = {}) {

package/scripts/session-token.mjs

@@ -17,19 +17,31 @@ const PAYLOAD_SESSION_KEYS = [
   'tab',
 ]
 
-const PROJECT_PAYLOAD_SESSION_KEYS = [
+const PROJECT_SESSION_PAYLOAD_KEYS = [
   'sessionId',
   'session_id',
   'session',
+]
+
+const PROJECT_CONVERSATION_PAYLOAD_KEYS = [
   'conversationId',
   'conversation_id',
   'conversation',
+]
+
+const PROJECT_THREAD_PAYLOAD_KEYS = [
   'threadId',
   'thread_id',
   'thread-id',
   'thread',
 ]
 
+const PROJECT_PAYLOAD_SESSION_KEYS = [
+  ...PROJECT_SESSION_PAYLOAD_KEYS,
+  ...PROJECT_CONVERSATION_PAYLOAD_KEYS,
+  ...PROJECT_THREAD_PAYLOAD_KEYS,
+]
+
 const ENV_SESSION_KEYS = [
   'HELLOAGENTS_NOTIFY_SESSION_ID',
   'WT_SESSION',
@@ -45,6 +57,16 @@ const PROJECT_ENV_SESSION_KEYS = [
   'HELLOAGENTS_NOTIFY_SESSION_ID',
 ]
 
+const PROJECT_ALIAS_ENV_SESSION_KEYS = [
+  'WT_SESSION',
+  'TERM_SESSION_ID',
+  'KITTY_WINDOW_ID',
+  'ALACRITTY_WINDOW_ID',
+  'WINDOWID',
+  'WEZTERM_PANE',
+  'TAB_ID',
+]
+
 function readStringCandidate(input, key) {
   if (!input || typeof input !== 'object') return ''
   const value = input[key]
@@ -99,9 +121,19 @@ export function resolveProjectSessionToken({
   return resolveTokenFromKeys(env, PROJECT_ENV_SESSION_KEYS)
 }
 
+export function resolveProjectSessionAliasToken({
+  env = process.env,
+} = {}) {
+  return resolveTokenFromKeys(env, PROJECT_ALIAS_ENV_SESSION_KEYS)
+}
+
 export {
   ENV_SESSION_KEYS,
   PAYLOAD_SESSION_KEYS,
+  PROJECT_ALIAS_ENV_SESSION_KEYS,
+  PROJECT_CONVERSATION_PAYLOAD_KEYS,
   PROJECT_ENV_SESSION_KEYS,
   PROJECT_PAYLOAD_SESSION_KEYS,
+  PROJECT_SESSION_PAYLOAD_KEYS,
+  PROJECT_THREAD_PAYLOAD_KEYS,
 }

package/scripts/state-document.mjs

@@ -1,77 +1,32 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 
-const STATE_META_BEGIN = '<!-- HELLOAGENTS_STATE_META'
-const STATE_META_END = 'HELLOAGENTS_STATE_META -->'
+export const AUTO_CREATED_STATE_MARKER = '由运行时自动创建；后续按实际任务重写'
 
 function normalizeText(content = '') {
   return String(content || '').replace(/^\uFEFF/, '')
 }
 
-function splitLines(content = '') {
-  return normalizeText(content).replace(/\r\n/g, '\n').split('\n')
-}
-
-export function parseStateDocument(content = '') {
-  const lines = splitLines(content)
-  if (lines[0]?.trim() !== STATE_META_BEGIN) {
-    return {
-      hasMetadata: false,
-      metadata: null,
-      body: normalizeText(content),
-    }
-  }
-
-  const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === STATE_META_END)
-  if (endIndex < 0) {
-    return {
-      hasMetadata: false,
-      metadata: null,
-      body: normalizeText(content),
-    }
-  }
-
-  const metadataText = lines.slice(1, endIndex).join('\n').trim()
-  const body = lines.slice(endIndex + 1).join('\n').replace(/^\n+/, '')
-  try {
-    return {
-      hasMetadata: true,
-      metadata: JSON.parse(metadataText),
-      body,
-    }
-  } catch {
-    return {
-      hasMetadata: false,
-      metadata: null,
-      body,
-    }
-  }
-}
-
 export function readStateDocument(filePath) {
   if (!filePath || !existsSync(filePath)) {
-    return {
-      hasMetadata: false,
-      metadata: null,
-      body: '',
-    }
+    return { body: '' }
   }
 
-  return parseStateDocument(readFileSync(filePath, 'utf-8'))
+  return {
+    body: normalizeText(readFileSync(filePath, 'utf-8')),
+  }
 }
 
-export function composeStateDocument({ metadata = {}, body = '' } = {}) {
+export function composeStateDocument({ body = '' } = {}) {
   const normalizedBody = normalizeText(body).replace(/^\n+/, '')
-  return [
-    STATE_META_BEGIN,
-    JSON.stringify(metadata, null, 2),
-    STATE_META_END,
-    '',
-    normalizedBody,
-  ].join('\n').replace(/\n+$/, '\n')
+  return normalizedBody ? `${normalizedBody.replace(/\n+$/, '')}\n` : ''
+}
+
+export function looksLikeAutoCreatedState(body = '') {
+  return normalizeText(body).includes(AUTO_CREATED_STATE_MARKER)
 }
 
-export function writeStateDocument(filePath, { metadata = {}, body = '' } = {}) {
+export function writeStateDocument(filePath, { body = '' } = {}) {
   mkdirSync(dirname(filePath), { recursive: true })
-  writeFileSync(filePath, composeStateDocument({ metadata, body }), 'utf-8')
+  writeFileSync(filePath, composeStateDocument({ body }), 'utf-8')
 }

package/scripts/turn-state.mjs

@@ -5,7 +5,6 @@ import { fileURLToPath } from 'node:url'
 import {
   appendSessionEvent,
   clearCapsuleSection,
-  getSessionCapsulePath,
   getRuntimeScope,
   readCapsuleSection,
   writeCapsuleSection,
@@ -108,7 +107,7 @@ export function readTurnState(cwd = process.cwd(), { now = Date.now(), ...option
   return {
     cwd: normalizePath(entry.cwd),
     key: entry.key || '',
-    path: getSessionCapsulePath(cwd, options),
+    path: getRuntimeScope(cwd, options).statePath,
     updatedAt: entry.updatedAt,
     ...normalized,
   }
@@ -288,7 +287,7 @@ function main() {
     const payload = writeTurnState(cwd, input)
     process.stdout.write(JSON.stringify({
       suppressOutput: true,
-      path: getSessionCapsulePath(cwd, input),
+      path: getRuntimeScope(cwd, input).statePath,
       payload,
     }))
     return