Skip to content

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

Fix events indexing, Coerce seq number param to number and update agents.md (#38)

Chirag Jain6b152dd7d3f5
diff --git a/AGENTS.md b/AGENTS.md
index de2949441..439fffb38 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,8 @@
- A change that makes code unused MUST remove that dead code in the same change; it MUST NOT leave stale exports, files, documentation, duplicates, or “just in case” shims.
- Comments MUST explain intent, trade-offs, or constraints and remain concise; they MUST NOT restate the code or include issue-tracker IDs.
- Every nested `AGENTS.md` MUST have a sibling `CLAUDE.md` containing only `@AGENTS.md`, so Cursor and Claude Code load the same scoped rules.
-- Code under `packages/sdk` is autogenerated and MUST NOT be edited manually; changes belong in the generator or its source, not in the generated output.
+- OpenAPI spec under `fern/openapi/openapi.json` is autogenerated in CI and MUST NOT be edited manually
+- Code under `packages/sdk` is autogenerated in CI and MUST NOT be edited manually
- Tests MUST live under a top-level `test` directory that mirrors the `src` layout; they MUST NOT be inlined under `src`.
- Functions with more than one parameter of the same type MUST take a single options object (e.g. `f({ a, b }: { a: string; b: string })`); they MUST NOT use multiple positional parameters of that repeated type (e.g. `f(a: string, b: string)`).
- Zod unions MUST use `z.discriminatedUnion` whenever every member carries a shared literal discriminator field; `z.union` is only permitted when no such common discriminator exists.
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index b7e6df4c5..459191996 100644
--- a/fern/openapi/openapi.json
+++ b/fern/openapi/openapi.json
@@ -4807,7 +4807,10 @@
"required": false,
"schema": {
"minimum": 0,
- "type": "integer"
+ "type": [
+ "integer",
+ "null"
+ ]
}
}
],
diff --git a/packages/sdk/.fern/metadata.json b/packages/sdk/.fern/metadata.json
index e8e18b22c..98f46d1b5 100644
--- a/packages/sdk/.fern/metadata.json
+++ b/packages/sdk/.fern/metadata.json
@@ -26,7 +26,7 @@
"streamType": "web",
"useDefaultRequestParameterValues": true
},
- "originGitCommit": "09ef45c28d8c9e97c441e3c7f0ab3afc321a7563",
+ "originGitCommit": "8937bc865fb2ba0ef37d2fc6e7dcf1676058abfa",
"originGitCommitIsDirty": true,
"invokedBy": "manual",
"requestedVersion": "0.0.0",
diff --git a/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts
index 9c665fdf6..e8523b8a5 100644
--- a/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts
+++ b/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts
@@ -5,5 +5,5 @@
* {}
*/
export interface SubscribeToTurnSessionsRequest {
- afterSequenceNumber?: number;
+ afterSequenceNumber?: number | null;
}
diff --git a/packages/server/src/runtime/event-subscription/inMemory.ts b/packages/server/src/runtime/event-subscription/inMemory.ts
index c94c31dcc..350f51222 100644
--- a/packages/server/src/runtime/event-subscription/inMemory.ts
+++ b/packages/server/src/runtime/event-subscription/inMemory.ts
@@ -14,7 +14,7 @@ import {
} from '.';
interface InMemoryStream<T extends object> {
- /** Dense log: the event at index i has sequence_number i. */
+ /** Dense log: the event at index i has sequence_number i + 1 (1-indexed). */
events: SequencedEvent<T>[];
/** Undefined = no TTL set yet (mirrors a Redis key without EXPIRE). */
expiresAtMs?: number | undefined;
@@ -39,7 +39,7 @@ export class InMemoryEventStreamStore<T extends object> {
const stream = this.getLiveStream(streamId) ?? { events: [] };
this.streams.set(streamId, stream);
- const sequenceNumber = stream.events.length;
+ const sequenceNumber = stream.events.length + 1;
// Deep-copy so the log is isolated from caller mutations (mirrors JSON round-trip in Redis).
stream.events.push({ ...structuredClone(event), sequence_number: sequenceNumber });
@@ -134,7 +134,9 @@ export class InMemoryEventSubscription<T extends object> implements EventSubscri
options?: EventSubscriptionPollOptions,
): AsyncGenerator<SequencedEvent<T>, void, unknown> {
const signal = options?.signal;
- let cursor = afterSequenceNumber === undefined ? 0 : afterSequenceNumber + 1;
+ // 0 and omitted both mean "from the start". With 1-indexed sequences stored at
+ // index seq-1, "strictly after N" starts at array index N.
+ let cursor = afterSequenceNumber === undefined || afterSequenceNumber === 0 ? 0 : afterSequenceNumber;
for (;;) {
if (signal?.aborted) {
return;
@@ -143,8 +145,8 @@ export class InMemoryEventSubscription<T extends object> implements EventSubscri
if (!live) {
throw new StreamGoneError(this.streamId);
}
- const batch = live.events.slice(cursor);
- if (batch.length === 0) {
+ const end = live.events.length;
+ if (cursor >= end) {
try {
await this.store.waitForChange(this.streamId, signal);
} catch (error) {
@@ -155,10 +157,15 @@ export class InMemoryEventSubscription<T extends object> implements EventSubscri
}
continue;
}
- cursor += batch.length;
// Deep-copy each yielded event so consumers cannot mutate the stored log.
- for (const stored of batch) {
- yield structuredClone(stored);
+ // Snapshot `end` so appends during yield are left for the next pass.
+ while (cursor < end) {
+ const event = live.events[cursor];
+ if (event === undefined) {
+ throw new Error(`Corrupt stream ${this.streamId}: missing event at index ${String(cursor)}`);
+ }
+ cursor += 1;
+ yield structuredClone(event);
}
}
}
diff --git a/packages/server/src/runtime/event-subscription/index.ts b/packages/server/src/runtime/event-subscription/index.ts
index 9b0a3e161..0485b4730 100644
--- a/packages/server/src/runtime/event-subscription/index.ts
+++ b/packages/server/src/runtime/event-subscription/index.ts
@@ -29,7 +29,10 @@ export interface EventSubscription<T extends object> {
*/
assertSubscribable(): Promise<void>;
- /** Yields events strictly after the supplied sequence, or from the start when omitted. */
+ /**
+ * Yields events strictly after the supplied sequence number.
+ * Sequences are 1-indexed; omit or pass 0 to start from the first event.
+ */
poll(
afterSequenceNumber?: number,
options?: EventSubscriptionPollOptions,
diff --git a/packages/server/src/runtime/event-subscription/redis.ts b/packages/server/src/runtime/event-subscription/redis.ts
index bd2b88bc6..54b2bb8ff 100644
--- a/packages/server/src/runtime/event-subscription/redis.ts
+++ b/packages/server/src/runtime/event-subscription/redis.ts
@@ -24,11 +24,11 @@ function sequenceNumberFromEntryId(streamId: string, entryId: string): number {
}
/**
- * One Redis Stream with locally minted sequence numbers. Assumes a single
- * producer per stream; the counter dies with the instance, the data via key TTL.
+ * One Redis Stream with locally minted 1-indexed sequence numbers. Assumes a
+ * single producer per stream; the counter dies with the instance, the data via key TTL.
*/
export class RedisEventSubscription<T extends object> implements EventSubscription<T> {
- private nextSequenceNumber = 0;
+ private nextSequenceNumber = 1;
constructor(
private readonly redis: RedisClientType,
@@ -67,7 +67,11 @@ export class RedisEventSubscription<T extends object> implements EventSubscripti
options?: EventSubscriptionPollOptions,
): AsyncGenerator<SequencedEvent<T>, void, unknown> {
const signal = options?.signal;
- let cursor = afterSequenceNumber === undefined ? '0-0' : `${String(afterSequenceNumber + 1)}-0`;
+ // 0 and omitted both mean "from the start" (sequences are 1-indexed).
+ // Entries are `${seq}-1`. XREAD returns IDs greater than `id`, so
+ // `${N+1}-0` is an exclusive lower bound just below the next entry.
+ let cursor =
+ afterSequenceNumber === undefined || afterSequenceNumber === 0 ? '1-0' : `${String(afterSequenceNumber + 1)}-0`;
for (;;) {
if (signal?.aborted) {
return;
diff --git a/packages/server/src/schemas/turn.ts b/packages/server/src/schemas/turn.ts
index 53c8a9ca2..bf0a59294 100644
--- a/packages/server/src/schemas/turn.ts
+++ b/packages/server/src/schemas/turn.ts
@@ -7,7 +7,12 @@ export type { Turn } from '@truefoundry/utils/agent-session';
export const SubscribeTurnQuerySchema = z
.object({
- after_sequence_number: z.number().int().nonnegative().optional(),
+ // Query strings need coerce; map null/'' to undefined first so Number(null)→0
+ // cannot silently become a resume cursor (and so OpenAPI does not advertise null).
+ after_sequence_number: z.preprocess(
+ val => (val === null || val === '' ? undefined : val),
+ z.coerce.number().int().nonnegative().optional(),
+ ),
})
.openapi('SubscribeTurnQuery');
diff --git a/packages/server/tests/runtime/event-subscription/contractSuite.ts b/packages/server/tests/runtime/event-subscription/contractSuite.ts
index 9bb5e82e0..6960f7924 100644
--- a/packages/server/tests/runtime/event-subscription/contractSuite.ts
+++ b/packages/server/tests/runtime/event-subscription/contractSuite.ts
@@ -45,7 +45,7 @@ async function collect(
/** EventSubscription contract suite — factory-injected so both backends run it. */
export function runEventSubscriptionContractSuite(createRegistry: () => EventSubscriptionRegistry<TestEvent>) {
- it('put assigns dense sequence numbers starting at 0', async () => {
+ it('put assigns dense 1-indexed sequence numbers', async () => {
const registry = createRegistry();
const streamId = nextStreamId();
const producer = registry.get(streamId);
@@ -54,7 +54,7 @@ export function runEventSubscriptionContractSuite(createRegistry: () => EventSub
for (let i = 0; i < 3; i += 1) {
sequenceNumbers.push(await producer.put(makeEvent(i), { streamTTLSeconds: STREAM_TTL_SECONDS }));
}
- expect(sequenceNumbers).toEqual([0, 1, 2]);
+ expect(sequenceNumbers).toEqual([1, 2, 3]);
});
it('poll from the start yields every event sent, in order, with identical payloads', async () => {
@@ -68,7 +68,23 @@ export function runEventSubscriptionContractSuite(createRegistry: () => EventSub
}
const received = await collect(registry, streamId, sent.length);
- expect(received).toEqual(sent.map((event, index) => ({ ...event, sequence_number: index })));
+ expect(received).toEqual(sent.map((event, index) => ({ ...event, sequence_number: index + 1 })));
+ });
+
+ it('poll with afterSequenceNumber 0 matches an omitted cursor (from the start)', async () => {
+ const registry = createRegistry();
+ const streamId = nextStreamId();
+ const producer = registry.get(streamId);
+
+ const sent = [makeEvent(0), makeEvent(1), makeEvent(2)];
+ for (const event of sent) {
+ await producer.put(event, { streamTTLSeconds: STREAM_TTL_SECONDS });
+ }
+
+ const fromOmitted = await collect(registry, streamId, sent.length);
+ const fromZero = await collect(registry, streamId, sent.length, 0);
+ expect(fromZero).toEqual(fromOmitted);
+ expect(fromZero[0]?.sequence_number).toBe(1);
});
it('poll from a mid-stream cursor yields only events strictly after it', async () => {
@@ -81,11 +97,12 @@ export function runEventSubscriptionContractSuite(createRegistry: () => EventSub
await producer.put(event, { streamTTLSeconds: STREAM_TTL_SECONDS });
}
+ // after 1 → skip seq 1; replay seq 2, 3, 4
const received = await collect(registry, streamId, 3, 1);
expect(received).toEqual([
- { ...sent[2], sequence_number: 2 },
- { ...sent[3], sequence_number: 3 },
- { ...sent[4], sequence_number: 4 },
+ { ...sent[1], sequence_number: 2 },
+ { ...sent[2], sequence_number: 3 },
+ { ...sent[3], sequence_number: 4 },
]);
});
@@ -96,15 +113,15 @@ export function runEventSubscriptionContractSuite(createRegistry: () => EventSub
await producer.put(makeEvent(0), { streamTTLSeconds: STREAM_TTL_SECONDS });
- // Cursor at the tip: nothing to replay, so the poller parks for live events.
- const pending = collect(registry, streamId, 2, 0);
+ // after 1 (= tip): nothing to replay, so the poller parks for live events.
+ const pending = collect(registry, streamId, 2, 1);
await producer.put(makeEvent(1));
await producer.put(makeEvent(2));
const received = await pending;
expect(received).toEqual([
- { ...makeEvent(1), sequence_number: 1 },
- { ...makeEvent(2), sequence_number: 2 },
+ { ...makeEvent(1), sequence_number: 2 },
+ { ...makeEvent(2), sequence_number: 3 },
]);
});
}