Stello Agent Usage

const root = await agent.createSession({ label: 'Main' })
await agent.enterSession(root.id)

createSession → enterSession → turn / stream (× N) → leaveSession → archiveSession

const bootstrap = await agent.enterSession(sessionId)
// bootstrap.context — 组装好的上下文（MemoryEngine 视角）
// bootstrap.session — SessionMeta（id, label, status, turnCount 等）

const result = await agent.turn(sessionId, '帮我分析市场趋势')

// result.turn.finalContent      — 最终文本回复（tool loop 结束后）
// result.turn.toolRoundCount    — 经历了几轮 tool call 循环
// result.turn.toolCallsExecuted — 实际执行了多少个 tool
// result.turn.rawResponse       — 原始最终 LLM 响应

const streamResult = await agent.stream(sessionId, '帮我分析市场趋势')

for await (const chunk of streamResult) {
  process.stdout.write(chunk)
}

const result = await streamResult.result
console.log(result.turn.finalContent)

await agent.turn(sessionId, input, {
  maxToolRounds: 5,                       // 限制 tool call 循环轮数（默认无限）
  signal: abortController.signal,         // 支持取消（中断当前轮 LLM/tool 调用）
  onToolCall: (toolCall) => { /* ... */ },
  onToolResult: (result) => { /* ... */ },
})

await agent.leaveSession(sessionId)   // 触发 consolidation 调度（fire-and-forget）
await agent.archiveSession(sessionId) // 标记归档，之后不应再 turn()

const child = await agent.forkSession(sessionId, {
  // ── 必填 ──
  label: '市场分析-深度研究',

  // ── SessionConfig 字段（可选，参与合成链）──
  systemPrompt: '你是市场分析专家...',
  llm: specializedLlm,
  tools: customTools,
  skills: ['search', 'summarize'],
  consolidateFn: customConsolidateFn,
  compressFn: customCompressFn,

  // ── Fork 专属字段（可选）──
  prompt: '请深入分析半导体行业',   // fork 后立即发送的首条消息
  context: 'inherit',              // 'none'（默认）| 'inherit' | ForkContextFn
  topologyParentId: otherNodeId,   // 显式指定拓扑父节点（不传 = 当前 sessionId）
  profile: 'researcher',           // 引用预注册的 ForkProfile 名称
  profileVars: { region: '北美' }, // ForkProfile.systemPromptFn 的模板变量
})

// child: TopologyNode
// child.id              — 新 session 的 ID
// child.parentId        — 拓扑父节点 ID
// child.sourceSessionId — fork 时的上下文来源 session ID
// child.depth           — 拓扑深度（root = 0）
// child.label           — 显示名称

await agent.forkSession(sessionId, { label: '子任务', context: 'none' })    // 空白开始（默认）
await agent.forkSession(sessionId, { label: '深度研究', context: 'inherit' }) // 完整继承 L3
await agent.forkSession(sessionId, {
  label: '摘要子任务',
  context: async (parentMessages) => parentMessages.slice(-10),             // 自定义裁剪
})

const roots = await agent.listRoots()                   // TopologyNode[]
const forest = await agent.getTopology()                // SessionTreeNode[]（嵌套森林）
const node = await agent.getTopologyNode(sessionId)     // 单个 TopologyNode
const sessions = await agent.listSessions({ status: 'active' })  // SessionMeta[]

const view = await agent.getSessionMetadata(sessionId)
// view.memory   — string | null（持久；不进 send 上下文）
// view.insight  — string | null（一次性 inbox；下次 send 注入并 clear）

const digests = await agent.listSessionDigests({ status: 'active' })
// digests[i] = { id, label, status, memory, insight }

const messages = await agent.listMessages(sessionId, { limit: 100 })

await agent.putMemory(sessionId, '当前进展摘要...')       // 持久 memory（替换语义）
await agent.putInsight(sessionId, '需要重新评估方向...')  // 一次性 insight（send 消费后 clear）
await agent.clearInsight(sessionId)                       // 主动清除

await agent.attachSession(sessionId, connectionId)  // WS 连接建立
await agent.detachSession(sessionId, connectionId)  // WS 连接断开

agent.hasActiveEngine(sessionId)   // 是否有活跃 Engine
agent.getEngineRefCount(sessionId) // 当前引用计数

createStelloAgent({
  runtime: {
    resolver: myResolver,
    recyclePolicy: { idleTtlMs: 30_000 },
  },
})

// 运行时更新
agent.updateConfig({ runtime: { idleTtlMs: 60_000 } })

const root = await agent.createSession({ label: 'Main' })
await agent.enterSession(root.id)
await agent.turn(root.id, '你好')
await agent.turn(root.id, '继续上个话题')
await agent.leaveSession(root.id)

const root = await agent.createSession({ label: 'Main' })
await agent.enterSession(root.id)
await agent.turn(root.id, '我需要研究三个市场')

const children = await Promise.all([
  agent.forkSession(root.id, { label: '美国市场', systemPrompt: '你是美国市场专家' }),
  agent.forkSession(root.id, { label: '欧洲市场', systemPrompt: '你是欧洲市场专家' }),
  agent.forkSession(root.id, { label: '亚洲市场', systemPrompt: '你是亚洲市场专家' }),
])

await Promise.all(
  children.map(async (child) => {
    await agent.enterSession(child.id)
    await agent.turn(child.id, '分析半导体供应链')
    await agent.leaveSession(child.id)  // 触发 consolidation
  }),
)

// 独立的研究/写作两条线，互不影响
const research = await agent.createSession({ label: 'Research' })
const writing  = await agent.createSession({ label: 'Writing' })

await agent.enterSession(research.id)
await agent.turn(research.id, '调研材料 ...')

await agent.enterSession(writing.id)
await agent.turn(writing.id, '基于已有材料写一份 ...')

const all = await agent.listRoots()  // 两个 root 都会出现

async function reflect(agent: StelloAgent, llm: LLMAdapter): Promise<void> {
  const digests = await agent.listSessionDigests({ status: 'active' })
  // ... 应用层 prompt 把 digests 喂给 llm，解析出 per-target insight ...
  for (const [id, content] of Object.entries(insightsByTarget)) {
    await agent.putInsight(id, content)
  }
}

ws.on('connection', async (socket) => {
  const holderId = socket.id

  socket.on('enter', async ({ sessionId }) => {
    await agent.attachSession(sessionId, holderId)
    await agent.enterSession(sessionId)
  })

  socket.on('message', async ({ sessionId, input }) => {
    const stream = await agent.stream(sessionId, input)
    for await (const chunk of stream) {
      socket.send(JSON.stringify({ type: 'chunk', data: chunk }))
    }
    const result = await stream.result
    socket.send(JSON.stringify({ type: 'done', data: result }))
  })

  socket.on('close', async () => {
    for (const sessionId of socket.sessions) {
      await agent.detachSession(sessionId, holderId)
    }
  })
})