الجلسات

import { createAgent } from '@lousho/build-ai-agent';

const chat = createAgent({ instructions: 'Be brief.', provider });

const session = chat.session(); // in memory, new generated id
await session.send('My name is Ali.');
const { text } = await session.send('What is my name?'); // sees the first exchange

console.log(session.id, session.messages.length);

​

كائن الجلسة

• 'wait' (الافتراضي): ينتظر ثم يُنفَّذ دورةً مستقلة، كما سبق.
• 'queue': ينضم مُدخَله إلى تلك الدورة، مثل run.enqueue(): يُضاف بعد نتائج أدوات الخطوة الحالية، فيراه استدعاء النموذج التالي في الدورة. يُنجَز الاستدعاء بنتيجة تلك الدورة (وsignal الخاص به لا يسري على الدورة)، وسجل المحادثة المحفوظ عند انتهاء الدورة يحوي رسالة المستخدم المضافة إلى الطابور في ترتيبها. وstream() المنضم لا يُخرج إلا run.done الخاص بالدورة؛ أما أحداث الدورة، ومنها input.queued وinput.applied، فتُبث على التشغيل الذي بدأها. وإذا انتهت الدورة قبل أن تأخذ المُدخَل (اكتملت، أو توقفت مؤقتًا، أو أُلغيت)، نُفِّذ الاستدعاء دورةً تالية في نهاية المطاف. وإذا فشلت الدورة رُفض الاستدعاء بالخطأ نفسه؛ وفي الجلسة المتينة يبقى المُدخَل في نقطة حفظ الدورة ويطبّقه resume().
• 'steer': مثل 'queue'، لكن المُدخَل ينضم عبر run.steer(): إذا لم يكن استدعاء النموذج في الدورة قد أصدر شيئًا بعد، أُلغي وأُعيد بالرسالة الجديدة، ولا تُنفَّذ استدعاءات الأدوات التي لم تبدأ في الدورة. وإلا انتظر النقطة الآمنة التالية، كما في 'queue'. يُنجَز الاستدعاء بنتيجة الدورة، وتسري البدائل نفسها.

import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const session = agent.session({ id: 'user-42', turnPolicy: 'queue' });

const first = session.send('Find flights to Rome.');
const second = session.send('Only direct ones, please.'); // joins the first turn
console.log((await second) === (await first)); // true: one turn, one result

​

بث دورة في جلسة

import { createAgent } from '@lousho/build-ai-agent';

const chat = createAgent({ instructions: 'Be brief.', provider });
const session = chat.session();

for await (const event of session.stream('My name is Ali.')) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
// The turn is already saved: this call sees it.
const { text } = await session.send('What is my name?');

• يبني قائمة الرسائل نفسها التي يبنيها send()، ويصطف خلف الاستدعاءات السابقة على الجلسة (يمكن الجمع بين send() وstream()).
• حين ينتهي التشغيل، تُحفظ رسالة المستخدم الجديدة ومخرجات التشغيل تمامًا كما يحفظها send()، وبعد ذلك فقط يُسلَّم run.done. فحين تنتهي حلقة for await، أو يُنجَز run.result، يكون سجل المحادثة مكتملًا. وتحمل الأحداث runId الخاص بالمقبض المُرجَع.
• التشغيل المُلغى (عبر signal، أو بالخروج من الحلقة مبكرًا) أو الفاشل يترك سجل المحادثة كما كان قبل الاستدعاء، مثل send(). والتشغيل الذي كان قد انتهى فعلًا عند مغادرة الحلقة يُحفظ. والتشغيل الفاشل يُنهي البث بـ error ثم run.done (finishReason: 'error')، ويُرفض run.result. ويشمل ذلك مخزنًا يفشل في التحميل أو الحفظ: وعندها لا يكون للدورة run.start.
• التشغيل الذي يتوقف مؤقتًا عند أداة needsApproval ينتهي بـ approval.requested ثم run.done ('awaiting-approval')، تمامًا كما يُنجَز send()، ويحوي سجل المحادثة الدورة حتى موضع التوقف. وagent.approvals.resolve() يتابعه بوصفه الدورة التالية في الجلسة. ودالة approve لا تسري على البث، كما في agent.stream().

​

الجلسات المتينة

import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const agent = createAgent({ provider, store: new SqliteStore('./.lousho/agent.db') });

// After a restart: finish the turn that was running, if any.
const finished = await agent.resume('user-42'); // ExecutionResult, or null when nothing was pending
console.log(finished?.text, await agent.session({ id: 'user-42' }).pending()); // pending() is null now

• createAgent({ store }) يقبل أي AgentStore ({ sessions?, checkpoints?, approvals? }، انظر اختيار المخزن): agent.session({ id }) يحفظ سجل محادثته في store.sessions ونقاط حفظه في store.checkpoints، ويحفظ store.approvals توقفات الموافقة. وstore الخاص بالجلسة (وهو SessionStore، أو كائن { sessions, checkpoints }) وcheckpointStore يغلبان مخزن الوكيل، جزءًا جزءًا.
• agent.resume(id) هو agent.session({ id }).resume()، إلا أنه يُنهي أولًا تشغيلًا بدأ بـ agent.send(message, { sessionId: id }) (انظر التنفيذ المتين).
• كل دورة تُنفَّذ بـ sessionId: '<session id>.turn-<n>' (وn هو طول سجل المحادثة لحظة بدء الدورة)، فتجد العملية الجديدة الدورة المنقطعة دون أي تتبّع إضافي. والدورة المنتهية تنضم إلى سجل المحادثة، تمامًا كما في send() العادي، وتُحذف نقطة حفظها.
• resume() يتابع الدورة عبر مسار الاستئناف في المنفّذ (input: []): استدعاءات الأدوات التي سُجّلت نتائجها لا تُنفَّذ من جديد، واستجابة النموذج المسجّلة لا تُطلب من جديد. أما الأداة التي كانت قيد التنفيذ حين ماتت العملية فتُنفَّذ من جديد (مرة واحدة على الأقل، انظر التنفيذ المتين).
• send() وstream() يستأنفان الدورة المعلّقة أولًا، ثم يرسلان الرسالة الجديدة، فيرى النموذج الدورة بعد إتمامها (وأحداث الدورة المستأنفة لا تُبث). استخدم pending() للتحقق أولًا، أو discardPending() للتخلي عن الدورة غير المنتهية.
• الدورة التي تتوقف مؤقتًا عند أداة needsApproval تبقى في نقطة حفظها، لا في سجل المحادثة، إلى أن تنتهي. وما دامت تنتظر، يرمي resume() وsend() وstream() الخطأ SessionAwaitingApprovalError (ومعه approvalId)، ويتابع agent.approvals.resolve({ id, approved }) الدورة في هذه الجلسة. بعد إعادة التشغيل، افتح الجلسة واستدعِ resume() (أو send()) مرة واحدة قبل البتّ، ليعرف الوكيل إلى أي جلسة تنتمي الموافقة؛ وأعطِ الوكيلين كليهما store الدائم نفسه (أو approvalStore).
• الدورة المُلغاة يُتخلى عنها (وتُحذف نقطة حفظها)، كما هو الحال من دون مخزن نقاط حفظ. وclear() يحذف الدورة المعلّقة أيضًا.

​

المخازن

import type { Message } from '@lousho/build-ai-agent';

interface SessionStore {
  load(id: string): Promise<Message[] | undefined>;
  save(id: string, messages: readonly Message[]): Promise<void>;
  delete(id: string): Promise<void>;
}

• MemorySessionStore (الافتراضي، مخزن جديد لكل جلسة) يعيش ما عاشت العملية. شارك نسخة واحدة بين الجلسات لتجدها بمعرّفاتها.
• FileSessionStore(dir) يكتب ملف JSON واحدًا لكل جلسة (<dir>/<id>.json)، كتابةً ذرّية (ملف مؤقت ثم إعادة تسمية)، وينشئ dir عند أول حفظ.

import { createAgent, FileSessionStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider });
const store = new FileSessionStore('./.lousho/sessions');

const first = agent.session({ id: 'user-42', store });
await first.send('My name is Ali.');

// Later, even in another process or another createAgent() instance:
const again = agent.session({ id: 'user-42', store });
await again.send('What is my name?'); // "Ali"

​

اختيار المخزن

import {
  createAgent,
  FileSessionStore,
  LocalStorageCheckpointStore,
  StorageServiceApprovalStore,
  type AgentStore,
} from '@lousho/build-ai-agent';

// `storage` is a StorageService rooted where the files should go.
const store: AgentStore = {
  sessions: new FileSessionStore('./.lousho/sessions'),
  checkpoints: new LocalStorageCheckpointStore(storage),
  approvals: new StorageServiceApprovalStore(storage),
};
const agent = createAgent({ provider, store });

import { createAgent, AgentExecutor } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
const agent = createAgent({ provider, store }); // transcripts, per-step checkpoints and approvals
await agent.session({ id: 'user-42' }).send('Hello');

// With AgentExecutor directly, pass the parts:
// AgentExecutor.execute({ ..., sessionId, checkpointStore: store.checkpoints, approvalStore: store.approvals })

store.prune({ olderThanMs: 7 * 24 * 60 * 60 * 1000 }); // { sessions, checkpoints, approvals } deleted
store.close();

• يُنشأ المجلد إن لم يكن موجودًا. والمخطط مُرقَّم الإصدار عبر PRAGMA user_version ويُرحَّل عند الفتح؛ وقاعدة البيانات التي كتبها إصدار أحدث تُرفض.
• وضع WAL ومهلة انشغال (busy timeout) مدتها 5 ثوانٍ يتيحان لعمليتين تشارك الملف. ولا يبتّ في الموافقة إلا واحدة منهما.
• نقاط الحفظ ولقطات الموافقة تُخزَّن JSON معتمًا لا يُفسَّر محتواه، فالحقول الجديدة تُكتب وتُقرأ دون تغيير.
• prune() يزيل الجلسات ونقاط الحفظ التي لم تُحدَّث خلال olderThanMs، والموافقات التي بُتّ فيها قبل تلك المدة؛ أما الموافقات التي لم يُبتّ فيها فتبقى.
• الملف الذي ليس قاعدة بيانات SQLite يفشل بخطأ يذكر المسار؛ واستخدام المخزن بعد close() يرمي خطأً واضحًا.

​

تعليمات المشروع