@kanyun-ai-infra/agenthub 1.6.0 → 1.7.0

package/dist/index.cjs

@@ -4935,9 +4935,18 @@ var DeliveryResultArtifactItemSchema = import_zod42.z.object({
   /** Artifact category. Workers MAY add new kinds; storage is opaque. */
   kind: import_zod42.z.enum(["diff", "log", "general"]),
   /**
-   * Logical path inside the sandbox workspace (used as the idempotency
-   * key together with `runId`). Two writes with the same `(runId, path)`
-   * pair collapse to a single row via `ON CONFLICT DO NOTHING`.
+   * Logical path inside the sandbox workspace, and the idempotency key of
+   * the artifact row: `(runId, path)` on the run plane, `(sessionId, path)`
+   * on the session plane. Two writes with the same pair collapse to a single
+   * row — the run plane keeps the first (`ON CONFLICT DO NOTHING`), the
+   * session plane keeps the newest bytes and moves `turn_id` to the newest
+   * ATTRIBUTED writer (`ON CONFLICT DO UPDATE`, T-INV-5).
+   *
+   * Two items with the SAME path inside one request body are legal wire but
+   * a single artifact: the session plane de-duplicates them before the
+   * insert, last one wins, and `artifactsInserted` counts the de-duplicated
+   * items. Not a 400 — see `turnId` below on why an artifact-shaped problem
+   * must not be the reason a delivery result is lost.
    */
   path: import_zod42.z.string().min(1).max(1024),
   /** Object key inside the OSS bucket where the artifact was uploaded. */
@@ -4955,6 +4964,26 @@ var DeliveryResultArtifactItemSchema = import_zod42.z.object({
   contentType: import_zod42.z.string().min(1).max(255)
 }).strict();
 var DeliveryResultUpdateSchema = import_zod42.z.object({
+  /**
+   * The turn this delivery result belongs to — `ctx.turnId` on the worker
+   * side (`deriveWorkerTurnId`, uuid v5). Drives `artifacts.turn_id`; see
+   * `specs/features/pilot-v2-session-turns.md` §Projection 6.
+   *
+   * Optional through the migration window: a sandbox image predating P2
+   * omits it, and the control plane then INFERS the turn and records an
+   * anomaly rather than rejecting the write. Delivery attribution must not
+   * become a reason a delivery fails — which is also why an id that names no
+   * turn of THIS session degrades to the same inference (plus a warn log and
+   * the anomaly naming the rejected id) instead of failing the request. The
+   * id is still never honoured across sessions: `artifacts.turn_id` has no
+   * foreign key, so a foreign id would attach these artifacts to a turn
+   * another session's `GET /turns` serves.
+   *
+   * Deliberately NOT part of the `.refine()` below: it qualifies the other
+   * fields rather than mutating anything, so a body carrying only `turnId`
+   * is still the empty request it looks like, and still a 400.
+   */
+  turnId: import_zod42.z.string().uuid().optional(),
   /**
    * The PR / MR URL the agent created. First-write-wins per spec
    * (`UPDATE ... WHERE pull_request_url IS NULL`); subsequent writes
@@ -4963,10 +4992,11 @@ var DeliveryResultUpdateSchema = import_zod42.z.object({
    */
   pullRequestUrl: import_zod42.z.string().url().max(1024).optional(),
   /**
-   * Append-set of artifacts uploaded for this run. Each item is
-   * upserted independently via the `unique(run_id, path)` constraint;
-   * the response indicates how many of the submitted items resulted
-   * in a new row.
+   * Append-set of artifacts uploaded for this run. Each item is upserted
+   * independently via the `unique(run_id, path)` / `unique(session_id, path)`
+   * constraint; the response indicates how many of the submitted items
+   * resulted in a new row. Items are keyed by `path` — see the field's own
+   * doc for what a repeated path inside one body means.
    */
   artifacts: import_zod42.z.array(DeliveryResultArtifactItemSchema).max(64).optional(),
   /**
@@ -5652,7 +5682,28 @@ var RecordWorkspaceSnapshotRequestSchema = import_zod50.z.object({
    * parts may be null ("nothing to restore" — a valid no-op snapshot, NOT
    * a failure, per 已定方案 决策②).
    */
-  snapshot: WorkspaceSnapshotSchema
+  snapshot: WorkspaceSnapshotSchema,
+  /**
+   * The turn whose end produced this snapshot (`ctx.turnId`, uuid v5 from
+   * `deriveWorkerTurnId`). The control plane stamps
+   * `session_turns.workspace_snapshot_captured_at` on that row; the stored
+   * snapshot JSON and its session-level latest-wins semantics are unchanged.
+   *
+   * **It lives on the ENVELOPE, not inside `snapshot`** (T-INV-6).
+   * `WorkspaceSnapshotSchema` is `.strict()` and is re-used verbatim as
+   * `PodAgentStartWorkerRequestSchema.workspaceSnapshot`, which travels
+   * control-plane → pod-agent: a key added there makes every pod-agent
+   * older than the change reject `POST /pilot/worker/start`. The contract
+   * test in `__tests__/pilot-v2-workspace-snapshot.test.ts` pins this.
+   *
+   * Optional for one migration window. This envelope is `.strict()`, so a
+   * worker that sends `turnId` to a control plane predating this field gets
+   * a 400 and loses the snapshot entirely — **control-plane and agent-hub
+   * MUST ship before the sandbox image**. Until the window closes the
+   * control plane infers the turn (most recent completed one) when it is
+   * absent; after it, this becomes required.
+   */
+  turnId: import_zod50.z.string().uuid().optional()
 }).strict();
 var RecordWorkspaceSnapshotResponseSchema = import_zod50.z.object({
   success: import_zod50.z.literal(true),
@@ -5685,44 +5736,54 @@ var WorkspaceExportPartSchema = WorkspaceSnapshotPartSchema.extend({
 var WorkspaceExportDataSchema = import_zod50.z.object({
   version: import_zod50.z.literal("v1"),
   /**
-   * Opaque monotonic cursor identifying this capture. **Not a turn ordinal**
+   * **Internal ordering cursor. Prefer {@link WorkspaceExportDataSchema.shape.turnId}.**
+   *
+   * Opaque monotonic value identifying this capture. **Not a turn ordinal**
    * despite the name: the capture side sets it to `capturedAt.getTime()`
    * (epoch milliseconds, sandbox clock). The name is fixed by the stored
    * `WorkspaceSnapshot` envelope. Never render it as "turn N".
    *
-   * Its one job for a caller is deciding **whether the snapshot is this turn's
-   * or the previous turn's**. The worker emits the turn's terminal event
-   * BEFORE it captures and uploads, so an export issued the moment a turn
-   * completes races the capture: it returns either 404 or the PRIOR turn's
-   * snapshot. Compare against `completedAt` from the terminal event payload —
-   * both come from the same in-sandbox clock, and the capture is ordered after
-   * the terminal append — and poll until
-   * `capturedAtTurn >= Date.parse(completedAt)`, with a bounded timeout.
-   *
-   * **`>=`, not `>`.** The two readings are `ctx.now()` calls in one process
-   * separated by a single `await`, at millisecond resolution, so they can land
-   * on the SAME millisecond. Under a strict `>` that turn's own snapshot never
-   * satisfies the test, and the caller polls out the timeout and concludes "no
-   * files" for a turn that did produce them — a wrong answer that looks like a
-   * normal one.
-   *
-   * `>=` cannot admit the previous turn's snapshot: that capture happens in the
-   * tail of turn N-1, before turn N is dispatched at all, so it precedes turn
-   * N's `completedAt` by a whole turn (turns are serial per session — a second
-   * concurrent turn is refused with `SESSION_TURN_IN_PROGRESS`). Equality is
-   * only reachable within one turn, between its own terminal and its own
-   * capture.
-   *
-   * Residual limit, deliberately not papered over: if the sandbox clock steps
-   * BACKWARDS between the terminal append and the capture (NTP correction),
-   * `capturedAtTurn` lands before `completedAt` and neither `>` nor `>=`
-   * accepts it. The poll then times out, and the caller cannot distinguish that
-   * from "nothing was produced". Anchoring the snapshot to a turn identity
-   * rather than a timestamp is the real fix — see the spec's follow-ups.
+   * Its remaining job is the platform's own latest-wins comparison on the
+   * recording path. The freshness question it used to answer for callers —
+   * "is this snapshot my turn's or the previous turn's?" — is now answered
+   * directly by `turnId`: compare it against the turn you dispatched instead
+   * of comparing timestamps. The old recipe (poll until
+   * `capturedAtTurn >= Date.parse(completedAt)`, `>=` and not `>` because the
+   * two `ctx.now()` readings can land on the same millisecond) still works and
+   * is the only option against a sandbox image predating P2, but it carries a
+   * failure mode `turnId` does not: a BACKWARD sandbox clock step (NTP
+   * correction) between the terminal append and the capture puts
+   * `capturedAtTurn` before `completedAt`, and neither `>` nor `>=` accepts
+   * it — the poll then times out and looks exactly like "nothing was
+   * produced".
+   *
+   * The race itself is unchanged either way: the worker emits the turn's
+   * terminal event BEFORE it captures and uploads, so an export issued the
+   * moment a turn completes returns either 404 or the PRIOR turn's snapshot.
+   * Poll with a bounded timeout; with `turnId` the predicate is equality
+   * against your own turn, so there is nothing to reason about clocks.
    */
   capturedAtTurn: import_zod50.z.number().int().nonnegative(),
   /** ISO-8601 capture time — the field to show a human. */
   capturedAt: import_zod50.z.string().min(1),
+  /**
+   * The turn whose end produced this snapshot, when the platform knows it.
+   * This is the field a caller polls on: the export is this turn's iff
+   * `turnId` equals the turn id it dispatched — no clock comparison, and
+   * immune to the backward-clock-step hole in `capturedAtTurn`.
+   *
+   * Absent (or attributed to an earlier turn than you expect) in three cases,
+   * all of which mean "not yours yet", not "broken":
+   *   1. the snapshot was recorded by a sandbox image predating the envelope
+   *      `turnId` — the platform then attributes it to the most recent
+   *      completed turn and flags the inference;
+   *   2. the turn's projection had not materialized its `session_turns` row
+   *      when the snapshot landed, so there was no row to stamp;
+   *   3. the session predates this field entirely.
+   * Keep the `capturedAtTurn` fallback for those; do not treat a missing
+   * `turnId` as an error.
+   */
+  turnId: import_zod50.z.string().uuid().nullable().optional(),
   parts: import_zod50.z.object({
     repoBundle: WorkspaceExportPartSchema.nullable(),
     externalArchive: WorkspaceExportPartSchema.nullable()
@@ -7536,7 +7597,35 @@ var TurnArtifactBundleSchema = import_zod58.z.object({
   /** Absent for a `rejected` bundle — nothing was uploaded, so there is no row. */
   artifactId: import_zod58.z.string().optional(),
   state: ArtifactBundleStateSchema,
+  /**
+   * MUST STAY A PLAIN `number` — widening it to `.nullable()` is a wire break,
+   * not an additive change. `@kanyun-ai-infra/agenthub` bundles contracts into
+   * its published artifact (`noExternal: ["@pilot/contracts"]`), so SDK 1.6.0
+   * carries a FROZEN copy of this schema with `entryCount` a required number.
+   * Old readers tolerate keys they have never heard of (every envelope on the
+   * turn read path is a non-strict `z.object`, which strips them) but not a
+   * value outside the type they froze: a `null` here makes 1.6.0's
+   * `sessions.turns.get` / `.list` throw `MALFORMED_PLATFORM_RESPONSE` for
+   * every turn that has any artifact row at all.
+   *
+   * So "not counted" travels as `0` plus {@link entryCountKnown} `false`
+   * rather than as `null`. The real count lives in the manifest inside the zip
+   * in object storage, and the read path that produces a `Turn` does not fan
+   * out to object storage to get it; to see the actual entries, follow
+   * `TurnArtifacts.incrementalHref` / `cumulativeHref` on the parent object.
+   */
   entryCount: import_zod58.z.number().int().nonnegative(),
+  /**
+   * Is {@link entryCount} a measurement? Absent or `false` means it is not —
+   * the `0` above is a placeholder, NOT an empty bundle. Optional so the key
+   * itself is additive: a reader frozen before it existed drops it and still
+   * parses, and one that has it must treat "absent" as "unknown" too, because
+   * that is exactly what a pre-P2 control plane sends.
+   *
+   * `true` is reserved for a build that really counts the manifest entries.
+   * Nothing sets it today.
+   */
+  entryCountKnown: import_zod58.z.boolean().optional(),
   createdAt: import_zod58.z.string(),
   reason: import_zod58.z.string().optional()
 });
@@ -10654,14 +10743,14 @@ var SessionsResource = class {
    * **`waitForTurn` resolving does NOT mean the snapshot is ready.** The worker
    * emits the turn's terminal event and only then bundles, uploads and reports.
    * Exporting the instant a turn completes therefore returns either a 404 or —
-   * worse, because it is silent — the PREVIOUS turn's snapshot. Poll for
-   * freshness instead of calling once:
+   * worse, because it is silent — the PREVIOUS turn's snapshot. Poll until the
+   * export names your turn instead of calling once:
    *
    * ```ts
    * const { terminalEvent } = await agenthub.sessions.waitForTurn(sessionId, turnId);
-   * // `completedAt` exists ONLY on a success terminal, and is the same
-   * // in-sandbox clock as capturedAtTurn (capture is strictly ordered after the
-   * // terminal append). `payload` is typed `unknown`, hence the cast.
+   * // `completedAt` exists ONLY on a success terminal. Its value is the
+   * // fallback cursor below; its PRESENCE is what tells you the turn succeeded.
+   * // `payload` is typed `unknown`, hence the cast.
    * const completedAtRaw = (terminalEvent.payload as { completedAt?: string })?.completedAt;
    * if (!completedAtRaw) {
    *   // Failed / aborted turn: nothing was captured, and polling would just
@@ -10674,11 +10763,24 @@ var SessionsResource = class {
    * while (Date.now() < deadline) {
    *   try {
    *     const candidate = await agenthub.sessions.exportWorkspace(sessionId);
-   *     // `>=`, not `>`: both timestamps are `ctx.now()` in the same sandbox
-   *     // process, one `await` apart, at millisecond resolution — so they can
-   *     // be EQUAL, and a strict `>` would then never accept this turn's own
-   *     // snapshot and report "no files" after the full timeout.
-   *     if (candidate.capturedAtTurn >= completedAt) { exported = candidate; break; }
+   *     // The snapshot names its own turn — compare ids, no clock reasoning.
+   *     if (candidate.turnId === turnId) { exported = candidate; break; }
+   *     // Fallback: `turnId` didn't match — either it's absent (session
+   *     // predates the field, or the turn's `session_turns` row hadn't
+   *     // materialized yet when the snapshot landed) or it's present but
+   *     // WRONG: a sandbox image older than this field makes the platform
+   *     // infer "most recent completed turn", which can land on a turn you
+   *     // didn't dispatch. Either way `turnId` cannot tell you "not mine" —
+   *     // only the timestamp can, so any non-match falls through to it, not
+   *     // just a null one. `>=`, not `>`: both timestamps are `ctx.now()` in
+   *     // the same sandbox process, one `await` apart, at millisecond
+   *     // resolution — so they can be EQUAL, and a strict `>` would never
+   *     // accept this turn's own snapshot, reporting "no files" after the
+   *     // full timeout.
+   *     if (candidate.capturedAtTurn >= completedAt) {
+   *       exported = candidate;
+   *       break;
+   *     }
    *   } catch (err) {
    *     // Discriminate on `code`, NOT on status: SESSION_NOT_FOUND is a 404 too,
    *     // and a bad id / deleted session / lost access must surface immediately
@@ -10695,6 +10797,20 @@ var SessionsResource = class {
    * // exported === null → this turn produced no files. Normal, not a failure.
    * ```
    *
+   * **`turnId` is the primary check; the timestamp branch is only a fallback.**
+   * They are not equivalent. `turnId` is an equality test against an id you
+   * already hold — but a non-matching `turnId` does not mean "not my turn": it
+   * can be null, or it can be a DIFFERENT turn the platform inferred during the
+   * migration window, and nothing in the response distinguishes the two. Treat
+   * every non-match the same way and fall back to the timestamp rather than
+   * special-casing "absent." `capturedAtTurn` is an internal epoch-ms cursor
+   * with a failure mode `turnId` does not have: a BACKWARD sandbox clock step
+   * (NTP correction) between the terminal append and the capture puts it before
+   * `completedAt`, no comparison accepts it, and the poll times out —
+   * reporting "no files" for a turn that produced them, which reads like a
+   * normal result. Never display either value; `capturedAt` is the
+   * human-facing field.
+   *
    * **404 `WORKSPACE_SNAPSHOT_NOT_FOUND` is not by itself an error.** It throws
    * (a `PilotPlatformApiError`, so "this session never ran" is never silently
    * flattened to an empty result), and you MUST catch it inside the polling