feat(session)!: remove the path-based transcript API; fix #463 follow-ups; release version source

.github/scripts/next-release-version.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Computes the next release version for the Release workflow.
+#
+# usage: next-release-version.sh <patch|minor|major> <workspace-version> [tag ...]
+#
+# The base is the highest of the workspace version and every plain `vX.Y.Z`
+# tag given. The workspace version alone is not a safe base: releases are
+# published from a tag, and the version in Cargo.toml can lag the latest tag
+# (it sat at 2.1.4 while v2.2.0 through v2.8.0 existed, so the workflow kept
+# proposing a tag that was already taken). Prints `<base> <next>`.
+set -euo pipefail
+
+bump="${1:?bump (patch|minor|major) required}"
+workspace_version="${2:?workspace version required}"
+shift 2
+
+semver='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+if ! [[ "$workspace_version" =~ $semver ]]; then
+  echo "Workspace version '${workspace_version}' is not X.Y.Z" >&2
+  exit 1
+fi
+
+base="$workspace_version"
+for tag in "$@"; do
+  version="${tag#v}"
+  # Pre-release and other non-release tags never set the base.
+  if [[ "$tag" == v* && "$version" =~ $semver ]]; then
+    base="$(printf '%s\n%s\n' "$base" "$version" | sort -V | tail -n1)"
+  fi
+done
+
+IFS=. read -r major minor patch <<< "$base"
+case "$bump" in
+  major)
+    major=$((major + 1))
+    minor=0
+    patch=0
+    ;;
+  minor)
+    minor=$((minor + 1))
+    patch=0
+    ;;
+  patch)
+    patch=$((patch + 1))
+    ;;
+  *)
+    echo "Unsupported bump: ${bump}" >&2
+    exit 1
+    ;;
+esac
+
+echo "${base} ${major}.${minor}.${patch}"

.github/scripts/next-release-version.test.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Tests for next-release-version.sh. Run: .github/scripts/next-release-version.test.sh
+set -euo pipefail
+
+script="$(cd "$(dirname "$0")" && pwd)/next-release-version.sh"
+failures=0
+
+expect() {
+  local name="$1" want="$2"
+  shift 2
+  local got
+  if got="$("$script" "$@" 2>/dev/null)"; then :; else got="error"; fi
+  if [[ "$got" != "$want" ]]; then
+    echo "FAIL ${name}: want '${want}', got '${got}'" >&2
+    failures=$((failures + 1))
+  fi
+}
+
+# The regression: a stale workspace version must not hide newer tags.
+expect "stale workspace minor" "2.8.0 2.9.0" minor 2.1.4 v2.1.4 v2.2.0 v2.7.0 v2.8.0
+expect "stale workspace patch" "2.8.0 2.8.1" patch 2.1.4 v2.8.0 v2.2.0
+expect "stale workspace major" "2.8.0 3.0.0" major 2.1.4 v2.8.0
+# Numeric, not lexical, ordering.
+expect "numeric ordering" "2.10.0 2.11.0" minor 2.1.4 v2.9.0 v2.10.0
+# A workspace version ahead of every tag still wins.
+expect "workspace ahead" "3.0.0 3.1.0" minor 3.0.0 v2.8.0
+expect "no tags" "2.1.4 2.1.5" patch 2.1.4
+# Pre-release and foreign tags never set the base.
+expect "prerelease ignored" "2.8.0 2.9.0" minor 2.1.4 v2.8.0 v3.0.0-rc1 nightly 9.9.9
+# A leading-zero tag is not a release version (08 would be octal).
+expect "leading zero ignored" "2.8.0 2.9.0" minor 2.1.4 v2.8.0 v2.08.0
+# Bad input fails.
+expect "bad bump" "error" hotfix 2.1.4
+expect "bad workspace version" "error" minor 2.1 v2.8.0
+
+if ((failures > 0)); then
+  echo "${failures} failure(s)" >&2
+  exit 1
+fi
+echo "next-release-version: ok"

.github/workflows/ci.yml

@@ -64,6 +64,9 @@ jobs:
       - name: Check formatting
         run: cargo fmt --all -- --check
 
+      - name: Release version script
+        run: .github/scripts/next-release-version.test.sh
+
       - name: Clippy
         run: cargo clippy --workspace --all-targets -- -D warnings
 

.github/workflows/release.yml

@@ -85,37 +85,23 @@ jobs:
             exit 1
           fi
 
-          IFS=. read -r major minor patch <<< "$current_version"
-          case "${{ inputs.bump }}" in
-            major)
-              major=$((major + 1))
-              minor=0
-              patch=0
-              ;;
-            minor)
-              minor=$((minor + 1))
-              patch=0
-              ;;
-            patch)
-              patch=$((patch + 1))
-              ;;
-            *)
-              echo "Unsupported bump: ${{ inputs.bump }}" >&2
-              exit 1
-              ;;
-          esac
-
-          next_version="${major}.${minor}.${patch}"
+          # The workspace version can lag the latest tag (releases are cut
+          # from tags), so the next version is derived from the highest of
+          # the two; see the script.
+          git fetch --tags origin
+          mapfile -t existing_tags < <(git tag --list 'v*')
+          versions="$(.github/scripts/next-release-version.sh "${{ inputs.bump }}" "$current_version" "${existing_tags[@]}")"
+          read -r base_version next_version <<< "$versions"
           tag="v${next_version}"
 
-          git fetch --tags origin
           if git rev-parse --verify --quiet "refs/tags/${tag}"; then
             echo "Tag ${tag} already exists" >&2
             exit 1
           fi
 
           {
             echo "current_version=${current_version}"
+            echo "base_version=${base_version}"
             echo "next_version=${next_version}"
             echo "tag=${tag}"
           } >> "$GITHUB_OUTPUT"

CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## Unreleased: the path-based transcript API is removed (tinyagents#453)
+
+**Breaking.** `tinyagents-session` no longer reads or writes a workspace
+directory for transcripts. Everything goes through the store port
+(`TranscriptLocator`/`TranscriptHistory`/`TranscriptRead`, served by
+`DriverSessionStores`, `WorkspaceStores` or `InMemorySessionStores`); the only
+reader of classic `session_raw/*.jsonl` files is the one-time, read-only
+`legacy::import_transcripts_once` / `WorkspaceStores`, and
+`legacy::rewrite_legacy_transcripts` for pre-import fixups.
+
+Removed from `tinyagents_session::transcript`: `FileTranscriptLocator`,
+`FileTranscriptHistory`, `AgentTranscriptFiles`, `agent_transcript_root`,
+`write_transcript*`, `append_transcript_turn*`, `append_interrupted_partial`,
+`append_tools_record`, `read_transcript`, `read_transcript_display`,
+`read_transcript_legacy_md`, `adopt_legacy_session_transcripts`,
+`migrate_layout_if_needed`, `find_latest_transcript`,
+`find_root_transcript_for_thread*`, `find_root_transcripts_for_thread`,
+`read_thread_usage_summary` (and `ThreadUsageSummary`/`SubagentArchetypeUsage`),
+`resolve_keyed_transcript_path*`, `append_background_message` and its
+lock-notification variant, `TranscriptLocator::file_backing`, `view::get_page`,
+`view::get_page_scoped`, `view::project_thread*`, `view::resolve_files_scoped`,
+the view's projection cache, and `thread_spend`. Replacements:
+`append_background_message_in`, `view::get_page_in`,
+`view::project_thread_in(locator, thread_id, agent_id, lookup)`,
+`spend::thread_spend_in`, `TranscriptLocator::thread_transcripts` /
+`root_for_thread_scoped` / `read_session_transcript`, and
+`TranscriptLocator::adopt_legacy` (driver stores).
+`SessionAdoption`, `SessionTurnGuard`, `lock_session_turn` and the rest of the
+locator-based surface are unchanged. The `fs2` dependency is gone.
+
+Fixes (the two deferred tinyagents#463 findings):
+
+- A background append's idempotency check considered every row of the head
+  generation's log, so a key dropped by a compaction *inside the same
+  generation* still reported `Duplicate` and the delivery was lost. It now
+  looks at the generation's live context only (rows after the last compaction
+  plus that compaction's replacement), which is what the contract always said:
+  a key a compaction dropped is appended again.
+- The driver-backed thread listing read the index alone, so a root whose
+  index refresh failed stayed invisible until something read or wrote that
+  transcript again. A listing now compares written index documents with
+  written transcript logs and re-indexes any missing stem before it answers.
+- `legacy::import_transcripts` now carries a classic line's top-level
+  `background` provenance onto the imported row, so an out-of-band delivery
+  keeps its origin and idempotency key after import.
+
+The Release workflow derives the next version from the highest of the
+workspace version and the latest `v*` tag instead of the (stale) workspace
+version alone, so it no longer proposes a tag that already exists.
+
 ## Unreleased: locator-based transcript reads and writes (tinyagents#453)
 
 Hosts can now do through a `TranscriptLocator` everything they used the
@@ -27,8 +77,7 @@ driver store:
 - `legacy::rewrite_legacy_transcripts(workspace_dir, rewrite) ->
   LegacyRewriteReport` for pre-import fixups of classic `session_raw/` files.
 
-The path API is unchanged; `project_from_files` and `thread_spend` now share
-the locator code path.
+(The path API was still present at this point and was removed in the entry above.)
 
 Review follow-ups: `rewrite_legacy_transcripts` keeps a transcript's recorded
 tool declarations, counts unreadable directories and entries in `errors`

crates/tinyagents-integration-tests/Cargo.toml

@@ -10,7 +10,6 @@ publish = false
 [dependencies]
 anyhow = { workspace = true }
 async-trait = { workspace = true }
-chrono = { workspace = true }
 dotenvy = "0.15"
 futures = { workspace = true }
 reqwest = { workspace = true }