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.mdindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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 EventSubscrioptions?: 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 EventSubscriif (!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.tsindex 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.tsindex 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 EventSubscriptioptions?: 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.tsindex 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.tsindex 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: () => EventSubfor (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: () => EventSubawait producer.put(event, { streamTTLSeconds: STREAM_TTL_SECONDS });}+ // after 1 → skip seq 1; replay seq 2, 3, 4const 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: () => EventSubawait 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 },]);});}