run_code. بدلًا من أن يستدعي الـ tools
واحدة تلو الأخرى، مع round trip للموديل بعد كل call، يكتب برنامج JavaScript قصيرًا
يستدعي tools الـ agent كدوال async، ويُجري loop وfilter ويجمع نتائجها، ثم يُرجع
قيمة واحدة. وهكذا تصبح عدة tool calls بـ round trip واحد للموديل، والنتائج
الوسيطة الكبيرة لا تدخل الـ context أصلًا: فقط قيمة إرجاع البرنامج تدخل.
يعمل البرنامج داخل QuickJS WebAssembly isolate داخل العملية نفسها، لا داخل
Docker. وكل tool call يجريها يمر بالفحوص نفسها التي يمر بها call مباشر من
الموديل: التحقق من الوسائط، hooks، قواعد الصلاحيات وأوضاعها، guardrails،
وneedsApproval.
متى تستخدمه
- الجواب يحتاج عدة calls تعتمد مدخلاتها على نتائج سابقة (ابحث عن ثلاثة أسعار، ثم حوّل مجموعها).
- tool تُرجع أكثر بكثير مما يحتاجه الموديل (قائمة طويلة تحتاج filter، أو تقرير تحتاج إلى عدّه).
- الـ call نفسها تتكرر على قائمة عناصر.
شغّله
ثبّت الـ peer dependency الاختياريةquickjs-emscripten واضبط codeMode على
createAgent(). بادئة vendor/ في اسم الموديل تحدد الـ provider؛ ومع
OpenRouter استخدم openrouter/<vendor>/<model> (مثل
openrouter/openai/gpt-4o-mini):
run_code تُرجع { result, logs, toolCalls }: قيمة إرجاع السكربت، والأسطر
التي سجّلها بـ console.log() (وconsole.error() / warn()، مسبوقة
بمستواها)، وعدد الـ tool calls التي أجراها.
بدون quickjs-emscripten مثبّتة، أول run لـ agent عليه codeMode يفشل بـ
MissingPeerDependencyError يذكر اسم الحزمة وأمر التثبيت.
الخيارات
codeMode: true تعني الإعدادات الافتراضية. وإذا مرّرت object يمكنك ضبط أي
خيار مما يلي:
بدون
tools، يستطيع السكربت استدعاء كل tools الـ run ما عدا run_code
وask_question وtools الـ sub-agents (task وagent_status وagent_await
وagent_cancel وdelegate_to_*) وtool_search وload_skill والأدوات التي
يؤجّلها tool search. سمِّ tool في tools لتسمح بها رغم
ذلك: الـ deferred tool المذكورة هناك تصبح قابلة للاستدعاء من السكربتات ويظهر توقيعها
في وصف run_code (أي أنها لم تعد محجوبة عن الـ context في code mode)،
لكنها تظل خارج قائمة tools الموديل نفسه إلى أن تحمّلها tool_search.
يعرف الموديل ما يستطيع استدعاءه من وصف run_code: signature بأسلوب TypeScript
لكل tool مسموحة، مبني من input schema الخاصة بها، ووصفها يظهر كتعليق:
ما يستطيع السكربت فعله وما لا يستطيع
الكود هو جسم دالةasync. يستطيع استخدام لغة JavaScript ودوالها المدمجة (JSON
وMath وDate وPromise والمصفوفات والـ maps والتعابير النمطية)، واستدعاء
tools، والتسجيل، وإرجاع قيمة.
await tools.<name>(args)تعود بنتيجة الـ tool، أو ترميError(name: 'ToolError') رسالته هي رسالة خطأ الـ tool نفسها. وtoolsفيها فقط الـ tools المسموحة ولا يمكن تغييرها.- الوسائط والنتائج تعبر الحدود نسخَ JSON:
Dateتصل كـ string، الدوال والحقولundefinedتُحذف، وتغيير نتيجة داخل السكربت لا يغيّر شيئًا خارجها. Promise.allتشغّل الـ calls في الوقت نفسه، بحد أقصىtoolConcurrency(إعداد الـ agent) لكل سكربت.- يجب أن تكون قيمة الإرجاع JSON-serializable؛ و
undefinedتصبحnull.
require ولا import ولا process ولا fetch ولا نظام ملفات ولا
شبكة ولا setTimeout ولا أي مؤقّت آخر، ولا أي host object. ويصل السكربت
إلى العالم الخارجي فقط عبر الـ tools المُعطاة له.
نموذج الأمان
- العزل. كل سكربت يحصل على QuickJS runtime وcontext جديدين في
WebAssembly، ولا يوجد فيهما شيء من الـ host غير دالتين (واحدة لـ tool call
وواحدة لسطر log) ينزعهما كود الإعداد الخاص بالـ SDK من الـ global object
قبل أن يعمل السكربت. و
node:vmلا يُستخدم هنا، لأنه ليس حدًّا أمنيًا. - الحدود. الـ isolate يفرض حد الذاكرة وحد الـ stack البالغ 512 KiB.
والموعد النهائي يفحصه interrupt handler بينما السكربت يحسب، فأي loop لا
نهائية تُوقَف عند
timeoutMs—try/catchلا يستطيع التقاط هذا الإيقاف — ويفحصه مؤقّت بينما السكربت ينتظر tool. وكثرة الـ tool calls توقّف السكربت أيضًا، حتى لو التقط الخطأ. - البوابة لكل call. كل
tools.x(args)هو inner tool call داخل الـ run: يُتحقق منه مقابل schema الـ tool، ثم pre-tool hooks وقواعد الصلاحيات ووضع الصلاحيات وtool guardrails وneedsApproval، ثم تعمل الـ tool (عبر sandbox الـ run إذا كانتrequiresSandbox) بـ principal الـ run، ثم post-tool hooks. والـ call المرفوضة ترمي خطأ داخل السكربت مع سبب الرفض. والـ guardrail التي تمنع inner call توقّف الـ run كله، كما تفعل مع call مباشرة. - Plan mode.
run_codeمعلَّمة read-only: لا تغيّر شيئًا بنفسها. وفي plan mode يُفحص كل inner call على حدة، فيستطيع السكربت استدعاء tools القراءة فقط، وأي call لـ tool أخرى ترميdenied by plan mode. - الأخطاء. خطأ الـ tool يصل إلى السكربت كرسالة فقط، ولا يصل معه stack trace
من الـ host أبدًا. والـ tokens التي أخذتها الـ tool من
ctx.getToken()تُحجب من نتيجتها، كما في call مباشرة.
timeoutMs. وعلى سيرفر يعالج طلبات أخرى، أبقِ
timeoutMs منخفضًا.
الموافقات وتسجيل الدخول والتوقفات الأخرى
السكربت لا يستطيع التوقف. الـ QuickJS isolate لا يمكن حفظه واستئنافه لاحقًا، فأي inner call كان سيوقّف الـ run يرمي خطأ داخل السكربت بدلًا من ذلك، والـ run لا يتوقف:
يستطيع الموديل بعد ذلك استدعاء تلك الـ tool مباشرة، فيتوقف الـ run كالمعتاد.
و
run_code نفسها قد تحتاج approval (مثلًا مع permissions: [ask('*')]):
يتوقف الـ run قبل أن يعمل السكربت، ويعمل السكربت بعد قرار الموافقة، مع فحص
كل inner call.
الأحداث والـ tracing
الـ inner calls تصدّر أحداثtool.start وtool.partial وtool.done
وtool.error المعتادة، مع parentToolCallId مضبوط على
معرّف call الـ run_code. معرّفاتها <run_code call id>:<n>، مرقّمة بترتيب
الـ calls التي أجراها السكربت. وtool.done أو tool.error لكل inner call
يصل قبل الخاص بـ run_code نفسها: فإذا انتهى السكربت (أو أُوقف) وما زالت
calls بدأها شغّالة، يُلغى abortSignal الخاص بها وتنتظر run_code حتى
تستقر. والـ inner calls تنتج أيضًا أحداث permission.decision، والـ hooks
تراها تحت معرّفاتها الخاصة.
النتائج الداخلية تذهب للأحداث وللسكربت فقط. أما الـ transcript والـ session
والموديل فيحصلون فقط على نتيجة run_code وحدها.
مع tracing، لكل inner call الـ span execute_tool الخاصة بها، ابنة لـ span
الـ run_code، ومعها السمة lousho.tool.parent_call_id.
القيود والـ durability
- لا تقدّم جزئي. حالة السكربت تعيش فقط داخل الـ isolate. بعد crash،
يستدعي الـ run المستأنف
run_codeمن جديد ويعمل السكربت كله مرة أخرى، بما فيه الـ tool calls التي كان أجراها. اجعل الـ tools التي يستدعيها السكربت idempotent —ctx.toolCallIdلكل inner call هو نفسه عند إعادة التشغيل، فاستخدمه كـ idempotency key — أو نادِ الـ tools التي لها side effects مباشرة. - JavaScript فقط. الموديل يكتب JavaScript؛ وTypeScript لا يمر بـ transpile.
- أين يعمل. كل runs وكيل
createAgent():send()وstream()والـ sessions والاستئناف والموافقات، على Node. وهدفcloudflare-workerفيlousho buildلا يضمّ QuickJS، فالـ run المفعَّل فيهcodeModeيفشل هناك من بدايته. والـ agent الذي يُشغَّل كـ sub-agent (عبر أداةtaskأو delegate tool) يعمل دون code mode، وcodeModeالخاص بالـ lead لا يصل إلى tools الـ sub-agent. - الأخطاء نتائج. خطأ في السكربت، timeout، بلوغ حد الذاكرة، كثرة tool
calls، أو قيمة إرجاع تتجاوز
maxOutputChars— كلها تصبح tool error فيrun_codeيسمّي السبب؛ يستلمه الموديل والـ run يكمل.