Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

fix: keep derived session titles from splitting emoji surrogate pairs (#981)

Soumojit Das87634d8248e7
diff --git a/.changeset/session-title-surrogate-boundary.md b/.changeset/session-title-surrogate-boundary.md
new file mode 100644
index 000000000..c20c84c8f
--- /dev/null
+++ b/.changeset/session-title-surrogate-boundary.md
@@ -0,0 +1,6 @@
+---
+'@truefoundry/trueforge': patch
+---
+
+Truncate derived session titles on grapheme boundaries so emoji clusters are never split, and leave
+the title unset when nothing fits instead of storing a blank value.
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index 788ba8493..7c71d28b8 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -294,6 +294,27 @@ function createTurnResolver(deps: {
});
}
+/** Grapheme segmentation for title truncation (locale-independent per UAX #29). */
+const titleSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+/**
+ * Caps a title at {@link MAX_SESSION_TITLE_LENGTH} UTF-16 units without splitting a
+ * grapheme cluster: clusters that would cross the cap (emoji with skin tones or
+ * ZWJ sequences, which read as one unit but span several) are dropped whole.
+ */
+function truncateSessionTitle(title: string): string {
+ let truncated = '';
+ let length = 0;
+ for (const { segment } of titleSegmenter.segment(title)) {
+ if (length + segment.length > MAX_SESSION_TITLE_LENGTH) {
+ break;
+ }
+ truncated += segment;
+ length += segment.length;
+ }
+ return truncated;
+}
+
/**
* Derives a session title from the first user message of the first turn. Returns the
* trimmed text (capped at {@link MAX_SESSION_TITLE_LENGTH}) or `undefined` when no usable
@@ -317,7 +338,13 @@ export function deriveSessionTitle(input: TurnInputItem[] | undefined): string |
if (!trimmed) {
return undefined;
}
- return trimmed.slice(0, MAX_SESSION_TITLE_LENGTH);
+ const title = truncateSessionTitle(trimmed);
+ // A single cluster longer than the cap truncates to nothing; treat it as no usable title
+ // so the store keeps the title unset instead of persisting a blank first-write-wins value.
+ if (!title) {
+ return undefined;
+ }
+ return title;
}
/**
diff --git a/packages/trueforge/tests/unit/apis/turns.test.ts b/packages/trueforge/tests/unit/apis/turns.test.ts
index e75e602eb..bfdb7a6d0 100644
--- a/packages/trueforge/tests/unit/apis/turns.test.ts
+++ b/packages/trueforge/tests/unit/apis/turns.test.ts
@@ -3,11 +3,12 @@ import {
AgentSpecSchema,
Sessions,
TurnNotFoundError,
+ type TurnInputItem,
type TurnStreamingEvent,
} from '@truefoundry/trueforge-core/agent-session';
import type { Kysely } from 'kysely';
import { createLogger } from 'winston';
-import { createTurnsRouter, turnStreamId } from '../../../src/apis/turns';
+import { createTurnsRouter, deriveSessionTitle, turnStreamId } from '../../../src/apis/turns';
import { TrueForgeAuthorizer, type Authorizer } from '../../../src/auth/authorizer';
import { STANDALONE_REQUEST_CONTEXT } from '../../../src/auth/identity';
import { McpServerWithAuthStore } from '../../../src/db/McpServerWithAuthStore';
@@ -39,6 +40,55 @@ describe('turns', () => {
expect(turnStreamId('ten', 'sess', 'turn1')).toBe('tfg:agent:turn:ten:sess:turn1:stream');
});
+ describe('deriveSessionTitle', () => {
+ function userMessage(content: string): TurnInputItem[] {
+ return [{ type: 'user.message', content }];
+ }
+
+ it('caps long titles at 50 characters', () => {
+ expect(deriveSessionTitle(userMessage('x'.repeat(200)))).toBe('x'.repeat(50));
+ });
+
+ it('returns short titles unchanged', () => {
+ expect(deriveSessionTitle(userMessage('hello world'))).toBe('hello world');
+ });
+
+ it('returns undefined when no usable text is present', () => {
+ expect(deriveSessionTitle(undefined)).toBeUndefined();
+ expect(deriveSessionTitle([])).toBeUndefined();
+ expect(deriveSessionTitle(userMessage(' '))).toBeUndefined();
+ });
+
+ it('keeps an emoji pair fully inside the cap', () => {
+ const text = `${'b'.repeat(48)}πŸ˜€`;
+ expect(deriveSessionTitle(userMessage(text))).toBe(text);
+ });
+
+ it('backs off when the cap would split a surrogate pair', () => {
+ const title = deriveSessionTitle(userMessage(`${'a'.repeat(49)}πŸ˜€ and more`));
+ expect(title).toBe('a'.repeat(49));
+ });
+
+ it('drops a skin-tone cluster that would cross the cap instead of keeping its base', () => {
+ const title = deriveSessionTitle(userMessage(`${'x'.repeat(48)}πŸ‘‹πŸ½ and more`));
+ expect(title).toBe('x'.repeat(48));
+ });
+
+ it('keeps a skin-tone cluster that fits exactly inside the cap', () => {
+ const text = `${'y'.repeat(46)}πŸ‘‹πŸ½`;
+ expect(deriveSessionTitle(userMessage(text))).toBe(text);
+ });
+
+ it('drops a ZWJ sequence that would cross the cap', () => {
+ const title = deriveSessionTitle(userMessage(`${'z'.repeat(44)}πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦ and more`));
+ expect(title).toBe('z'.repeat(44));
+ });
+
+ it('returns undefined when a single cluster exceeds the cap', () => {
+ expect(deriveSessionTitle(userMessage(`e${'\u0301'.repeat(60)}`))).toBeUndefined();
+ });
+ });
+
describe('turn ownership', () => {
it('returns 403 for all turn routes when the caller is not the session creator', async () => {
const db = createSqliteDb(':memory:');