Interface: IThreadStore
Defined in: internal/thread-store/types.ts:33
Tenant-scoped storage of threads and turns.
Implemented by ThreadStore; the type of IAIGatewayDeps.threadStore, so a host may pass its own in overrides.
Methods
acquireLease()
acquireLease(
args):Promise<string>
Defined in: internal/thread-store/types.ts:70
acquireLease -- marks the thread busy for one call
About
One call at a time on a thread.
Takes the thread's lease (D77) for leaseMs and returns the token that releases it. A thread whose lease is held and not
expired is a 409: the caller tells the user the thread is busy and does not store anything.
AIGateway calls it before a call on an existing thread stores its user turn, and releaseLease in a finally.
Pitfalls
The lease expires by itself: a call longer than leaseMs runs unprotected at its end. Size leaseMs for the longest run.
Parameters
args
tenantId
string
threadId
string
Returns
Promise<string>
anonymizeByUser()
anonymizeByUser(
args):Promise<IThreadCounts>
Defined in: internal/thread-store/types.ts:305
anonymizeByUser -- keeps a user's threads as skeletons under a pseudonym (D54)
About
What identifies the person goes, what counts stays.
userId becomes the pseudonym, the title and the working memory are emptied, the status becomes CLOSED, the turns are
deleted; id, turnCount and the dates stay for the statistics. Returns how many threads and turns were touched.
Who needs it
forgetUser, in the ANONYMIZE mode (AIGateway.anonymizeUserData).
Parameters
args
pseudonym
string
tenantId
string
userId
string
Returns
Promise<IThreadCounts>
appendTurn()
appendTurn(
args):Promise<void>
Defined in: internal/thread-store/types.ts:148
appendTurn -- stores one turn at the end of a thread
About
The turn, then the thread's
turnCountandupdatedAt.
Two repository writes, in that order. The turns of one answer are appended one after the other by appendTurns, so the
repository's order is the order of the conversation.
Who needs it
appendTurns, the one writer of turns in the gateway.
Parameters
args
tenantId
string
threadId
string
turn
Returns
Promise<void>
createThread()
createThread(
args):Promise<IThread>
Defined in: internal/thread-store/types.ts:47
createThread -- a new, empty conversation of a user
About
OPEN, no turns, no memory, no lease; the id is the gateway's.
Saves the thread and returns a copy. The title stays empty unless given.
Who needs it
prepareCall, for a call without a threadId (step 3).
Parameters
args
tenantId
string
title?
string
Optional; WorkingMemory/THREAD_TITLE can fill it later.
userId
string
Returns
Promise<IThread>
delete()
delete(
args):Promise<IThreadCounts>
Defined in: internal/thread-store/types.ts:285
delete -- hard-deletes threads with their turns and working memory (D119)
About
The listed ids, or every thread of the tenant for
"all", narrowed to one user whenuserIdis given.
An unknown id, or one of another tenant or user, is ignored. Returns how many threads and turns went. The runs, the
trace entries and the files of the threads are the callers' business (deleteThreads).
Who needs it
deleteThreads (the facade's delete) and forgetUser (the DELETE mode, D54).
Parameters
args
tenantId
string
threadIds
userId?
string
Returns
Promise<IThreadCounts>
findThread()
findThread(
args):Promise<IThread|null>
Defined in: internal/thread-store/types.ts:248
findThread -- one thread of a tenant, or null
About
getThreadwithout the 404, for a caller that asks "is it there".
Null for a thread that is missing, deleted or of another tenant.
Who needs it
forgetUser and deleteThreads, to read the lease of each thread before they write.
Parameters
args
tenantId
string
threadId
string
Returns
Promise<IThread | null>
getLastTurns()
getLastTurns(
args):Promise<ITurn[]>
Defined in: internal/thread-store/types.ts:168
getLastTurns -- the newest turns of a thread, oldest first
About
The model's window on the conversation.
Reads the newest limit turns and returns them in chronological order. The WorkingMemory reads the window of a call
with it (D122); closeRun the turns a run could have stored; updateMemory the turns since the last fact extraction.
Who needs it
WorkingMemory, closeRun, updateMemory, deleteThreads.
Parameters
args
limit
number
tenantId
string
threadId
string
Returns
Promise<ITurn[]>
getThread()
getThread(
args):Promise<IThread>
Defined in: internal/thread-store/types.ts:106
getThread -- one thread of a tenant, or a 404
About
The read every other method starts with.
A thread that is missing, deleted (deletedAt set) or of another tenant is the same 404 (5372567786151); findThread
is the twin that returns null instead. The ownership by the user is not checked here: that is getOwnThread (D32).
Who needs it
getOwnThread, prepareCall (read again under the lease, for the status), closeRun, updateMemory, WorkingMemory,
AIGateway.continueRun and continueReview (the turn count before a step).
Parameters
args
tenantId
string
threadId
string
Returns
Promise<IThread>
getTurns()
getTurns(
args):Promise<ITurn[]>
Defined in: internal/thread-store/types.ts:190
getTurns -- the whole history of a thread for a chat screen
About
Every turn of the thread, oldest first, in one read.
A thread's history is loaded whole, as the Vercel chat client loads a chat (D37): no paging. getLastTurns is the model's
window on the same turns; this one is the screen's.
AIGateway.getTurns calls it after it checked that the thread is the caller's.
Pitfalls
A conversation of thousands of turns is one large read and one large payload.
Parameters
args
tenantId
string
threadId
string
Returns
Promise<ITurn[]>
listThreadIds()
listThreadIds(
args):Promise<string[]>
Defined in: internal/thread-store/types.ts:266
listThreadIds -- the ids of a tenant's threads, or of one user's
About
Every live thread, by id only, for the bulk operations.
Deleted threads are excluded. No paging: the bulk operations (D119, D54) walk the whole list.
Who needs it
forgetUser and deleteThreads, to find the threads whose lease they must check.
Parameters
args
tenantId
string
userId?
string
Returns
Promise<string[]>
listThreads()
Defined in: internal/thread-store/types.ts:128
listThreads -- one page of a user's threads for the sidebar of a chat screen
About
The conversations of one user, newest first, paged by cursor.
Pages as the Vercel chat client does (D37): the first read passes both cursors null and gets the newest limit threads;
endingBefore a thread id reads the older ones (the next page), startingAfter the newer ones. Deleted threads are left out.
AIGateway.listThreads calls it with the tenant and user of the call.
Pitfalls
limit outside 1–200 or both cursors at once is a 400; a cursor that is not a thread of this user is the repository's 404.
The order is by createdAt: a thread used again keeps its place, it does not move to the top.
Parameters
args
page
tenantId
string
userId
string
Returns
releaseLease()
releaseLease(
args):Promise<void>
Defined in: internal/thread-store/types.ts:85
releaseLease -- frees the thread after a call
About
Gives back what
acquireLeasegave out.
Clears the lease that carries token. A lease another call took after this one expired stays: the late release of a
call that overran never frees a thread someone else holds.
Parameters
args
tenantId
string
threadId
string
token
string
Returns
Promise<void>
setWorkingMemory()
setWorkingMemory(
args):Promise<void>
Defined in: internal/thread-store/types.ts:229
setWorkingMemory -- stores the working memory of a thread
About
The WorkingMemory's write; the thread's
updatedAtstays, memory is not activity of the user.
Replaces the state whole (a copy of it).
Who needs it
WorkingMemory only: its saveContext and reset.
Parameters
args
state
tenantId
string
threadId
string
Returns
Promise<void>
updateThread()
updateThread(
args):Promise<void>
Defined in: internal/thread-store/types.ts:209
updateThread -- changes the title or the status of a thread
About
What is omitted stays;
updatedAtmoves.
The status is the gateway's: AWAITING_HUMAN when a run pauses, OPEN again when it settles or closes. The title is the
user's (AIGateway.renameThread).
Who needs it
settleRun, settleReviewPause, settleReview, closeRun (the status); AIGateway.renameThread (the title).
Parameters
args
status?
tenantId
string
threadId
string
title?
string
Returns
Promise<void>