Release/1.7.1

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project are documented in this file. Format follows
 
 For narrative release notes written for operators and product owners, see [RELEASE_NOTES.md](RELEASE_NOTES.md).
 
+## [1.7.1] - 2026-07-17
+
+Patch release fixing a Word-document save failure in the AgentCore Runtime and advancing the **session-metadata static-sort-key migration** (issue #175) to its write side. Word tools now resolve the user-files bucket's real region instead of pinning to `AWS_REGION`, so `PutObject` no longer fails with `PermanentRedirect`. On the storage side, new sessions are now born with a static sort key and legacy rows self-migrate in place on their next write, structurally eliminating the ghost-row race behind the "Failed to parse session item" warnings and closing the first-turn duplicate-row race. No infra or data migration; ship through `backend.yml`.
+
+### ✨ Improved
+
+- Static-sort-key write path for session metadata (issue #175 Phase 1b) — new sessions are born at a static sort key (`S#{session_id}` + `SessionRecencyIndex` keys) guarded by a real `attribute_not_exists(PK)` conditional put, and legacy rows do a one-time in-place migration to the static SK on their next write. Rows no longer rotate on every message, so the ghost-row race that produced "Failed to parse session item" warnings is structurally eliminated for migrated rows, and the deterministic SK closes the first-turn duplicate-row race the old timestamped SK could not gate. `delete_session` resolves the raw SK via the GSI (catching migrated rows the old reconstruction missed) and soft-deletes in place. The recency index is updated (`SET GSI4`) for active rows and removed for deleted ones (#673)
+
+### 🐛 Fixed
+
+- Word-document `PutObject` no longer fails with `PermanentRedirect` in the AgentCore Runtime — the user-files S3 client pinned its endpoint to `https://s3.{AWS_REGION}.amazonaws.com`, but the runtime's `AWS_REGION` does not reliably match the bucket region and the explicit `endpoint_url` disabled botocore's automatic region redirect. The client now resolves the bucket's true region via `HeadBucket` (`x-amz-bucket-region`, backed by the `s3:ListBucket` the runtime role already has) and drops the hardcoded `endpoint_url`, fixing both the save and the presigned download URL (#674)
+
 ## [1.7.0] - 2026-07-17
 
 Feature release adding a full **Word (.docx) document toolset** for the agent and advancing the **session-metadata static-sort-key migration** (issue #175) through its read-side phases. The agent can now create, modify, list, and read Word documents — rendered inline in chat with a download button — behind the `create_word_document` capability toggle. On the storage side, a new sparse `SessionRecencyIndex` GSI plus a dual-scheme union reader let session listing work whether or not a session's base sort key has been migrated, deploying safely in any order. Also bumps `strands-agents` to 1.48.0 to fix an "Agent force-stopped" crash on non-PDF document uploads. Requires a CDK deploy for the new GSI; ships the rest via `backend.yml` + the frontend pipeline.

README.md

@@ -8,7 +8,7 @@
 **An open-source, production-ready Generative AI platform for institutions**
 *Built by Boise State University, designed for everyone.*
 
-[![Release](https://img.shields.io/badge/Release-v1.7.0-6366f1?style=flat&logo=github&logoColor=white)](RELEASE_NOTES.md)
+[![Release](https://img.shields.io/badge/Release-v1.7.1-6366f1?style=flat&logo=github&logoColor=white)](RELEASE_NOTES.md)
 [![Nightly](https://github.com/Boise-State-Development/agentcore-public-stack/actions/workflows/nightly.yml/badge.svg)](https://github.com/Boise-State-Development/agentcore-public-stack/actions/workflows/nightly.yml)
 
 ![Python](https://img.shields.io/badge/Python-3.13+-3776AB?style=flat&logo=python&logoColor=white)
@@ -296,7 +296,7 @@ agentcore-public-stack/
 
 See [RELEASE_NOTES.md](RELEASE_NOTES.md) for the full changelog, including new features, bug fixes, platform upgrades, and deployment notes for each release.
 
-**Current release:** v1.7.0
+**Current release:** v1.7.1
 
 ---
 

RELEASE_NOTES.md

@@ -1,3 +1,32 @@
+# Release Notes — v1.7.1
+
+**Release Date:** July 17, 2026
+**Previous Release:** v1.7.0 (July 17, 2026)
+
+---
+
+> 🚀 **Backend-only release.** No CDK deploy and no data migration — ship through `backend.yml`. Session rows self-migrate to the static sort key on their next write; nothing to run.
+
+---
+
+## Highlights
+
+v1.7.1 is a patch fixing a Word-document save failure and advancing the **session-metadata static-sort-key migration** (issue #175) to its write side. Saving a generated Word document no longer fails with `PermanentRedirect` in the AgentCore Runtime — the S3 client now resolves the user-files bucket's real region instead of trusting `AWS_REGION`. On the storage side, new sessions are now **born with a static sort key** and legacy rows **self-migrate in place** on their next write, so rows stop rotating on every message — structurally eliminating the ghost-row race behind the "Failed to parse session item" warnings and closing the first-turn duplicate-row race.
+
+## Fixed — Word-document saves failing with `PermanentRedirect`
+
+The user-files S3 client pinned its endpoint to `https://s3.{AWS_REGION}.amazonaws.com`. In the AgentCore Runtime, `AWS_REGION` does not reliably match the bucket's region, and the explicit `endpoint_url` disabled botocore's automatic S3 region redirect — so `PutObject` failed with `PermanentRedirect` and Word-document saves broke. The client (`agents/builtin_tools/word_document_tool.py`) now resolves the bucket's true region via `HeadBucket` (reading the `x-amz-bucket-region` header, which maps to the `s3:ListBucket` permission the runtime role already holds — avoiding the ungranted `s3:GetBucketLocation`) and drops the hardcoded `endpoint_url`. This fixes both the save and the presigned download URL region; if the region lookup is ever unavailable, botocore's now-enabled built-in redirect still corrects it.
+
+## Session-metadata static-sort-key migration (issue #175, write-side)
+
+v1.7.0 landed the read side (every reader tolerates both sort-key schemes); v1.7.1 turns on the **write** side. New sessions are now created at a static base sort key (`S#{session_id}` plus the `SessionRecencyIndex` keys) behind a real `attribute_not_exists(PK)` conditional put, and any still-legacy row does a one-time in-place migration to the static SK on its next write. Because the row no longer encodes `lastMessageAt` in the sort key, it never moves — the ghost-row race that produced "Failed to parse session item" warnings is structurally eliminated for every migrated row, and the deterministic sort key makes the first-turn duplicate-row guard meaningful for the first time. `delete_session` now resolves the raw sort key via the GSI (catching migrated rows the old `S#ACTIVE#…` reconstruction missed) and soft-deletes in place; the sparse recency index is set for active rows and removed for deleted ones. All resolve-then-update writers already operate on the current sort key and need no change. Covered by `TestWriteSideMigration` (born-static, one-time migrate, no rotation, in-place/legacy soft-delete, end-to-end) against the real `ConditionalCheckFailedException` contract.
+
+## 🚀 Deployment notes
+
+Ship through `backend.yml` (app-api + inference-api). No CDK deploy and no data migration — rows migrate themselves on their next write, and readers already tolerate both schemes as of v1.7.0. No breaking changes.
+
+---
+
 # Release Notes — v1.7.0
 
 **Release Date:** July 17, 2026

VERSION

@@ -1 +1 @@
-1.7.0
+1.7.1

backend/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentcore-stack"
-version = "1.7.0"
+version = "1.7.1"
 requires-python = ">=3.10"
 description = "Multi-agent conversational AI system with AWS Bedrock AgentCore"
 readme = "README.md"

backend/src/agents/builtin_tools/word_document_tool.py

@@ -47,6 +47,7 @@
 
 import boto3
 from botocore.config import Config
+from botocore.exceptions import ClientError
 
 from strands import tool
 
@@ -118,21 +119,72 @@ def _validate_document_name(name: str) -> Tuple[bool, Optional[str]]:
 
 
 _s3_client = None
+_bucket_region: Optional[str] = None
+
+
+def _resolve_bucket_region(bucket: str) -> str:
+    """Discover the user-files bucket's real region.
+
+    The AgentCore Runtime's ``AWS_REGION`` does not reliably match the
+    deployment/bucket region. Pinning the S3 client to the wrong region makes
+    ``PutObject`` fail with ``PermanentRedirect``. ``get_bucket_location`` is
+    region-agnostic (queried against us-east-1) and returns the true region;
+    a null ``LocationConstraint`` means us-east-1. Falls back to the env
+    region if the lookup is unavailable (e.g. missing s3:GetBucketLocation) —
+    ``PutObject`` still succeeds in that case because the client below no
+    longer hard-pins ``endpoint_url``, so botocore's built-in S3 region
+    redirect can correct it.
+    """
+    global _bucket_region
+    if _bucket_region:
+        return _bucket_region
+    # HeadBucket (maps to s3:ListBucket, which the runtime role has) returns
+    # the true region in the ``x-amz-bucket-region`` header — on a 200 when
+    # probed from the matching region and on the 301 otherwise. This avoids
+    # depending on s3:GetBucketLocation, which the inference-api role is not
+    # granted.
+    region = None
+    try:
+        probe = boto3.client("s3", region_name="us-east-1")
+        resp = probe.head_bucket(Bucket=bucket)
+        region = (
+            resp.get("ResponseMetadata", {})
+            .get("HTTPHeaders", {})
+            .get("x-amz-bucket-region")
+        )
+    except ClientError as exc:
+        region = (
+            exc.response.get("ResponseMetadata", {})
+            .get("HTTPHeaders", {})
+            .get("x-amz-bucket-region")
+        )
+        if not region:
+            logger.warning(f"Could not resolve region for bucket {bucket}: {exc}")
+    except Exception as exc:  # pragma: no cover - fall back to env region
+        logger.warning(f"Could not resolve region for bucket {bucket}: {exc}")
+    _bucket_region = region or _region()
+    return _bucket_region
 
 
 def _s3():
-    """Regional, SigV4 S3 client (matches FileUploadService config)."""
+    """SigV4 S3 client pinned to the user-files bucket's actual region.
+
+    Uses the bucket's real region (not ``AWS_REGION``) so ``PutObject`` never
+    hits ``PermanentRedirect`` in the AgentCore Runtime. No explicit
+    ``endpoint_url``: botocore then builds the correct regional virtual-host
+    endpoint (which keeps presigned download URLs CORS-safe) and can still
+    auto-correct the region if the resolved value is off.
+    """
     global _s3_client
     if _s3_client is None:
-        region = _region()
+        region = _resolve_bucket_region(_user_files_bucket())
         _s3_client = boto3.client(
             "s3",
             region_name=region,
             config=Config(
                 signature_version="s3v4",
                 s3={"addressing_style": "virtual"},
             ),
-            endpoint_url=f"https://s3.{region}.amazonaws.com",
         )
     return _s3_client
 

backend/src/apis/app_api/sessions/services/session_service.py

@@ -221,56 +221,60 @@ async def delete_session(self, user_id: str, session_id: str) -> bool:
             return False
 
         try:
-            # Get current session via GSI to find its SK
-            session = await self.get_session(user_id, session_id)
-            if not session:
+            # Resolve the raw row (with its actual SK) via GSI. Do NOT reconstruct the
+            # SK from lastMessageAt — under the static-SK schema (issue #175) a migrated
+            # row lives at S#{session_id}, not S#ACTIVE#{lastMessageAt}#{id}, so a
+            # reconstructed key would miss it entirely.
+            from apis.shared.sessions.metadata import _get_session_by_gsi, _static_session_sk
+
+            existing = await _get_session_by_gsi(session_id, user_id, self.table)
+            if not existing:
                 logger.info("Session not found for deletion")
                 return False
 
-            if session.deleted:
+            if existing.get('deleted') or existing.get('status') == 'deleted':
                 logger.info("Session already deleted")
                 return True
 
             now = datetime.now(timezone.utc)
             deleted_at = now.isoformat()
-
-            # Build old and new SKs
-            old_sk = f'S#ACTIVE#{session.last_message_at}#{session_id}'
-            new_sk = f'S#DELETED#{deleted_at}#{session_id}'
             pk = f'USER#{user_id}'
-
-            # Build the deleted item with all fields
-            deleted_item = {
-                'PK': pk,
-                'SK': new_sk,
-                'GSI_PK': f'SESSION#{session_id}',
-                'GSI_SK': 'META',
-                'sessionId': session_id,
-                'userId': user_id,
-                'title': session.title or '',
-                'status': 'deleted',
-                'createdAt': session.created_at,
-                'lastMessageAt': session.last_message_at,
-                'messageCount': session.message_count or 0,
-                'starred': session.starred or False,
-                'tags': session.tags or [],
-                'deleted': True,
-                'deletedAt': deleted_at
-            }
-
-            # Include preferences if present
-            # Convert floats to Decimals since DynamoDB high-level API requires Decimal for numbers
-            if session.preferences:
-                prefs = session.preferences.model_dump(by_alias=True)
-                deleted_item['preferences'] = _convert_float_to_decimal(prefs)
-
-            # Use high-level API: put_item + delete_item
-            # Put new item first, then delete old - if put fails, nothing is lost
-            # This is simpler and more reliable than transact_write_items
-            self.table.put_item(Item=deleted_item)
-            self.table.delete_item(
-                Key={'PK': pk, 'SK': old_sk}
-            )
+            old_sk = existing['SK']
+            target_sk = _static_session_sk(session_id)
+
+            if old_sk == target_sk:
+                # Already migrated — soft-delete in place: flip status + drop the sparse
+                # recency keys so the row leaves the active listing. No row move.
+                self.table.update_item(
+                    Key={'PK': pk, 'SK': target_sk},
+                    UpdateExpression=(
+                        "SET #s = :d, deleted = :true, deletedAt = :da "
+                        "REMOVE GSI4_PK, GSI4_SK"
+                    ),
+                    ExpressionAttributeNames={'#s': 'status'},
+                    ExpressionAttributeValues={':d': 'deleted', ':true': True, ':da': deleted_at},
+                )
+            else:
+                # Legacy row — migrate to the static tombstone (status=deleted, no GSI4)
+                # and drop the old row. One-time move; carry existing fields.
+                deleted_item = {
+                    k: v for k, v in existing.items()
+                    if k not in ('PK', 'SK', 'GSI4_PK', 'GSI4_SK')
+                }
+                deleted_item.update({
+                    'PK': pk,
+                    'SK': target_sk,
+                    'GSI_PK': f'SESSION#{session_id}',
+                    'GSI_SK': 'META',
+                    'sessionId': session_id,
+                    'userId': user_id,
+                    'status': 'deleted',
+                    'deleted': True,
+                    'deletedAt': deleted_at,
+                })
+                # existing came back with Decimals converted to floats — put_item needs Decimal.
+                self.table.put_item(Item=_convert_float_to_decimal(deleted_item))
+                self.table.delete_item(Key={'PK': pk, 'SK': old_sk})
 
             logger.info("Soft-deleted session")