> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 让空闲 Session 休眠并自动唤醒

Session 可以在两次 Run 之间进入空闲策略，并在下一次提交时自动准备执行环境。应用继续使用同一个 Session ID，无需在每次 submit 之前先调用 resume。

需要支持对应生命周期的 Sandbox / Harness 组合。单轮成功不证明休眠后可继续，查看[Harness serverless 验证记录](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-19-harness-serverless-matrix.json)中的具体组合与 SDK。

## 配置空闲时间

创建直接 Session 时设置策略：

```python theme={null}
session = client.create_session(
    harness={'id': 'pi', 'version': '1.5.2'},
    sandbox_connection_id=sandbox_connection_id,
    model_connection_id=model_connection_id,
    resources={'idle_timeout_seconds': 60},
)
```

```typescript theme={null}
const session = await client.createSession({
  harness: { id: 'pi', version: '1.5.2' },
  sandbox_connection_id: sandboxConnectionId,
  model_connection_id: modelConnectionId,
  resources: { idle_timeout_seconds: 60 },
});
```

当前默认 60 秒、最小 15 秒，控制平面每五秒检查资格，因此不要把超时值当精确的暂停完成时间。Provider 自动 standby 有自己的时序，可能早于平台计时器。

等待工具授权或审批的 Run 仍是活动 Run，不能当成两轮之间的空闲。应用应向用户提供处理入口，而不是靠暂停解决等待。

## 通过 SDK 显式暂停与恢复

使用已初始化的 owner 客户端、已保存的 Session ID，以及支持目标生命周期操作的 Sandbox。以下函数是彼此独立的运维动作，定义函数不会请求接口；不要把它们放入暂停/恢复循环。TypeScript 示例使用 SDK 初始化时导入的 `Hexagon`。

```python theme={null}
def request_session_pause(client, session_id, scope):
    if scope not in ('session', 'sandbox'):
        raise ValueError('Choose session or sandbox scope explicitly')
    transition = client.pause(session_id, scope=scope)
    observed = client.session(session_id)
    return {'transition': transition, 'observed_session': observed}


def request_session_resume(client, session_id):
    transition = client.resume(session_id)
    observed = client.session(session_id)
    return {'transition': transition, 'observed_session': observed}
```

```typescript theme={null}
async function requestSessionPause(
  client: Hexagon, sessionId: string, scope: 'session' | 'sandbox',
) {
  if (scope !== 'session' && scope !== 'sandbox') {
    throw new Error('Choose session or sandbox scope explicitly');
  }
  const transition = await client.pause(sessionId, scope);
  const observed = await client.session(sessionId);
  return { transition, observed_session: observed };
}

async function requestSessionResume(client: Hexagon, sessionId: string) {
  const transition = await client.resume(sessionId);
  const observed = await client.session(sessionId);
  return { transition, observed_session: observed };
}
```

逻辑暂停选择 `session`；只有支持且确实需要原生计算暂停时才选择 `sandbox`。示例要求明确传 scope，避免把逻辑暂停默认为停止计费。能力、归属和活动 Run 检查仍以服务端为准。暂停不能解决等待授权或审批的 Run，应先通过对应流程完成工作，或明确取消。

每个函数返回转换响应和之后一次 Session GET 的结果。它们是独立观察，中间可能发生其他操作。重复请求可能只返回 state/scope，不能把缺少 `compute_paused` 或 `provider_managed_standby` 解读为最新 Provider 检查。函数不等待 Runtime 就绪，也不证明进程或内存保留；继续执行下文的任务与持久化检查。

HTTP 和网络错误向调用方传播。`session_transition_pending`、`session_pause_scope_conflict`、`sandbox_pause_unsupported` 需要调查状态、scope 或能力，不应快速重试或发起相反转换。若变更成功而后续 GET 失败，函数仍会抛错，但转换可能已发生；进一步操作前读取原 Session 和资源操作。已关闭 Session 无法恢复。正常下一轮工作可以直接向同一 paused Session 提交来触发唤醒，不要求先显式 resume。完整响应和错误见 [Session 生命周期契约](https://docs.hexagon.autos/zh-CN/reference/sessions.md)。

## 保留边界

| 策略 | 当前示例 Provider | 应依赖的边界 |
| - | - | - |
| 内存暂停 | E2B、Freestyle、Instabox | 当前策略保留内存和文件；仍需具体组合验收 |
| 磁盘保留并重启 Runtime | Vercel、Upstash、Boat、Agent37 | 使用受管理工作区，避免依赖临时目录或进程状态 |
| 快照后重建资源 | Modal | Session ID 保持，底层资源 ID 会变化 |
| 暂停并允许冷启动回退 | Fly Machines | 文件系统是可靠边界，不保证内存始终保留 |
| Provider 管理 standby | Blaxel、Sprites | 不能从平台等待时间推断实际计费状态 |

Agent37 的 `/tmp` 会清空。任意临时文件、socket、后台服务和内存对象都不是跨 Provider 的统一持久化承诺。模型和 Tool 的原始密钥不会作为普通 guest 配置加入快照；普通用户 env 仍遵守其可读性边界。

## 读取实际策略与当前状态

通过 `session_initialization` / `sessionInitialization` 查看固定的生命周期策略，通过 `session` 查看当前 `state`、`pause_scope` 和 Sandbox 关联。实际 idle 间隔会受 `timeout_seconds - 10` 上限约束，配置的 idle 数值不能单独表达完整期限行为。例如 idle 60、timeout 60 的实际 idle 间隔是 50 秒；轮询和 Provider 操作还可能增加延迟。

Session 可能只是逻辑暂停，并不证明云计算停止计费。应核对 `pause_scope` 与 Provider 策略。`resuming` 同样不证明 Runtime 已就绪；保留提交的 Run ID，继续观察初始化和执行，不要因为唤醒较慢就提交第二个任务。

休眠唤醒验收应记录第一轮 Run、文件 hash、对话事实、实际 Session 状态及 pause scope、第二轮 Run，以及分别完成的文件与对话检查。不要用固定等待代替实际状态观察。策略涉及资源重建时，同时保留新旧云资源 ID，最后确认清理。

## 下一轮与验证

第一轮在受管理工作区写入文件，同时提供一个可核对的对话信息。观察空闲生命周期后，用新的幂等键向同一 Session submit 第二轮，要求读取文件并复述前轮信息。分别核对文件和对话恢复，不以一个成功推断另一个。

若资源 ID 变化，核对 Session 记录中的新绑定，不使用缓存的供应商资源 ID 操作旧机器。活动 invocation 结果未知时，唤醒机制不能作为重新执行原任务的入口。

计划内休眠与终态关闭不同。close 删除云资源并结束 Session；睡眠仍可能有存储费用，到期和账户限制仍生效。完成任务后显式关闭并确认清理。

依据：[Serverless 策略与验证范围](https://github.com/NexusFox88/docs/blob/main/resources/docs/serverless-sessions.md)。工作中断时，按[故障恢复](https://docs.hexagon.autos/zh-CN/build/recovery.md)处理。

## 观察实际空闲转换，而非浏览器是否闲置

空闲选择器要求 Session 打开、已有 Sandbox 且支持对应生命周期能力，并且没有非终态 Run。计时依据为 Session `updated_at` 和最新 Run `updated_at` 中较晚者。关闭浏览器或收到最后一个 token，不会启动独立的浏览器空闲时钟。授权或审批等待仍是非终态 Run；Session 或资源到期属于另一项限制，仍可能结束任务。

例如，有效空闲间隔为 60 秒时，要在记录的活动边界加上该间隔后才满足条件，之后还有五秒扫描与远端操作延迟。Session 继续显示 open 时，应检查策略、活动 Run 和生命周期诊断，不要反复主动发起暂停或唤醒。

## 分别记录保留结果

| 性质 | 需要的证据 | 不能据此推断什么 |
| - | - | - |
| 文件内容 | 唤醒前后独立读取工作区字节与 hash | 仅有模型读回不证明字节完整性。 |
| 对话 | 支持时核对原生对话标识，并验证可核对的前轮信息 | 文件保留不单独证明对话连续性。 |
| 进程或内存 | 明确的前后进程与内存状态探针 | 策略名称或原生对话 ID 不证明任意进程存活。 |
| 计算资源身份 | 原资源与当前资源 ID，以及恢复或 checkpoint 操作 | Session ID 不变不代表同一 VM。 |
| 清理 | 计算资源及所属 checkpoint/image 的确认处置 | 追问成功或 paused 状态不证明删除。 |

[11 月 19 日 serverless 记录](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-19-harness-serverless-ui.md)说明真实空闲唤醒尝试、独立文件与原生会话检查以及失败情况。对应矩阵逐 SDK 记录结果，但没有对任意进程或内存保留给出统一断言。练习中未测量的性质应记录为未验证，不追加到“通过”结论。后续 [E2B OCI 准备记录](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-19-e2b-oci-preparation.md)在矩阵快照后补充限定证据，不应把旧 unsupported 单元格改写成当时已执行的测试。

依据：[空闲条件](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts)、[worker 恢复](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/worker.ts)。下一步：[Serverless 生命周期](https://docs.hexagon.autos/zh-CN/concepts/serverless-lifecycle.md)、[Sandbox 能力](https://docs.hexagon.autos/zh-CN/integrations/sandboxes.md)、[容量与成本](https://docs.hexagon.autos/zh-CN/operate/capacity-and-cost.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.