Agent SDK · Tools and sessions

Stream resume.

Durable handles and resuming interrupted agent runs.

Durable streaming lets a client disconnect mid-stream and resume from where it left off. The server buffers events, keyed by a streamId advertised at stream start.

`resumeAgentStream(streamId, lastEventId, handlers, options?)`

Resumes a previously detached stream by replaying buffered events from lastEventId. Returns the accumulated AgentRunResult.

TypeScript

import { resumeAgentStream, type AgentRunEvent } from '@maincode-ai/matilda-agent-sdk';

const result = await resumeAgentStream(
  savedStreamId,
  savedLastEventId,
  {
    onEvent: (event: AgentRunEvent) => {
      if (event.type === 'message.delta') process.stdout.write(event.delta);
    },
  },
);
console.log('Resumed output:', result.finalOutput);

Parameters

Field	type	description
streamId	string	The stream ID from stream.started event (or result.streamId).
lastEventId	string \| undefined	The last cursor received (from cursor event or result.lastEventId). Omit to replay from the start.
handlers	{ onEvent?: (event: AgentRunEvent) => void }	Event handler callback.
options	RequestOptions & { signal?: AbortSignal; core?: MatildaCore }	Request options.

Returns Promise<AgentRunResult>.

401 auto-refresh

If the resume request returns 401 and the core has a getToken provider, the SDK automatically refreshes the token and retries once.

Full resume example

TypeScript

import { stream, resumeAgentStream } from '@maincode-ai/matilda-agent-sdk';

let streamId: string | undefined;
let lastEventId: string | undefined;
let receivedText = '';

// Start streaming — capture IDs for potential resume
for await (const event of stream({ name: 'resumable-agent' }, 'Tell me a fact.')) {
  if (event.type === 'stream.started') streamId = event.streamId;
  if (event.type === 'cursor') lastEventId = event.lastEventId;
  if (event.type === 'message.delta') {
    receivedText += event.delta;
    process.stdout.write(event.delta);
  }
}

console.log('\n[Stream completed — streamId:', streamId, 'cursor:', lastEventId, ']');

// Later — resume from the last cursor if the stream was interrupted
if (streamId) {
  const result = await resumeAgentStream(streamId, lastEventId, {
    onEvent: (event) => {
      if (event.type === 'message.delta') process.stdout.write(event.delta);
    },
  });
  console.log('\n[Resumed — output:', result.finalOutput.slice(0, 60), '...]');
}