lousho build ملف spec للـagent (راجع الإعداد) ويُخرج منه artifact جاهزًا للنشر على منصة واحدة:
--out (الافتراضي .lousho/build/<target>)، وbuild يُنشئ bundle باستخدام tsup، وdescribe يطبع الأمر الذي يشغّل الناتج أو ينشره. يجب أن يكون tsup مثبّتًا (npm install --save-dev tsup).
يرد كل target على
GET /health (200 ok) ويقدّم HTTP API الكامل تحته: sessions، وSSE streaming، وapprovals، وbearer auth.
لشرح عملي على VPS حقيقي — فحص الخادم، البناء، النقل، التشغيل، التحقق — راجع النشر على Hostinger VPS.
مجلدات الـagent
تقبل الأهداف الثلاثة أيضًا مجلد agent بدلًا من ملف spec (يُمرَّر المسار كوسيط موضعي (positional) أو عبر--agent):
server.ts المولَّد resolveAgentDir() على dist/agent ثم createDeployedServer(agent, { schedules, channels }). أي أن العملية تشغّل schedules الخاصة بالمجلد عندما تبدأ الاستماع، وتركّب channels تحت /channels — تتحقق الـchannels من طلباتها بنفسها، وتبقى مسارات المحادثة محمية بالـbearer token — وتطبع في السجل schedules: ...; channels: ....
تُحزَم ملفات الكود في المجلد مسبقًا في خطوة tsup وتُخرَج في dist/agent/**.js. البناء ESM واحد يشارك نسخة واحدة من الـSDK، فإذا احتوت tool على from 'lousho' فهي تشير إلى نفس الـSDK الذي يعمل عليه الخادم. ولا يُنسخ من المجلد إلا الملفات التي يقرؤها الخادم كبيانات: instructions.md وinstructions/ وskills/ وconfig بصيغة JSON/YAML، وكذلك نظيراتها في كل subagents/<name>/. ولا يصل أي شيء آخر من المجلد إلى dist/: لا ملفات .env، ولا الـsession store في .lousho/ أو في store.dir الخاص بالـconfig، ولا الملاحظات أو ملفات البيانات. ويُفرَّغ dist/ قبل كل build، لذا لا تنتقل الـsessions التي كتبها خادم build سابق تحته إلى الجديد. لا شيء يحتاج TypeScript loader وقت التشغيل. يكون dist/ بصيغة ESM (يصرّح dist/package.json بذلك). وتنسخه صورة Docker كما في السابق. لا يُحزَم الـsandbox الاختياري dockerode (يُحمَّل عند الحاجة lazily)، لذا يجب على المجلد الذي يستخدم SubprocessSandbox أن يثبّته حيثما يعمل.
يبني هدف Cloudflare Worker كلًّا من config المجلد وinstructions.md وtools/ وskills/ وsubagents/ وschedules/ (كـcron triggers خاصة بالـWorker) وchannels/ وmemory/ وprojectInstructions؛ ويرفض أي model لا يتوفر الـprovider الخاص به في الـWorker، وبقية الميزات التي لا يشملها عمود الـWorker في ما يعمل وما لا يعمل — ويذكر لك بالاسم ما يجب أن تزيله. تعمل الـtools داخل الـWorker بصلاحياته، ولا يُسمح لها إلا باستيراد الجزء الآمن للـWorker من lousho (التفاصيل في Cloudflare Workers):
وحدات الـagent
يبني هدفاnode-server وdocker أيضًا module بصيغة .ts/.js يكون الـexport الافتراضي له (أو الـexport المسمّى agent) عبارة عن options لـcreateAgent() أو agent مبنيًّا: وهو نفس الملف الذي يقدّمه lousho dev src/agent.ts، والموجود في scaffolds الـminimal والـtools (ويشغّل npm run build الخاص بها هذا الأمر):
server.ts المولَّد الـmodule، فيحزمه tsup مع استيراداته المحلية والـSDK في dist/server.js بصيغة ESM. إذا كان الـexport عبارة عن options، يبني الخادم الـagent باستخدام LOUSHO_STORE (ما لم تحدد الـoptions قيمة store)؛ أما الـagent المُصدَّر فيحتفظ بالـstore الخاص به. يذكر package.json الخاص بالـbuild حزمة الـprovider إذا احتوى الـmodule على model: '<provider>/...' حرفيًا أو سمّى class provider من الـSDK (new OpenRouterProvider(...))؛ ولا يُفحص إلا ملف الدخول، ويطبع الـbuild تحذيرًا (warning) إذا لم يجد provider. أي peer اختياري آخر تحتاجه أضِفه أنت إلى dependencies. لا يبني هدف cloudflare-worker الـmodule: استخدم spec أو مجلد agent.
HTTP API
يقدّم كل target نفس بروتوكول/chat الذي يقدّمه lousho dev (راجع CLI)، ومن نفس الكود: src/server/fetchRoutes.ts مبني على Fetch مباشرة، ويستدعيه كلٌّ من خادم Node والـWorker. أي أن الصفحة أو السكربت المكتوب للعمل مع dev server يعمل مع الخادم المنشور.
يحصل البودي الأكبر من 1MB على
413، ويحصل الـJSON غير الصالح على 400. يجب أن يرسل أي POST الترويسة Content-Type: application/json (أي قيمة أخرى تحصل على 415، LOUSHO_UNSUPPORTED_MEDIA_TYPE)، ويحصل POST من متصفح على origin آخر على 403 (LOUSHO_REQUEST_FORBIDDEN): راجع الطلبات بين المواقع. يحصل input الفارغ، أو البودي الذي لا يحتوي على sessionId وinput، على 400 (LOUSHO_REQUEST_INVALID؛ ويحصل session id غير الصالح على LOUSHO_SESSION_ID_INVALID). كل بودي خطأ هو JSON بالشكل { error, code }. الـturn المُرسَل إلى session متوقفة بانتظار approval يحصل على 409 مع code: 'LOUSHO_SESSION_AWAITING_APPROVAL' وapprovalId وapprovalIds (كل الـapprovals التي لا يزال يجب حسمها): احسمها عبر route الـapprovals، الذي يبث تكملة الـturn المتوقف، ثم أرسل الـturn الجديد. الـturn المُرسَل إلى session تشغّل فيها عملية أخرى أو replica أخرى turn (وتمسك الـrun lease الخاص بالـsession) يحصل على 409 مع code: 'LOUSHO_SESSION_BUSY' وheader Retry-After: 2، ويصل الرد قبل أن يبدأ أي stream؛ أعد الإرسال بعد الانتظار. مع قائمة auth، تصبح الـsession ملكًا لأول principal يرسل إليها turn، والـsession المخزنة التي لم يعد الخادم يتذكر صاحبها (بعد restart) تُرفض للجميع إلى أن يحدد authorizeSession لمن تعود؛ ومع LOUSHO_API_TOKEN وحده يوجد caller واحد ولا يوجد فحص ملكية (من يستطيع استخدام الـsession). لا يحسم الـapproval إلا الـcaller الذي يعمل الـrun باسمه، ما لم يقرر authorizeApproval غير ذلك. في مجلد agent، صدّر authorizeSession وauthorizeApproval من auth.ts لكي تغيّر أيًّا من القاعدتين (مثلًا لكي تسمح لمدير بحسم approvals مستخدمين آخرين): راجع من يستطيع حسم الـapproval.
أثناء بث الـturn، يكتب الخادم سطر تعليق SSE (: ping) بعد كل 15 ثانية تمر بدون event، لكي يحافظ الـproxy (يغلق nginx الـupstream الخامل بعد 60 ثانية) أو الـclient (يستسلم fetch الخاص بـNode بعد 300 ثانية بدون أي byte) على الاتصال عندما يكون الـmodel أو الـtool بطيئًا. تتجاهل الـSSE parsers سطور التعليق. يغيّر createRouteHandler(agent, { heartbeatMs }) الفترة، وتوقفها القيمة 0.
إعادة إرسال turn
إذا أرسل الـclient الطلبPOST /chat مرة أخرى (إعادة محاولة بعد انقطاع اتصال أو timeout، أو نقرة مزدوجة، أو إعادة تشغيل الـclient)، فهو، بدون أي شيء إضافي، turn جديد: تُضاف رسالة المستخدم مرة أخرى وقد يستدعي الـmodel نفس الـtools مرة أخرى. أرسل header Idempotency-Key (من 1 إلى 255 حرف ASCII مرئي، مثلًا UUID يولّده الـclient لكل رسالة) وأعد الإرسال بنفس المفتاح:
ترد الـsession المتوقفة بانتظار approval بـ
409 (LOUSHO_SESSION_AWAITING_APPROVAL) على إعادة الإرسال كأي turn. يُخزَّن المفتاح مع الـturn في الـsession store (في الـtranscript، أو في checkpoint الـturn إلى أن ينتهي)، لذا يعمل الـreplay بعد restart وعلى replica أخرى تشارك نفس الـstore؛ ويُرجع session.pending() مفتاح الـturn المنقطع بوصفه idempotencyKey. لا يُبحث عن المفتاح إلا في الـsession الخاصة به، وفقط طالما بقي الـturn الخاص به موجودًا في الـtranscript (الـcompaction التي تلخّصه تنساه). وبين الـreplicas يعتمد الـ409 على الـrun lease الخاص بالـsession، لذا يحتاج store يدعم الـleases؛ فقد تشغّله replicaتان تستلمان نفس المفتاح في اللحظة نفسها على store لا يدعمها.
المصادقة
عيّنLOUSHO_API_TOKEN (في الـWorker كـsecret: npx wrangler secret put LOUSHO_API_TOKEN) وستطلب routes /chat وأي channel ليس لديه verify خاص به الترويسة Authorization: Bearer <token>؛ وأي طلب آخر يحصل على 401 مع خطأ JSON (يُقارَن التوكن في زمن ثابت constant time). /health مفتوح، ولا يخضع للتوكن الـchannels التي تصادق نفسها (دالة verify، أو فحص توقيع المنصة مثل الخاص بـSlack). بدون التوكن يكون الخادم مفتوحًا: وهذا مقبول على 127.0.0.1، لكن على أي interface آخر يرفض الـnode-server المبني (وبالتالي صورة docker، التي تستمع على 0.0.0.0) العمل بدون auth: ويخرج بالخطأ LOUSHO_SERVER_UNPROTECTED. عيّن LOUSHO_API_TOKEN، أو أضف auth.ts، أو اربطه على 127.0.0.1. وإذا أردت تقديم agent مفتوح على interface عام عن قصد (شبكة خاصة، أو auth في proxy أمامه)، عيّن LOUSHO_ALLOW_PUBLIC=1: عندها يعمل الخادم ويطبع تحذيرًا (warning) بدلًا من ذلك. أنهِ الـTLS (terminate) أمام الخادم، لأن الـbearer token ينتقل نصًا صريحًا فوق HTTP العادي. مرّر التوكن وقت التشغيل (docker run -e LOUSHO_API_TOKEN=...).
برمجيًا: يُدمج adapter.scaffold(agentPath, outDir, { auth: { token } }) توكنًا داخل خادم node-server أو docker المبني، يُستخدم عندما لا يكون المتغير معيّنًا. المتغير له الأولوية، والتوكن المدمج يمكن قراءته في dist/server.js، لذا التزم بالمتغير. يقرأ الـWorker التوكن من الـbinding LOUSHO_API_TOKEN الخاص به فقط؛ وبدونه يرفض كل routes /chat ما لم تكن قيمة الـvar LOUSHO_ALLOW_OPEN_SESSIONS هي "true" (Cloudflare Workers).
خلف proxy، أو لواجهة أمامية على origin آخر، يقرأ الـnode-server والـWorker المولَّدان فحوص الطلبات الخاصة بالـroutes من LOUSHO_ALLOWED_ORIGINS وLOUSHO_ALLOWED_HOSTS (مفصولة بفواصل) وLOUSHO_REQUIRE_JSON_BODY=false: راجع الطلبات بين المواقع.
لـJWT أو OpenID Connect أو Basic auth، ولمعرفة من يتحدث إلى الخادم، يأخذ هدفا node-server وdocker قائمة auth مرتبة من auth.ts في مجلد الـagent، ويُلحَق بها LOUSHO_API_TOKEN. راجع مصادقة الـroutes والهويات.
الـsessions والـstore
يحددLOUSHO_STORE أين تُحفظ الـsessions والـcheckpoints والـapprovals:
يمكن لأكثر من instance على host واحد أن تتشارك ملف
sqlite: واحدًا على قرص محلي (مثلًا replicaتان على Docker volume واحد)؛ وترد الـsession المشغولة بـ409 مع Retry-After. أما الـfilesystem الشبكي (NFS، EFS، SMB) أو تعدد الـhosts فغير مدعومَين: استخدم store تنفّذه أنت. راجع مشاركة ملف SQLite.
الاستعادة بعد الـcrash
عندما يبدأ خادمnode-server أو docker الاستماع، يُكمل الـruns التي تركها crash أو kill ناقصة في الـstore. يستدعي agent.recover()، الذي يستأنف كل run وكل turn في session حالته in-progress من آخر checkpoint له. لا تُعاد الخطوات التي انتهت. أما الـtool call الذي كان يعمل عندما توقفت العملية فيُشغَّل مرة أخرى، لذا اجعل هذه الـtools idempotent. يطبع الخادم lousho server: resuming N interrupted run(s) عندما يجد أيًّا منها، وسطر recovered interrupted run '<id>' لكل run يكمله. وبعد ذلك يفحص الـstore مرة أخرى كل 30 ثانية إلى أن يتوقف.
- تُترك الـruns المتوقفة بانتظار approval أو سؤال كما هي. احسمها عبر
POST /chat/:sessionId/approvals/:id. - الـrun الذي تمسك الـrun lease الخاص به عملية أخرى حية يُتخطّى ويُعاد في فحص لاحق. والأمر نفسه للـrun الذي لم ينتهِ بعد الـlease الخاص بعمليته التي تعرضت لـcrash.
- مع الـstore الافتراضي
memoryلا يوجد شيء يُستعاد بعد restart، ولا يجد الفحص شيئًا. - إعادة إرسال الـturn نفسه التي تصل بينما لا يزال الخادم يستأنفه تُشغَّل بعد الـturn المستأنف، كـturn جديد. أرسل
Idempotency-Key(إعادة إرسال turn) لكي تحصل على رد الـturn المستأنف بدلًا من ذلك.
LOUSHO_RECOVER_ON_START=0 لإيقاف ذلك، مثلًا عندما تكون عملية أخرى تشغّل أصلًا agent.recover() لنفس الـstore.
node-server
dist/server.js هو bundle واحد مكتفٍ بذاته (الـSDK واعتمادياته بداخله)، لذا يعمل بدون npm install:
lousho dev، يرتبط بـ127.0.0.1 ما لم تختر interface آخر بـ--host=<h> (أو HOST=<h>). يأتي الـport من --port أو PORT، وإلا فالافتراضي 3000. وعلى أي interface غير loopback يحتاج auth (LOUSHO_API_TOKEN أو auth.ts) أو LOUSHO_ALLOW_PUBLIC=1، وإلا يرفض العمل (المصادقة).
مع SIGINT أو SIGTERM (docker stop، أو rolling deploy) يُجري الخادم drain قبل أن يخرج:
- يتوقف عن استقبال الاتصالات.
- يوقف الـschedules، فلا ينطلق أي شيء مرة أخرى.
- ينتظر الطلبات والـturns التي تعمل بالفعل، ومنها انطلاقات الـschedules والـturns التي قطع الـclient الخاص بها الاتصال. الحد الأقصى للانتظار 10 ثوانٍ، أو
LOUSHO_SHUTDOWN_TIMEOUT_MS. - يغلق الاتصالات التي لا تزال مفتوحة ويستدعي
agent.close().
--stop-timeout في Docker، terminationGracePeriodSeconds في Kubernetes) أطول من هذا الانتظار. الـdrain جزء من الخادم المولَّد؛ وcreateDeployedServer() helper داخلي في ذلك الـbundle وليس مُصدَّرًا. عندما تقدّم الـagent بنفسك (مثلًا createRouteHandler() خلف خادم node:http خاص بك)، افعل الشيء نفسه في الـsignal handler الخاص بك: أوقف الاستقبال، ودع الطلبات الجارية تنتهي، ثم استدعِ agent.close().
OPENAI_API_KEY، …).
عيّن OTEL_EXPORTER_OTLP_ENDPOINT (أو OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) لكي تصدّر traces الـOpenTelemetry الخاصة بالـagent عبر OTLP/HTTP، وOTEL_SERVICE_NAME كاسم للخدمة (افتراضيًا اسم الـagent). يتطلب ذلك أن تكون @opentelemetry/sdk-trace-node و@opentelemetry/resources و@opentelemetry/exporter-trace-otlp-http مثبتة بجانب dist/server.js (لصورة docker، في package.json المولَّد): راجع Tracing: الخادم المبني.
docker
يعيد استخدام scaffold وbundle الخاصين بـnode-server ويضيف Dockerfile مبنيًا على node:22-slim ينسخ dist/ ويشغّل node dist/server.js على port 3000 باستخدام المستخدم node غير المميّز الخاص بالصورة. تعيّن الصورة HOST=0.0.0.0 — داخل الـcontainer يجب أن يستمع الخادم على كل الـinterfaces لكي يصل إليه docker run -p، لذا يرفض الـcontainer العمل بدون auth: مرّر LOUSHO_API_TOKEN (أو أرفق auth.ts)، أو LOUSHO_ALLOW_PUBLIC=1 لـagent مفتوح عن قصد (المصادقة). للحصول على صورة قابلة لإعادة الإنتاج، شغّل npm install --package-lock-only في مجلد الناتج مرة واحدة واحتفظ بـpackage-lock.json: عندها يثبّت الـDockerfile باستخدام npm ci. مرّر التوكن وبيانات اعتماد الـprovider وقت التشغيل:
/app/data، المملوك للمستخدم node، وتصرّح عنه كـVOLUME. ينسخ Docker هذه الملكية إلى أي named volume جديد، لذا يستطيع الخادم غير المميّز الكتابة هناك بدون chown يدوي. للاحتفاظ بالـsessions بين إعادات التشغيل، اربط (mount) volume ووجّه الـstore إليه:
-v ./data:/app/data) بملكية مجلد الـhost نفسه، لذا نفّذ عليه chown للـuid 1000 أولًا.
cloudflare-worker
يولّد Worker بصيغة module (export default { fetch }) وwrangler.toml وdist/worker.js، محزومًا كـES module لمنصة المتصفح. يفشل البناء إذا ظهر أي import من نوع node: في الـbundle. يحتاج tsup وwrangler، ويقدّم HTTP API المذكور أعلاه. ولديه أضيق الحدود بين الأهداف الثلاثة:
- ملفات spec، ومجلدات agent تحتوي على config وinstructions وأدوات TypeScript وskills (بدون sub-agents ولا schedules ولا channels ولا memory slots من المجلد، وبدون أدوات sandboxed)؛
- الـproviders
mockوopenaiوanthropicوopenrouter؛ والأدوات المدمجةcurrent-dateوday-nameوhttp(لا تصلhttpإلا إلى أسماء الـhosts المدرجة في الـbindingLOUSHO_HTTP_ALLOW)؛ - sessions وcheckpoints وapprovals في KV namespace واحد؛ cron triggers بتوقيت UTC.
الـpeer dependencies الاختيارية في builds الخاصة بـnode وdocker
يحزمdist/server.js الـSDK لكنه يترك الـpeer dependencies الاختيارية خارجه (مدخلات peerDependenciesMeta في الـpackage.json الخاص به: حزم الـproviders، وdockerode، وMCP SDK، وprompts، …)، لذا لا يحتاج أي build إلى اعتمادية لا تستخدمها. يُدرج package.json المولَّد أصلًا ما يحتاجه الـagent حيثما يعمل الخادم: حزمة الـprovider التي يسميها الـspec (بنطاق يوافق الإصدار الـmajor من ai الذي بُني عليه، مثل @ai-sdk/openai لـagent يستخدم OpenAI)، و@modelcontextprotocol/sdk إذا احتوى الـspec على mcpServers — وهذا كل شيء: lousho وai وzod داخل الـbundle. أي أن npm install --omit=dev في صورة docker، أو npm install بجانب ناتج node-server، سيثبّتها. أي شيء آخر — استيرادات مجلد الـagent نفسه، أو dockerode للأدوات الـsandboxed — تضيفه أنت بنفسك. مسار الكود الذي يحتاج اعتمادية ناقصة يرمي خطأ الـSDK المرمَّز الخاص بالـpeer المفقود. وتعمل cron triggers الخاصة بالـspec على node-server وdocker أيضًا، وليس على Workers فقط (راجع Schedules).
الـtargets المخصصة
الـtargets عبارة عن objects من نوعDeploymentAdapter (scaffold وbuild وdescribe) تُسجَّل بالاسم عبر registerAdapter()؛ وكلاهما مُصدَّر من جذر الحزمة.