الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
تقريبًا كل خطأ يرميه الـ SDK عن قصد هو SDKError (أو subclass منه مثل ConfigurationError أو ValidationError أو MissingPeerDependencyError) وفيه:
  • code: نص ثابت بصيغة LOUSHO_<AREA>_<NAME>. اعتمد عليه في التفرّع، لا على نص الرسالة — فقد تصبح الرسالة أوضح مع الوقت.
  • hint: جملة واحدة عن طريقة الحل.
  • docs: رابط لقسم هذا الكود في الصفحة.
تنتهي الرسالة بالمعلومات نفسها في سطر مستقل، لذا فإن الخطأ الذي يظهر دون catch يخبرك بما يجب فعله:
الـ run الذي يُرفض (send()، أو result الخاص بـ stream()، أو دورة session، أو AgentExecutor.execute()) يضع ما أنفقه على الخطأ في error.usage، وهو RunUsage مثل result.usage (ويشمل الـ sub-agents الخاصة به)، فلا تضيع tokens الـ run الفاشل وتكلفته. ويُضبط على أي خطأ يُرفض به الـ run — SDKError أو PropagatingToolError أو خطأ خاص بك — إلا إذا كان للخطأ خاصية usage خاصة به، وهو غير enumerable (فلا يتغيّر تسجيل الخطأ أو تحويله إلى JSON). ولا يكون موجودًا إذا فشل الـ run قبل أن يبدأ.
error.detail هو الرسالة دون هذا السطر. أخطاء الـ tools والـ providers (ToolExecutionError وLLMProviderError وTimeoutError وRateLimitError) تُبقي رسالتها كما هي، لأن الـ model يراها كنتيجة tool أو خطأ provider مضغوط؛ لكن toString() لا تزال تضيف السطر. الاستثناءات بضع subclasses مسمّاة من Error دون code، أُبقيت عادية عن قصد: PropagatingToolError والـ subclasses الخاصة بها (يرميها الـ tool لكي يوقف الـ run)، وWorkspaceError (عملية على الـ workspace رُفضت أو فشلت — يراها الـ model كخطأ tool)، وMcpToolError (أداة MCP محمّلة أرجع سيرفرها isError؛ وهي أيضًا خطأ tool)، وAuthError (مدخل من lousho/auth يرفض الطلب بالـ 401 أو 403 الخاص به)، وCronExpressionError (parseCronExpression() التي تغلّفها defineSchedule() كـ LOUSHO_SCHEDULE_INVALID)، وDecryptionError (EncryptionUtils وDTOEncryptionFilter). أما CassetteMismatchError (replay في recordReplay؛ راجع الاختبار) فليست منها: هي SDKError بكود LOUSHO_CASSETTE_INVALID وحقلين .cassette / .callNumber.
يربط ERROR_CODES (مُصدَّر) كل كود بالـ hint الخاص به. ويحافظ test على تطابقه مع الأكواد المستخدمة في الكود ومع الأقسام أدناه. ويفشل test آخر إذا رمى كود جديد في الـ SDK new Error(...) حرفيًا بدلًا من SDKError؛ والمواضع القليلة المتبقية داخلية ومسرودة في src/utils/plainErrors.test.ts مع سبب كلٍّ منها. إذا كنت تبدأ من العَرَض بدلًا من الكود، فراجع استكشاف الأخطاء. ابحث عن الكود بحسب المجال:

الإعدادات

LOUSHO_CONFIG_INVALID

المعنى: خيار أو معامل يحمل قيمة لا يستطيع الـ SDK استخدامها. هذا هو الكود الافتراضي لـ ConfigurationError؛ ويسمّي error.field الخيار إذا كان معروفًا. الحل: غيّر الخيار الذي تسمّيه الرسالة. مثال: withFallback([]) يرمي “withFallback() needs at least one provider”. والكود نفسه يظهر مع new NodeWorkspace({ root }) عندما يكون الـ root مفقودًا أو ليس مجلدًا، ومع اسم tool مكرر في ToolRegistry، وقيمة toolConcurrency غير صالحة، وserveMcp() دون name، وlousho studio دون ملفات Agent Forge.

LOUSHO_CONFIG_MISSING_PROVIDER

المعنى: لا يوجد model للتشغيل: استُدعي createAgent() دون model أو provider ولم يجد شيئًا في البيئة، أو استُدعي AgentExecutor.execute() / stream() دون provider. الحل: مرّر model: 'openai/gpt-4.1-mini' (أي <provider>/<model>)، أو مرّر provider instance، أو اضبط LOUSHO_MODEL أو مفتاح provider مثل OPENAI_API_KEY. البادئة vendor/ في اسم الـ model هي التي تختار الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثلًا openrouter/openai/gpt-4.1-mini). راجع المزوّدون. مثال: createAgent({ instructions: 'x' }) دون أي env var للـ provider.

LOUSHO_CONFIG_MISSING_AGENT

المعنى: استُدعي AgentExecutor.execute() / stream() دون agent. الحل: مرّر الـ agent، مثلًا AgentBuilder.create().setName('a').build()، أو استخدم createAgent() الذي لا يحتاج إلى كائن agent منفصل. مثال: AgentExecutor.execute({ input: 'hi', provider }).

LOUSHO_CONFIG_MISSING_INPUT

المعنى: استُدعي AgentExecutor.execute() / stream() دون input. الحل: مرّر رسالة المستخدم كنص أو Message[]. مثال: AgentExecutor.execute({ agent, provider }).

LOUSHO_CONFIG_CONFLICTING_OPTIONS

المعنى: مرّرت خيارين بالمعنى نفسه معًا. الحل: أبقِ أحدهما. في createAgent() الخيار prompt هو alias مُهمَل (deprecated) لـ instructions: أبقِ instructions. مثال: createAgent({ provider, instructions: 'a', prompt: 'b' }).

LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE

المعنى: تلقّى send() أو stream() الخيار sessionId، وهذا يجعل الـ run durable (يُستكمل الـ run بعد تعطّل العملية)، لكن الـ agent ليس لديه checkpoint store (مخزن نقاط حفظ). الحل: مرّر createAgent({ store: memoryStore() }) (أو SqliteStore، أو store فيه checkpoints)، أو احذف sessionId. راجع Durable execution. مثال: createAgent({ provider }).send('hi', { sessionId: 'job-1' }).

LOUSHO_CONFIG_RESOLVER_FAILED

المعنى: خيار من خيارات createAgent() معطى كدالة تعتمد على الـ run (model أو instructions / prompt أو tools) رمى خطأً أثناء حل إعدادات الـ run. لم يبدأ الـ run أصلًا: يُرفض send()، وينتهي stream() بحدث error، ويبقى سجل محادثة الـ session كما هو. يسمّي error.field الخيار، وerror.cause هو ما رمته الدالة. الحل: أصلح الدالة التي تسمّيها الرسالة. راجع الإعدادات الديناميكية. مثال: createAgent({ provider, model: ({ metadata }) => plans[metadata.plan].model }) مع خطة غير معروفة.

LOUSHO_PROMPT_UNRESOLVED

المعنى: createAgent({ prompt: 'name@version' }) (أو LOUSHO_PROMPT) ليس لديه instructions كبديل احتياطي، ولم يُجلب الـ prompt: الـ observe daemon لا يمكن الوصول إليه، أو ردّ بـ 404 لهذا الاسم والإصدار، أو LOUSHO_OBSERVE غير مضبوط. يُرفض كل run ما دام الـ prompt لم يُحل (يُرفض send()، وينتهي stream() بحدث error): الـ runs الواقعة داخل نافذة إعادة المحاولة (30 ثانية) فورًا، وكل run بعدها بعد أن يفشل جلب إعادة المحاولة الخاص به ما دام الـ daemon متوقفًا. لا يُستدعى الـ model أبدًا، لذا لا يعمل الـ agent أبدًا دون system prompt. وتسمّي الرسالة مرجع الـ prompt. الحل: شغّل الـ daemon (lousho observe) واضبط LOUSHO_OBSERVE على الـ URL الخاص به، أو انشر الـ prompt (lousho prompt push)، أو مرّر instructions كبديل احتياطي (عندما يكون مضبوطًا، لا يسجّل الـ daemon الذي يتعذّر الوصول إليه إلا تحذيرًا ويستخدم الـ run النص المضمّن). راجع المراقبة. مثال: createAgent({ provider, prompt: 'mira@latest' }) ولا يوجد daemon قيد التشغيل.

الـ providers والـ peer dependencies

LOUSHO_PROVIDER_SPEC_INVALID

المعنى: نص الـ model ليس بصيغة <provider>/<model>. الحل: اكتب الجزأين، مثلًا 'openai/gpt-4.1-mini' أو 'anthropic/claude-sonnet-4-5'. مثال: resolveProvider('gpt-4o').

LOUSHO_PROVIDER_UNKNOWN

المعنى: بادئة الـ provider في نص الـ model ليست من البادئات التي يعرفها الـ SDK. تسرد الرسالة البادئات المدعومة وتقترح أقربها. الحل: استخدم بادئة مدعومة (openai أو anthropic أو google أو openrouter أو ollama أو pi أو mock)، أو مرّر provider instance خاصًا بك. ولـ vendor ليست له بادئة، تسرد الرسالة الطرق الأخرى: openrouter/<vendor>/<model>، أو pi/<vendor>/<model> إذا كان pi يخدم هذا الـ vendor، أو حزمة AI SDK الخاصة بالـ vendor عبر fromAiSdk() (راجع المزوّدون). مثال: createAgent({ model: 'opnai/gpt-4o' }) يقول “Did you mean ‘openai/gpt-4o’?”.

LOUSHO_PROVIDER_MISSING_API_KEY

المعنى: متغير البيئة الذي يحمل credentials الـ provider (OPENAI_API_KEY أو ANTHROPIC_API_KEY أو OPENROUTER_API_KEY) غير مضبوط. الحل: اضبطه، أو مرّر provider instance مهيّأ. مثال: createAgent({ model: 'openai/gpt-4.1-mini' }) دون OPENAI_API_KEY.

LOUSHO_PROVIDER_REQUEST_FAILED

المعنى: فشل استدعاء model (LLMProviderError، وكذلك CompactedLLMProviderError الذي يشرح compacted.category الخاص به السبب: timeout أو context-length-exceeded أو quota-exceeded أو auth-failure أو unknown؛ أما فشل rate-limit فله كود خاص به، LOUSHO_PROVIDER_RATE_LIMITED). الرد المتوافق مع OpenAI الذي يُبلغ عن فشل داخل 200 (finish_reason: "error" من OpenRouter، أو chunk يحتوي على error في منتصف الـ stream) يفشل كـ 502 قابل لإعادة المحاولة بدلًا من إرجاع النص المقطوع. تجاوز السياق يكون context-length-exceeded (غير قابل لإعادة المحاولة) مهما كانت الـ status، ومنه “exceeds the available context size” و”Context size has been exceeded” من llama.cpp / LM Studio، سواء وصل من الطلب أو كخطأ في الـ stream. وفشل الاتصال يكون timeout ويسمّي السبب، مثلًا connection refused (ECONNREFUSED) at http://localhost:1234/v1/responses - is the server running?. وإذا تعذّرت قراءة body الخطأ من الـ provider (وكانت الرسالة Bad Request فقط)، يُضاف مقطع قصير من الـ body. الحل: مع quota-exceeded (الـ 429 insufficient_quota من OpenAI، أو 402 مثل “Insufficient credits” من OpenRouter؛ غير قابل لإعادة المحاولة، لأن إعادة المحاولة لا تضيف رصيدًا) اشحن الحساب أو انتقل إلى provider آخر؛ ومع auth-failure أصلح الـ API key؛ ومع context-length-exceeded قصّر المحادثة (راجع Context compaction)؛ ومع الفشل العابر استخدم withRetry() / fallbackModels (راجع المزوّدون). مثال: رد 401 من الـ provider بمفتاح ملغي.

LOUSHO_PROVIDER_RATE_LIMITED

المعنى: قيّد الـ provider معدل طلبات المستدعي: فشل استدعاء model بـ compacted.category: 'rate-limit' (CompactedLLMProviderError، وهو أيضًا LLMProviderError)، أو RateLimitError. الحل: أعد المحاولة بعد compacted.retryAfterMs (يفعل withRetry() ذلك، حتى backoff.maxMs؛ وRetry-After الأطول من ذلك يفشل فورًا مع ضبط compacted.retryAfterMs)، أو أرسل طلبات أقل. مثال: رد 429 (الـ 429 insufficient_quota من OpenAI عند نفاد الرصيد هو quota-exceeded، أي LOUSHO_PROVIDER_REQUEST_FAILED).

LOUSHO_PEER_MISSING

المعنى: ميزة تحتاج حزمة اختيارية غير مثبتة (MissingPeerDependencyError، أو SDK خاص بـ provider مثل @ai-sdk/openai). استدعاء الـ model الذي تنقصه حزمة الـ provider الخاصة به يفشل بهذا الكود (CompactedLLMProviderError الذي يكون cause الخاص به MissingPeerDependencyError)، لا بـ LOUSHO_PROVIDER_REQUEST_FAILED، وترسل الـ server routes رسالته (أمر التثبيت) إلى العميل بدلًا من الرسالة العامة. الحل: نفّذ أمر npm install الموجود في الرسالة (وهو موجود أيضًا في error.installCommand). راجع التثبيت. مثال: SubprocessSandbox دون dockerode: npm install dockerode@^5.0.1.

LOUSHO_HOSTED_TOOL_UNSUPPORTED

المعنى: لدى الـ agent أداة hosted tool (webSearch() أو codeInterpreter() أو fileSearch() أو hostedTool()) لا يستطيع الـ provider الخاص به إرسالها: إما لأن الـ provider لا يدعم hosted tools (Ollama، أو LLMProvider مخصص دون supportsHostedTool())، أو لأن المثبّت هو ai 4 (تحتاج الـ hosted tools إلى ai 6 أو 7)، أو لأن حزمة الـ provider المثبّتة لا تتضمن هذه الأداة. تسمّي الرسالة الـ provider والأداة وما الذي سيعمل. الحل: شغّل الأداة على provider وحزمة يدعمانها (راجع Hosted tools عند الـ provider)، أو احذفها من tools لهذا الـ provider. مثال: createAgent({ model: 'ollama/llama3.2', tools: [webSearch()] }) يرفض أول send() له.

LOUSHO_UNSUPPORTED_CONTENT

المعنى: رسالة مستخدم تحتوي على جزء ملف ({ type: 'file', data, mimeType }) لا يستطيع الـ provider إرساله: نوع وسائطه ليس من الأنواع التي يرسلها الـ provider على إصدار ai الرئيسي لديك (راجع المدخلات متعددة الوسائط). يُرفض الاستدعاء قبل إرسال أي شيء، لذا لا يجيب الـ model أبدًا دون الملف. ومع withFallback() (أو fallbackModels) يأخذ الـ provider التالي الاستدعاء. ويُرفض agent.send() وagent.stream() بهذا الكود. الحل: أرسل الملف إلى provider وإصدار ai رئيسي يقبلان نوعه (أو اذكر النوع في fromAiSdk(model, { fileMediaTypes }))، أو ضع نص الملف في الرسالة، أو اضبط unsupportedFiles: 'text-note' على الـ provider لكي يرسل [file <name> (<type>) not sent] مكانه، كما كان سابقًا. مثال: ملف PDF مُرسَل إلى new OllamaProvider({ name: 'ollama' }).

ملفات الـ AgentSpec

LOUSHO_SPEC_NOT_FOUND

المعنى: تلقّى loadSpec() مسارًا غير موجود. الحل: تحقق من المسار الوارد في الرسالة — خطأ إملائي، أو مجلد عمل خاطئ، أو spec لم يُنشأ أصلًا. مثال: loadSpec('agent.yaml') ولا يوجد agent.yaml في الـ cwd.

LOUSHO_SPEC_INVALID

المعنى: وجد loadSpec() حقولًا لم تجتز الـ validation. تُسرد كل مشكلة بصيغة '<path>': <problem>، بالإضافة إلى أي حقل top-level يبدو خطأً إملائيًا، مع اقتراح. الحل: أصلح كل حقل مسرود. راجع الإعدادات. مثال:

LOUSHO_SPEC_UNKNOWN_FIELD

المعنى: الـ spec صالح فيما عدا ذلك، لكن فيه حقل top-level يُرجَّح أنه خطأ إملائي في أحد حقول الـ spec، وكان سيُتجاهل. أما بقية الحقول المجهولة فلا تزال تُتجاهل. الحل: أعد تسميته بالحقل المقترح، أو احذفه. مثال: tool: [http] يعطي “unknown field ‘tool’ (did you mean ‘tools’?)”.

LOUSHO_SPEC_UNSUPPORTED_FORMAT

المعنى: امتداد ملف الـ spec ليس .yaml ولا .yml ولا .json. الحل: أعد تسمية الملف، أو حوّله. مثال: loadSpec('agent.toml').

LOUSHO_SPEC_UNSUPPORTED

المعنى: يضبط AgentSpec v2 حقلًا لا يستطيع هذا الإصدار من الـ SDK تشغيله بعد. الـ spec صالح فيما عدا ذلك؛ وكان تشغيله سيفشل، لذا يُرفض من البداية. الحل: احذف الحقل الذي تسمّيه الرسالة، أو حدّث الـ SDK. مثال: tools: [{ builtin: web_fetch }] على إصدار لا يدعم مراجع tools.

LOUSHO_SPEC_SECRET_MISSING

المعنى: يشير AgentSpec v2 إلى secret ({ env: NAME } أو { secret: name }) ليست له قيمة في المكان الذي يُبنى فيه الـ agent. الحل: اضبط متغير البيئة، أو أضف الـ secret المسمّى (Studio: Settings → Secrets). مثال: env: { GITHUB_TOKEN: { env: GITHUB_TOKEN } } وGITHUB_TOKEN غير مضبوط.

الأدوات

LOUSHO_TOOL_NOT_FOUND

المعنى: عنصر tools في الـ spec يسمّي tool ليست من الأدوات المدمجة. الحل: استخدم إحدى الأدوات التي تسردها الرسالة، أو ابنِ الـ agent بـ createAgent({ tools: [...] }) مع أداتك. راجع الأدوات. مثال: tools: [not-a-real-tool] في spec.

LOUSHO_TOOL_NEEDS_CREDENTIALS

المعنى: الـ spec يسمّي tool (github أو jira) تحتاج credentials وليس في ملف الـ spec حقل لها. الحل: ابنِ الـ agent بـ createAgent() ومرّر الأداة مهيّأة، مثلًا createGitHubTools(config) من lousho/integrations. مثال: tools: [github] في spec.

LOUSHO_TOOL_EXECUTION_FAILED

المعنى: ToolExecutionError (أو subclass منه مثل ToolArgumentsValidationError). داخل الـ run يصل إلى الـ model كنتيجة tool ويستمر الـ run. الحل: افحص error.toolName وerror.cause، وأصلح الأداة أو المدخلات التي أُعطيت لها. مثال: رمت الدالة execute الخاصة بأداة خطأً. ترمي الأدوات المدمجة (http وemail وgithub وjira وslack وask_question) SDKError بهذا الكود عند فشل الاستدعاء؛ ورسالتها هي نتيجة الأداة، لذا لا يُلحق بها سطر [code] hint (docs).

LOUSHO_TOOL_ARGS_INVALID

المعنى: استدعى الـ model أداة بـ arguments لا تطابق الـ input schema الخاص بها (ToolArgumentsValidationError). داخل الـ run تصل المشكلات إلى الـ model كنتيجة tool ويستطيع إعادة المحاولة، لذا نادرًا ما ينتهي run بسببها. الـ arguments التي ليست JSON صالحًا (المقطوعة مثلًا) تأخذ الخطأ نفسه، مع مشكلة واحدة على (root): arguments are not valid JSON: <parse error>; received: <the text, truncated>. ولا تعمل الأداة. وقبل ذلك يُجرَّب إصلاح بسيط: code fence من markdown حول النص، والفواصل الزائدة في النهاية، والـ JSON المرمَّز مرتين، كلها تُصلَح إذا كانت النتيجة object JSON. والـ arguments الفارغة ("") تعني {}. ويحمل حدث tool.start الخاص بالاستدعاء الحقل rawArgs، وهو النص الذي أرسله الـ model، كلما أُصلح أو فشل الـ parse. الحل: إذا كنت أنت من استدعى الأداة، فأصلح الـ arguments التي تسمّيها الرسالة؛ وإذا ظل الـ model يخطئ فيها، فاجعل نص .describe() للحقل أوضح. يسرد error.issues كل مسار ومشكلته. راجع الأدوات. مثال: يرسل الـ model { to: 42 } إلى أداة حقلها to نص.

LOUSHO_MCP_START_FAILED

المعنى: لم يبدأ سيرفر MCP من نوع stdio (عنصر في mcpServers يحتوي على command): لم يُعثر على الأمر، أو خرجت العملية أثناء مصافحة initialize، أو لم تردّ خلال connectTimeoutMs (الافتراضي 60 ثانية). يحمل الخطأ (McpStartError) القيمة exitCode (أو signal) وstderr، وهي آخر 20 سطرًا كتبتها العملية هناك، وتعرض الرسالة كليهما. ويفشل به connectMcp() وagent.ready() (أو أول send()). الحل: اقرأ أسطر الـ stderr الواردة في الرسالة، أو شغّل الـ command مع args الخاصة به بنفسك. تحقق من اسم الحزمة وإصدارها لسيرفر npx، ومن الـ env الذي يحتاجه، ومن cwd. ومع stderr: 'inherit' أو 'ignore' لا تُعرض أي أسطر. راجع MCP. مثال: npx -y some-mcp-server لحزمة غير موجودة يخرج وعلى الـ stderr سطر npm error 404.

LOUSHO_MCP_CALL_FAILED

المعنى: فشل استدعاء أداة MCP محمّلة على مستوى البروتوكول: خرج السيرفر أو أغلق الاتصال (MCP error -32000: Connection closed)، أو انتهت مهلة الطلب، أو ردّ السيرفر بخطأ JSON-RPC. تسمّي الرسالة الأداة كما يراها الـ model (<server>__<tool>)؛ وcause هو خطأ MCP SDK نفسه، والـ code الرقمي الخاص به هو كود JSON-RPC. الأداة التي عملت وأبلغت isError: true ليست هذا الخطأ (يصل نصها إلى الـ model كـ McpToolError)، ولا طلب تسجيل الدخول (LOUSHO_MCP_AUTH_REQUIRED) ولا الإلغاء. أثناء الـ run تكون النتيجة خطأ tool ويستمر الـ run؛ وخطوة الـ flow التي فيها retry: { maxAttempts } تعمل مرة أخرى، والسيرفر المتصل بـ lazy (الافتراضي) يعيد الاتصال في الاستدعاء التالي. الحل: تأكد أن السيرفر الذي تسمّيه الرسالة يعمل ويستجيب؛ ولسيرفر stdio، شغّل أمره بنفسك واقرأ الـ stderr الخاص به. ارفع timeoutMs الخاص بالسيرفر إذا انتهت مهلة الطلب. مثال: سيرفر stdio يتعطّل أثناء معالجة files__read.

الـ approvals والـ sessions

LOUSHO_APPROVAL_STORE_MISSING

المعنى: استُدعيت أداة عليها needsApproval في run من AgentExecutor.execute() ليس لديه approvalStore يتوقف فيه. الحل: مرّر approvalStore: new InMemoryApprovalStore() (أو store دائمًا)، أو استخدم createAgent() الذي يملك واحدًا افتراضيًا. راجع Approvals. مثال: AgentExecutor.execute({ agent, input, provider, toolRegistry }) مع أداة needsApproval.

LOUSHO_APPROVAL_NOT_FOUND

المعنى: تلقّى resumeAfterApproval() أو agent.approvals.resolve() معرّفًا لا يقابل approval معلّقة: إما أنه مجهول أو حُسم من قبل. الحل: احسم معرّفًا من agent.approvals.list() (أو approvalId في النتيجة المتوقفة)؛ كل approval تُحسم مرة واحدة. مثال: استدعاء agent.approvals.resolve({ id, approved: true }) مرتين. يردّ route الـ approvals (POST /chat/:sessionId/approvals/:id) بهذا الكود مع 404 أيضًا عندما تخص الـ approval session غير التي في الـ URL.

LOUSHO_APPROVAL_ORPHANED

المعنى: agent.approvals.resolve() (أو streamResolve()، أو resumeAfterApproval()) تلقّى approval لم يعد الـ run المتوقف الخاص بها ينتظرها: حُذف الـ checkpoint الخاص بالـ run (<id>.turn-<n> لـ turn في session، أو checkpoint run من send(msg, { sessionId })) (بـ checkpoints.delete(id)، أو discardPending()، أو TTL، أو يدويًا) أو استبدله run أحدث تحت المعرّف نفسه. لم تعمل الأداة، وتُسحب الـ approval: فلا تُسرد بعد ذلك، ويفشل حسمها مرة أخرى بـ LOUSHO_APPROVAL_NOT_FOUND. الحل: ابدأ turn جديدة في الـ session (أو run جديدًا) بدلًا منها؛ فلم يبقَ شيء لإكماله. يحتفظ SqliteStore.prune() بالـ turns المتوقفة، لذا يتطلب هذا أن يُزال الـ checkpoint بطريقة أخرى. مثال: تحذف cust-7.turn-2 من الـ checkpoint store، ثم توافق على الاسترداد الذي توقفت عنده تلك الـ turn.

LOUSHO_APPROVAL_CONFLICT

المعنى: 409 من route الـ approvals: حسم طلب آخر الـ approval نفسها قبلك، ولا تزال متابعته قيد التشغيل (على عملية السيرفر هذه). الحل: لا تحسمها مرة أخرى؛ اقرأ الـ session (GET /chat/:sessionId) وانظر كيف اكتملت الـ turn. مثال: مشرفان يضغطان “Approve” على الاسترداد نفسه في اللحظة نفسها.

LOUSHO_APPROVAL_FORBIDDEN

المعنى: 403 من route الـ approvals: رفض authorizeApproval الخاص بالـ route هذا المستدعي. افتراضيًا لا يستطيع حسمها إلا المستدعي الذي يعمل الـ run المتوقف لحسابه (راجع مصادقة الـ routes). الحل: احسمها كمستدعي يقبله authorizeApproval، أو غيّر authorizeApproval. مثال: يرسل المستخدم bob قرارًا على approval تخص run خاصًا بـ alice.

LOUSHO_APPROVAL_DECISION_INVALID

المعنى: 400 من route الـ approvals: لا يحتوي الـ body على approved (boolean) ولا على answer (نص). الحل: أرسل { "approved": true } (أو false، مع note اختياري)، أو { "answer": "..." } لتوقف ask_question. مثال: إرسال { "approve": "yes" } لـ /chat/alice-1/approvals/ap-1.

LOUSHO_APPROVAL_KIND_MISMATCH

المعنى: 400 من route الـ approvals: أُرسل answer لتوقف ليس سؤالًا. توقف السؤال يقبل answer — أو approved مع الجواب في note (وapproved: false للرفض)؛ وتوقف الـ tool call يقبل approved؛ أما توقف تسجيل الدخول فيكتمل تلقائيًا فور تسجيل المستخدم دخوله. الحل: أرسل الحقل المناسب لنوع التوقف؛ يعرض GET /chat/:sessionId قيمة approvalKind للتوقف المعلّق. مثال: إرسال { "approved": true } إلى توقف ينتظر جواب الـ model على ask_question.

LOUSHO_SESSION_FORBIDDEN

المعنى: 403 من route session: رفض authorizeSession الخاص بالـ route على هذا المستدعي الإجراء (read أو chat أو approve) على هذه الـ session. الحل: استخدم session يملكها هذا المستدعي، أو غيّر authorizeSession. مثال: يقرأ المستخدم bob المسار GET /chat/alice-1 الذي استخدمته alice أولًا (وهذا هو الافتراضي عند غياب authorizeSession)، أو لا يسمح authorizeSession إلا بالمعرّفات التي تبدأ بمعرّف المستدعي.

LOUSHO_REQUEST_FORBIDDEN

المعنى: 403 من route session قبل تشغيله: طلب POST قادم من صفحة على origin آخر (ليس الـ Origin الخاص به origin السيرفر نفسه وليس ضمن allowedOrigins، أو علّمه المتصفح بـ Sec-Fetch-Site: cross-site)، أو أن ترويسة Host ليست من القيم التي يسمح بها السيرفر (allowedHosts، أو أسماء الـ loopback على lousho dev). الحل: استدعِ من origin السيرفر نفسه، أو أضف origin الصفحة إلى allowedOrigins (راجع مصادقة الـ routes)؛ ولرفض Host، أضف الاسم إلى allowedHosts (--allowed-hosts على lousho dev). مثال: صفحة على https://evil.example ترسل POST إلى /api/agent/chat مع cookie الـ session الخاص بالمستخدم.

LOUSHO_REQUEST_INVALID

المعنى: 400 من route session: الـ body ليس JSON صالحًا، أو ينقصه حقل يحتاجه الـ route (POST /chat دون sessionId وinput، أو input فارغ، أو input لا يحتوي على رسالة user). الحل: أرسل الحقول التي تسمّيها رسالة الخطأ، مثلًا { "sessionId": "chat-1", "input": "Hello" } (راجع HTTP API). مثال: POST /chat مع { "sessionId": "chat-1", "input": [] }.

LOUSHO_UNSUPPORTED_MEDIA_TYPE

المعنى: 415 من route session: لم يُرسل body الـ POST بصيغة JSON. الـ bodies من نوع form وtext/plain مرفوضة لأن أي موقع آخر يستطيع إرسالها دون CORS preflight. الحل: أرسل Content-Type: application/json (curl -H 'Content-Type: application/json')، أو مرّر requireJsonBody: false. مثال: curl -d '{"sessionId":"a","input":"hi"}' /chat دون -H يرسل application/x-www-form-urlencoded.

LOUSHO_SESSION_AWAITING_APPROVAL

المعنى: SessionAwaitingApprovalError: الـ session أو الـ run الخاص بـ sessionId متوقف عند approval (error.approvalId)، لذا لا يستطيع قبول input جديد الآن. الحل: احسم الـ approval بـ agent.approvals.resolve() (أو resumeAfterApproval() مع checkpointStore نفسه)، ثم أرسل مرة أخرى. راجع Durable execution. وعبر HTTP، يُرجع POST /chat لـ session في هذه الحالة 409 بهذا الكود مع الـ approvals التي يجب حسمها (approvalId وapprovalIds). مثال: session.send('next') والـ turn السابق لا يزال ينتظر approval.

LOUSHO_SESSION_ID_INVALID

المعنى: معرّف الـ session ليس من 1 إلى 128 حرفًا من الحروف والأرقام و_ و- (تصبح المعرّفات أسماء ملفات، لذا فإن ../ و/ مرفوضة). أو معرّف run (sessionId الخاص بـ agent.send() / agent.stream()، أو معرّف في checkpoint store) ليس من 1 إلى 200 حرف من الحروف والأرقام و_ و- و. (ولا يبدأ ولا ينتهي بـ .)، وهي القاعدة نفسها على كل store؛ أو ينتهي بـ .turn-<n> أو .paused، وهي مفاتيح checkpoints خاصة بالـ session (فالـ run تحت 'victim.turn-2' كان سيكتب في turn الـ session victim)، أو بـ .fire (claim إطلاق خاص بـ schedule). تذكر الرسالة أي القاعدتين تنطبق: المعرّف الذي يحتوي على . أو يتجاوز 128 حرفًا هو معرّف run صالح لكنه ليس معرّف session صالحًا. الحل: استخدم معرّفًا مثل 'chat-9f2c4e7a1b'، أو اتركه ليُولَّد تلقائيًا. وعلى route يخدم أكثر من مستخدم، لا تجعل المعرّفات سهلة التخمين من اسم المستخدم أو رقمه (راجع من يستطيع استخدام session). مثال: agent.session({ id: '../etc' })، أو agent.send(msg, { sessionId: 'chat.turn-2' }).

LOUSHO_SESSION_FILE_CORRUPT

المعنى: سجل محادثة مخزّن (ملف FileSessionStore، أو صف في SqliteStore) ليس JSON صالحًا أو ليس مصفوفة JSON من الرسائل، مثل كتابة انقطعت في منتصفها. الحل: استعد الملف من نسخة احتياطية، أو احذفه لتبدأ الـ session من جديد: يزيله session.clear(). مثال: sessions/user-42.json ومحتواه {}.

LOUSHO_SESSION_BUSY

المعنى: استدعيت session.compact() أو session.clear() أو session.fork() وهناك turn من هذه الـ session قيد التشغيل أو في الطابور. ومن send() / stream(): أجرى كاتب آخر لا يراه الطابور داخل العملية (عملية أخرى، أو كائن store آخر فوق البيانات نفسها) commit لـ turn أثناء تشغيل هذه الـ turn، لذا لم يُجرَ commit لهذه الـ turn (بشكل ذرّي مع store يوفّر saveIf: الذاكرة والملفات وSQLite؛ وبأفضل جهد مع KV). تُحفظ استدعاءات الـ tools في الـ turn التي عملت: تُضاف الـ turn حتى نتائجها بعد turn الكاتب الآخر. ويظهر أيضًا من send() وresume() وagent.send(msg, { sessionId }) وagent.resume() وapprovals.resolve(): الـ run الذي يحمل الـ checkpoint (أو turn الـ session) يعمل الآن في عملية أو replica أو كائن store آخر، ويحتفظ بالـ run lease الخاص به (راجع Durable execution)؛ لم يُشغَّل شيء هنا، وتبقى الـ approval المحسومة معلّقة. وعبر HTTP، 409 مع Retry-After من POST /chat: عملية أو replica أخرى تحتفظ بالـ lease الخاص بالـ session، أو طلب بـ Idempotency-Key نفسه لا يزال يشغّل الـ turn الخاصة به من هذه الـ session (راجع إعادة إرسال turn). الحل: انتظر send() الخاص بالـ turn (أو ألغِه)، ثم استدعِ مرة أخرى. وبعد فشل send() بهذه الطريقة، أرسل مرة أخرى: تقرأ الـ session سجل المحادثة الحالي في بداية كل استدعاء. والـ lease الذي تركته عملية متوقفة يُستولى عليه فور انتهاء مدته (30 ثانية، بالإضافة إلى مهلة سماح تصل إلى 30 ثانية لفرق الساعات على stores الملفات وSQLite)، أو فورًا عندما يثبت أن العملية خرجت على الـ host نفسه وفي الـ PID namespace نفسه. والـ run الذي تعلّق حتى تجاوزت مدة الـ lease الخاص به يفشل بهذا الكود عند الـ checkpoint التالي بدلًا من الكتابة فوق الـ run الذي حلّ محله.

LOUSHO_SESSION_TURN_PENDING

المعنى: استدعيت session.compact() وفي الـ session الـ durable turn منقطعة، والـ checkpoint الخاص بها مرتبط بطول سجل المحادثة. الحل: أكملها بـ session.resume() أو تخلّص منها بـ session.discardPending()، ثم استدعِ مرة أخرى.

LOUSHO_SESSION_TURN_FAILED

المعنى: وجد send() / stream() في session durable الـ turn غير المكتملة للـ session، وقد فشلت آخر محاولة لها بخطأ provider لا تصلحه إعادة المحاولة (فشل في طول السياق أو المصادقة، أو 4xx آخر). يسجّله الـ checkpoint الخاص بالـ turn كـ lastError وattempts؛ ولا تُعاد الـ turn. الحل: تخلّص من الـ turn بـ session.discardPending() وأرسل مرة أخرى، أو أصلح السبب وأعد محاولتها بـ session.resume().

LOUSHO_SESSION_STREAM_UNSUPPORTED

المعنى: استدعيت stream() على AgentSession مبنية يدويًا دون runner يدعم الـ streaming. الحل: احصل على الـ session من agent.session() التي تدعم الـ stream، أو استدعِ send(). مثال: new AgentSession(run).stream('hi').

LOUSHO_SESSION_STEP_NOT_FOUND

المعنى: تلقّت session.fork({ fromStep }) خطوة ليست عددًا صحيحًا من 0 إلى عدد الخطوات في session.history(). الخطأ ConfigurationError (field: 'fromStep') وتسرد رسالته النطاق الصحيح. الحل: اختر خطوة من session.history()، أو 0 إذا كنت لا تريد الاحتفاظ بشيء. مثال: session.fork({ fromStep: 9 }) على session فيها ثلاث خطوات.

LOUSHO_SESSION_EXISTS

المعنى: تلقّت session.fork({ id }) معرّفًا له سجل محادثة أصلًا في store الـ session (أو turn عليها checkpoint كان الـ fork سيلتقطها)، أو هو معرّف الـ session نفسه. الخطأ ConfigurationError (field: 'id'). الحل: اختر معرّفًا غير مستخدم، أو اترك id فيُنتج <id>-fork-<n>. مثال: session.fork({ fromStep: 1, id: session.id }).

LOUSHO_SESSION_FORK_UNSUPPORTED

المعنى: استدعيت fork() على AgentSession مبنية يدويًا دون الدالة التي تنشئ sessions شقيقة. الحل: احصل على الـ session من agent.session() التي تدعم الـ fork. مثال: new AgentSession(run).fork({ fromStep: 0 }).

LOUSHO_REMOTE_UNAUTHORIZED

المعنى: lousho eval --url أو remoteTarget() أو sub-agent من نوع remoteAgent() تلقّى 401 من الـ agent المنشور: الـ bearer token مفقود أو غير صحيح. تفشل حالة الـ eval (ويستمر الـ run)؛ ويصل إلى الـ lead model خطأ tool منظَّم. ولا يدخل الـ token الرسالة أبدًا. الحل: مرّر LOUSHO_API_TOKEN الخاصة بالنشر عبر --token أو متغير البيئة LOUSHO_EVAL_TOKEN. راجع تشغيل الـ evals على نشر قائم. مثال: lousho eval --url https://agent.example.com على نشر محمي بـ token.

LOUSHO_REMOTE_REQUEST_FAILED

المعنى: حالة eval عن بُعد (lousho eval --url أو remoteTarget()) أو مهمة remoteAgent() لم تتمكن من العمل: تعذّر الوصول إلى النشر، أو ردّ بحالة ليست 2xx، أو أُلغي الطلب، أو انقطع بث الأحداث أو اقتُطع (دون run.done). وتفشل به أيضًا مهمة remoteAgent() التي ينتهي الـ run البعيد الخاص بها بخطأ، وتقول الرسالة “the remote run ended in an error”. يصل إلى الـ lead model كخطأ tool منظَّم؛ ولا يكون الـ bearer token جزءًا منه أبدًا. الحل: اقرأ الرسالة (تسمّي الـ url، ومع الـ sub-agent تسمّي معرّف الـ session البعيدة)؛ تحقق من الـ URL ومن GET <url>/health ومن سجلات النشر. مثال: lousho eval --url http://localhost:1 ولا شيء يستمع على المنفذ.

LOUSHO_SUBAGENT_TASK_NOT_FOUND

المعنى: طلب استدعاء task استئناف أو إجراء fork لـ taskId ليست لهذه الـ session الرئيسية محادثة له (لم يبدأ أبدًا، أو بدأ في session رئيسية أخرى أو run آخر، أو لم يكتمل)، أو يخص sub-agent آخر. يصل إلى الـ lead model كخطأ tool منظَّم. الحل: استخدم taskId من نتيجة task سابقة للـ session الرئيسية نفسها، ومع agent نفسه؛ أو اترك taskId لتبدأ مهمة جديدة. راجع الـ sub-agents. مثال: task({ agent: 'researcher', taskId: 'task_7', prompt }) والـ session لا تملك إلا task_1.

LOUSHO_SUBAGENT_TASK_BUSY

المعنى: طلب استدعاء task استئناف مهمة أو إجراء fork لها بينما الـ sub-agent الخاص بها لا يزال يعمل، مثل مهمة في الخلفية لم تكتمل. الحل: انتظرها بـ agent_await (أو أوقفها بـ agent_cancel)، ثم تابعها. مثال: task({ agent: 'researcher', taskId: 'task_1', prompt }) مباشرة بعد بدء task_1 بـ background: true.

LOUSHO_CHECKPOINT_NOT_FOUND

المعنى: طُلب من AgentExecutor.fork() أو agent.fork() خطوة غير موجودة في سجل الـ checkpoints الخاص بالـ session: الـ session مجهولة، أو لم يُوصل إلى الخطوة أبدًا، أو حُذفت مدخلاتها عند تجاوز historyLimit الخاص بالـ store. تسرد الرسالة الخطوات المحفوظة. الحل: أجرِ fork عند إحدى الخطوات المسرودة، أو ارفع historyLimit في الـ store. راجع Durable execution. مثال: agent.fork('job-1', { fromStep: 9 }) بعد run من 3 خطوات.

LOUSHO_CHECKPOINT_CORRUPT

المعنى: checkpoint مخزّن لا يمكن قراءته: ليس JSON صالحًا أو ليس checkpoint، وعادةً ما يكون كتابة انقطعت بسبب crash أو انقطاع كهرباء على store لا يدعم الكتابة الـ durable. يفشل عليه send() وresume() وagent.resume()، ويسرد agent.pending() الـ run بوصفه 'in-progress' مع هذا الكود في lastError الخاص به (retryable: false). الحل: تخلّص منه: session.discardPending() (أو session.clear()) لـ turn في session، وcheckpointStore.delete(id) لـ run. لا يمكن استئناف الـ run المنقطع. مثال: ملف checkpoints/chat.turn-2.json حجمه 0 بايت بقي بعد انقطاع الكهرباء.

LOUSHO_AGENT_DRIFT

المعنى: استأنف run متوقفًا مؤقتًا أو منقطعًا agent مختلف عن الذي حفظه، وقيمة onAgentDrift هي 'error'. تسمّي الرسالة ما تغيّر: الـ model، أو tools أُضيفت أو حُذفت أو تغيّر الـ input schema الخاص بها، أو الـ instructions. يُرمى الخطأ قبل أي استدعاء model أو تشغيل tool؛ ويبقى الـ checkpoint (ومع الـ approval، السجل المعلّق) كما هو. الحل: استأنف بالـ agent نفسه الذي أوقف الـ run، أو اضبط onAgentDrift على 'warn' (الافتراضي) أو 'ignore' لتُكمل على أي حال. راجع Durable execution. مثال: createAgent({ store, onAgentDrift: 'error' }) بعد نشر غيّر اسم tool، ثم agent.resume('job-1').

LOUSHO_RESUME_TOOL_MISSING

المعنى: run مستأنَف ينتظر tool call (call عليه موافقة، أو call من آخر turn للـ model لم تصدر نتيجته بعد) والـ agent الذي يستأنف لا يملك هذه الـ tool. هذا خطأ مهما كانت قيمة onAgentDrift، لأن الـ call لا يمكن تشغيله. الحل: أعِد الـ tool بالاسم نفسه، أو تخلّص من الـ run المتوقف (احذف الـ checkpoint الخاص به، أو ارفض الـ approval الخاصة به). راجع Durable execution. مثال: run متوقف عند charge_card، ثم نشر يحذف هذه الـ tool ويُستدعى agent.approvals.resolve({ id, approved: true }).

LOUSHO_RUN_ALREADY_ITERATED

المعنى: جرى المرور على AgentRun من session.stream() مرة ثانية. الحل: اجمع الأحداث في أول حلقة for await، أو استدعِ stream() من جديد لـ run جديد. راجع البث. مثال: حلقتا for await (const event of run) على الـ run نفسه.

LOUSHO_RUN_NO_PROGRESS

المعنى: رفض createProgressGuard() عدد maxDenials من الاستدعاءات ثم أجرى الـ model استدعاءً آخر كان سيرفضه. يُسجَّل الفشل بوصفه غير قابل لإعادة المحاولة، لذا يترك agent.recover() الـ run؛ ولا يزال agent.pending() يسرده. الحل: اقرأ أحداث heal.action الخاصة بالـ run لكي ترى الاستدعاءات التي رُفضت، ثم أصلح الأداة أو الـ instructions الخاصة بالـ agent. وإذا كانت أداة تتكرر لسبب مشروع، مثل أداة تُجري polling، فأضفها إلى ignoreTools. راجع الخطافات. مثال: model يظل يستدعي أداة فاشلة بعد أن طُلب منه التوقف.

الجداول الزمنية

LOUSHO_SCHEDULE_INVALID

المعنى: تلقّت defineSchedule() تعريفًا غير صالح: تعبير cron يفشل في الـ parse (تسمّي الرسالة الحقل)، أو لا يحتوي على واحد بالضبط من prompt وrun. وتواجه مجلدات الـ agents هذا أثناء تحميل schedules/. الحل: صحّح التعبير أو أعطِ الـ schedule واحدًا من prompt / run. راجع الجداول الزمنية. مثال: defineSchedule({ cron: '61 * * * *', prompt: 'hi' }).

LOUSHO_SCHEDULE_RUN_INCOMPLETE

المعنى: انتهت turn لـ schedule من نوع prompt بـ finishReason غير 'stop'؛ وتسمّيه الرسالة. يمرّره startSchedules() إلى onError، ويُرفض به fireSchedule()، ويسجّله scheduled() في الـ Worker. ومع 'awaiting-approval' تسمّي الرسالة الـ approval، وتبقى معلّقة. الحل: احسم الـ approval المعلّقة بـ agent.approvals.resolve()، أو غيّر الـ prompt أو الـ tools أو مخطط output أو الحدود لكي تتمكن turn بلا إشراف من الاكتمال. راجع الجداول الزمنية. مثال: schedule يجعل الـ prompt الخاص به الـ agent يستدعي tool عليها needsApproval.

القنوات

LOUSHO_CHANNEL_INVALID

المعنى: ملف في channels/ داخل مجلد agent لا يُجري default export لـ channel (كائن يحتوي على parse وreply). تسمّي الرسالة الملف. الحل: أجرِ default export لـ channel مبنية بـ defineChannel() أو httpChannel() أو webhookChannel() أو slackChannel() أو discordChannel() أو telegramChannel() أو githubChannel() أو teamsChannel(). راجع القنوات. مثال: export default { cron: 'x' } في channels/sms.ts.

LOUSHO_MEMORY_INVALID

المعنى: ملف في memory/ داخل مجلد agent لا يُجري default export لخانة memory (كائن يحتوي على scope وprovider). تسمّي الرسالة الملف. الحل: أجرِ default export لـ defineMemory({ ... })، أو للخيارات نفسها دون name (يُستخدم اسم الملف). راجع الذاكرة ومجلدات agent. مثال: export default { cron: 'x' } في memory/notes.ts.

السجل

LOUSHO_REGISTRY_UNREACHABLE

المعنى: لم يتمكن lousho add من قراءة مستند من الـ registry: لم يردّ الـ URL في الوقت المحدد أو أرجع خطأً، أو الملف المحلي مفقود، أو الـ scheme ليس http(s)، أو المستند أكبر من السقف. الحل: تحقق من قيمة --registry (أو LOUSHO_REGISTRY) ومن اتصالك. راجع السجل. مثال: lousho add x --registry https://example.invalid/index.json.

LOUSHO_REGISTRY_ITEM_NOT_FOUND

المعنى: لا يحتوي فهرس الـ registry على عنصر بهذا الاسم. تقترح الرسالة أقرب اسم إن وُجد. الحل: نفّذ lousho add --list واستخدم أحد الأسماء. مثال: lousho add web-serach واسم العنصر web-search.

LOUSHO_REGISTRY_INVALID

المعنى: فهرس registry أو مستند عنصر فيه ليس JSON صالحًا أو لا يطابق الصيغة (حقل ناقص، أو نوع عنصر مجهول، أو عنصر يسمّي مستنده عنصرًا آخر). الحل: أصلح المستند الذي تسمّيه الرسالة. راجع السجل. مثال: مستند عنصر دون files.

LOUSHO_REGISTRY_UNSAFE_PATH

المعنى: عنصر يطلب كتابة ملف مساره مطلق، أو يحتوي على .. أو backslashes أو حرف قرص، أو يقع خارج المجلد الذي يُسمح لنوعه بالكتابة فيه، أو يُحل خارج مجلد الـ agent عبر symlink، أو يتجاوز سقوف الحجم. لم يُكتب شيء. الحل: لا تثبّت العنصر؛ وأبلغ من يستضيف الـ registry. راجع السجل. مثال: عنصر tool فيه ملف ../../.bashrc.

LOUSHO_REGISTRY_FILE_EXISTS

المعنى: ملف كان العنصر سيكتبه موجود أصلًا. لم يُكتب شيء. الحل: مرّر --overwrite، أو انقل ملفك من مكانه أولًا. مثال: lousho add web-search مرتين.

LOUSHO_REGISTRY_MANIFEST_MISMATCH

المعنى: كود عنصر يصل إلى شيء لا يعلنه الـ permission manifest الخاص به: يستورد child_process دون exec: true، أو يكتب ملفات دون filesystem: "write"، أو يستدعي fetch() أو يسمّي host URL ليس ضمن network، أو يقرأ متغير بيئة ليس ضمن env، أو يستخدم eval أو new Function أو process.env[...] محسوبًا أو import() / require() ديناميكيًا — وهذه لا يُسمح بها أبدًا. تسرد الرسالة كل مخالفة بصيغة <file>:<line>: <what> (<fix>). لم يُكتب شيء. ويُبلغ عنها --dry-run أيضًا. الحل: لا تثبّت العنصر؛ وأبلغ من يستضيف الـ registry. يُصلح مؤلفه الكود أو يعلن الصلاحية. راجع السجل. مثال: عنصر tool يستورد ملفه node:child_process والـ manifest الخاص به خالٍ من exec.

الـ sandbox

LOUSHO_SANDBOX_EGRESS_UNSUPPORTED

المعنى: SubprocessSandbox مع network: { allow } وbroker لا يستطيع على هذا الـ Docker daemon أن يجعل الـ credential broker الطريق الوحيد للحاوية إلى الخارج، لذا لم يشغّل أي حاوية بدلًا من منح egress مفتوح. تسمّي الرسالة السبب: Docker Desktop (تعمل الحاويات داخل VM، فليس للـ host عنوان على الشبكة الداخلية)، أو Docker rootless، أو daemon على جهاز آخر (لا يستطيع الـ broker الاستماع على بوابة الشبكة)، أو شبكة مُعاد استخدامها ليست داخلية، أو Engine أقدم من 25.0.5 يمرّر DNS من الشبكات الداخلية. الحل: شغّل الـ agent على مضيف Linux عليه Docker Engine 25.0.5 أو أحدث، أو استخدم network: 'none'. راجع أدوات الـ workspace. مثال: new SubprocessSandbox({ network: { allow: ['api.github.com'] }, broker }) مع Docker Desktop.

LOUSHO_SANDBOX_PATH_DENIED

المعنى: تلقّى SubprocessSandbox.writeFile() مسارًا خارج root الخاص بالـ sandbox (عبر ..، أو مسار مطلق في مكان آخر، أو symlink يقود إلى الخارج)، أو الـ root نفسه. لم يُكتب شيء. الحل: اكتب تحت الـ root، أو ابنِ الـ sandbox بالـ root الذي يجب أن يحتوي على الملف (new SubprocessSandbox({ root })؛ والافتراضي هو مجلد العمل وقت الإنشاء). راجع حواجز الحماية. مثال: sandbox.writeFile('/etc/profile.d/x.sh', ...) مع الـ root الافتراضي.

LOUSHO_SANDBOX_FAILED

المعنى: run من sandbox() / defineTool({ sandbox }) فشل عند حدّ الـ sandbox، لا في كود الأداة نفسها الذي تعود أخطاؤه كما هي. يسمّي kind في الـ SandboxError الحدّ المعني: 'timeout' (استغرق الـ run أكثر من timeoutMs)، أو 'oom' (أنهاه الـ driver بسبب سقف الذاكرة الخاص به — ومع driver 'isolate' قد يُسقط هذا عملية الـ host أيضًا، لأن الـ isolate حدّ تنفيذ لا حدّ أمان)، أو 'driver' (فشل الـ driver نفسه). ويحمل الـ tool span الـ kind نفسه بوصفه sandbox.error. الحل: ارفع memoryMb/timeoutMs، أو أصلح الـ driver؛ وإذا لم يكن isolated-vm مثبّتًا، فثبّت الـ peer الاختياري أو مرّر SandboxDriver آخر. مثال: sandbox({ driver: 'isolate', timeoutMs: 5_000 }) يشغّل كودًا لا يعود خلال خمس ثوانٍ.

مجلدات الـ agents والـ skills والـ flows

LOUSHO_AGENT_DIR_INVALID

المعنى: لم يتمكن loadAgentDir() (أو lousho dev وlousho build اللذان يستخدمانه) من تحميل مجلد: المجلد مفقود أو غير قابل للقراءة، أو ملف فارغ، أو ملف في tools/ لا يحتوي على export صالح، أو ملف إعدادات يفشل في الـ parse، أو مجلد sub-agent بنيته معطوبة. تسمّي الرسالة الملف. الحل: أصلح الملف الذي تسمّيه الرسالة. راجع مجلدات agent. مثال: loadAgentDir('./agents/support') وinstructions.md فارغ.

LOUSHO_SKILL_INVALID

المعنى: skill بنيتها غير صحيحة (defineSkill() أو مجلد skills/، ومنه loadSkills() على skill ملف الـ frontmatter الخاص بها غير صحيح)، أو تلقّى withSkills() أسماءً مكررة، أو اسم skill يتعارض مع الأداة load_skill أو read_skill_file. الحل: أعطِ كل skill اسمًا فريدًا ووصفًا ومحتوى؛ وأعد تسمية أي أداة اسمها load_skill. راجع Skills. مثال: defineSkill({ name: 'x', description: '', content: '...' }).

LOUSHO_FLOW_INVALID

المعنى: تعريف flow فيه خطأ: اسم input ناقص أو مكرر، أو اسم الـ flow أو كوده ناقص، أو node من نوع مجهول. الحل: أصلح الجزء الذي تسمّيه الرسالة من الـ flow. راجع Flows. مثال: استدعاءان لـ .input('city') على FlowBuilder واحد.

LOUSHO_FLOW_TOOL_DENIED

المعنى: لم تعمل خطوة toolCall في flow. رفضتها قاعدة صلاحيات أو سياسة needsApproval الخاصة بالأداة، أو يحتاج الاستدعاء إلى approval ورفضه الـ callback approve في سياق الـ flow، أو أرجع 'defer' (لا يستطيع الـ flow التوقف مؤقتًا)، أو لم يُمرَّر أصلًا. الحل: مرّر approve في سياق الـ flow لكي يحسم الاستدعاءات التي تحتاج approval، أو غيّر القاعدة التي رفضت الاستدعاء. راجع Flows. مثال: خطوة flow تستدعي أداة دفع عليها needsApproval: true، وتعمل دون callback approve.

LOUSHO_FLOW_CHANGED

المعنى: استُدعي FlowExecutor.resume() مع flow تغيّرت خطواته (أُضيفت، أو حُذفت، أو نُقلت، أو تغيّر نوع خطوة أو معرّفها أو الأداة أو الـ agent الخاص بها) منذ حفظ الـ run. تُحفظ الخطوات المكتملة بحسب موضعها في الـ flow، لذا كانت النتائج المحفوظة ستقع على خطوات خاطئة. أما الـ prompts وبقية الإعدادات فيمكن تغييرها بحرية. الحل: استأنف بإصدار الـ flow الذي بدأ الـ run، أو ابدأ run جديدًا تحت runId آخر. راجع Flows. مثال: run حُفظ بعد charge في [charge, notify]، واستُؤنف مع [audit, charge, notify].

الـ storage والنشر والتكاملات

LOUSHO_STORAGE_FAILED

المعنى: فشل التخزين: لم تُفتح قاعدة SQLite (يحتوي cause على خطأ الـ driver)، أو استُخدمت بعد close()، أو الـ schema الخاصة بها أحدث مما يعرفه هذا الـ SDK، أو node:sqlite مفقود؛ أو تجاوز ملف حدّ حجم التخزين؛ أو لم يُقرأ ملف fileStore() / FileSessionStore أو لم يُستبدل لأن handle آخر يُبقيه مفتوحًا (EPERM / EACCES / EBUSY على Windows لمدة أطول من ~1.3 ثانية التي يعيد فيها الـ store المحاولة؛ والـ cause هو آخر خطأ)؛ أو انتظر تغيير في fileMemory أكثر من 10 ثوانٍ ملف القفل <key file>.lock الخاص بكاتب آخر. الحل: تحقق من المسار والصلاحيات، واستخدم Node >= 22.13 مع SqliteStore (أو store مبنيًا على ملفات)، وأنشئ store جديدًا بعد إغلاق أي store. مثال: new SqliteStore('/read-only/agent.db').

LOUSHO_STORAGE_BUSY

المعنى: لم تتمكن كتابة في SqliteStore من الحصول على قفل الكتابة على قاعدة البيانات لأن اتصالًا أو عملية أخرى (replica أخرى، أو نسخة احتياطية، أو transaction طويلة) تحتفظ به. ينتظر الـ driver فترة قصيرة فقط (50 ms) لكي لا يتجمّد الـ event loop؛ وبعدها تعيد الكتابات الـ transactional في الـ stores (حفظ الـ checkpoints والـ approvals، وresolve()، وsaveIf()، وclaims تسجيل الدخول بـ OAuth، وتحديثات الـ memory في SQLite) المحاولة مع backoff لنحو 5 ثوانٍ قبل أن تستسلم بهذا الخطأ. لا يعيد prune() المحاولة. وخطأ الـ driver الأصلي هو الـ cause. الحل: أعد الاستدعاء. وإذا استمر حدوثه، فابحث عمّا يحتفظ بالقفل مدة طويلة. مثال: عمليتان تحفظان في agent.db نفسه وإحداهما تشغّل transaction تستغرق بضع ثوانٍ.

LOUSHO_TRIGGER_INVALID

المعنى: تلقّى trigger adapter خيارات غير صحيحة: cron adapter لا يحتوي على واحد بالضبط من intervalMs / cron، أو كتلة auth لـ webhook فيها secret فارغ أو نوع مجهول، أو trigger لـ Slack لا يستطيع التحقق من الطلبات. الحل: اتبع المثال الوارد في الرسالة. راجع القنوات والجداول الزمنية. مثال: webhookChannel({ auth: { type: 'hmac', secret: '' } }).

LOUSHO_CHANNEL_REQUEST_FAILED

المعنى: فشل استدعاء لـ API منصة محادثة (Slack أو Discord أو Telegram أو GitHub)؛ تسمّي الرسالة الاستدعاء وحالة HTTP أو خطأ المنصة. الحل: تحقق من token البوت وصلاحياته، ومن حالة المنصة. راجع القنوات. مثال: يردّ chat.postMessage في Slack بـ channel_not_found، أو يردّ sendMessage في Telegram بـ 400 لمحادثة مجهولة، أو يردّ POST /repos/{owner}/{repo}/issues/{number}/comments في GitHub بـ 403 لـ token ليست لديه صلاحية كتابة.

LOUSHO_DEPLOY_FAILED

المعنى: لم يتمكن lousho build / lousho dev / الـ node-server runtime من تحزيم الـ agent أو تشغيله: --agent ناقص، أو مسار الـ agent غير موجود أو ليس مجلد agent، أو فشل في التحزيم (import لا يُحل؛ ثبّته، أو اضبط LOUSHO_BUILD_VERBOSE=1 للحصول على السجل الكامل)، أو قيمة LOUSHO_STORE غير صحيحة، أو مصادر الـ runtime ناقصة، أو tool لا يدعمها هدف Cloudflare Worker. الحل: اتبع الرسالة. راجع النشر. مثال: lousho build --target node-server دون --agent.

LOUSHO_SERVER_UNPROTECTED

المعنى: طُلب من الـ node-server المبني (أو صورة docker) الاستماع على واجهة غير الـ loopback (localhost و127.x.x.x و::1) دون route auth: لا LOUSHO_API_TOKEN، ولا build token، ولا auth.ts. كان أي شخص يصل إلى هذه الواجهة سيستطيع استخدام الـ agent، لذا يرفض العمل. الحل: اضبط LOUSHO_API_TOKEN، أو أضف auth.ts إلى مجلد الـ agent، أو اربطه على 127.0.0.1 (HOST / --host). وإذا كنت تريد تقديم agent مفتوح عن قصد (شبكة خاصة، أو auth عند proxy أمامه)، فاضبط LOUSHO_ALLOW_PUBLIC=1. راجع النشر: المصادقة. مثال: docker run -p 3000:3000 lousho-agent دون -e LOUSHO_API_TOKEN=....

الاختبارات والـ evals

LOUSHO_EVALS_INVALID

المعنى: استُخدم مساعد eval بشكل خاطئ: defineEval() خارج vitest، أو t.judge() قبل t.send() أو دون judge، أو llmJudge() خارج الـ judge runner. الحل: اتبع الرسالة. راجع Evals. مثال: استدعاء t.judge('polite') قبل t.send('hi').

LOUSHO_DATASET_UNAVAILABLE

المعنى: لم يتمكن defineEval({ dataset: 'name' }) من جلب أمثلة الـ dataset من الـ observe daemon عندما جمع vitest الملف: LOUSHO_OBSERVE غير مضبوط، أو تعذّر الوصول إلى الـ daemon أو لم يردّ خلال 10 ثوانٍ، أو ردّ بخطأ (404 يعني أن الـ dataset لم يُعثر عليه)، أو لا يحتوي رده على examples، أو الـ dataset فارغ. عندئذ يفشل الـ eval كـ test واحد باسمه، فلا ينجح بالأخضر وهو لم يشغّل شيئًا. تسمّي الرسالة الـ dataset والـ URL الخاص بالـ daemon. الحل: شغّل الـ daemon (lousho observe) واضبط LOUSHO_OBSERVE على الـ URL الخاص به (وLOUSHO_OBSERVE_TOKEN لـ daemon يعمل بـ --require-token)، ثم أنشئ الـ dataset وأضف إليه أمثلة (POST /api/v1/datasets وPOST /api/v1/datasets/:name/examples). راجع Evals. مثال: lousho eval مع dataset: 'refunds' وLOUSHO_OBSERVE غير مضبوط.

LOUSHO_TEST_FAILED

المعنى: لم يتحقق فحص يُجريه مساعد test: لم ينجح eval، أو بقيت في سكربت mockModel() turns غير مستخدمة في النهاية. الحل: اقرأ الرسالة؛ أصلح الـ agent أو احذف الـ turns الزائدة من السكربت. راجع الاختبار. مثال: mockModel([...three turns]) وتوقف الـ agent بعد turnين.

LOUSHO_CASSETTE_INVALID

المعنى: cassette للـ record/replay مفقود، أو ليس JSON صالحًا، أو لا يطابق الطلب المسجّل. تسمّي الرسالة الملف. وعدم التطابق داخل run يصل إلى send() كـ CassetteMismatchError نفسه (من lousho/testing، مع .cassette و.callNumber) — فهو فشل في تجهيزات الاختبار، لذا لا يُضغط أبدًا في CompactedLLMProviderError. الحل: سجّله من جديد (lousho eval --record <file>، أو recordReplay() مع mode: 'record'). راجع الاختبار. مثال: lousho eval --replay لـ eval لم يُسجَّل أبدًا.

عام

LOUSHO_GENERIC_ERROR

المعنى: SDKError مبني دون code. الحل: اقرأ الرسالة؛ فهي تخبرك بما فشل. مثال: new SDKError('Something failed').

LOUSHO_AGENT_EXECUTION_FAILED

المعنى: AgentExecutionError: فشل تشغيل agent. الحل: افحص error.cause لسبب الفشل الأصلي. مثال: new AgentExecutionError('Agent failed', agentId, cause).

LOUSHO_FLOW_EXECUTION_FAILED

المعنى: FlowExecutionError: فشلت خطوة في flow. الحل: افحص error.step وerror.cause. راجع Flows. مثال: خطوة في flow رمى الـ agent الخاص بها خطأً.

LOUSHO_VALIDATION_FAILED

المعنى: ValidationError: لم يجتز الـ input الـ validation. الحل: أصلح الحقول المسرودة في error.errors. مثال: new ValidationError('Validation failed', { email: ['Invalid email'] }).

LOUSHO_OPERATION_TIMEOUT

المعنى: TimeoutError: لم تكتمل عملية (error.operation) ضمن error.timeoutMs. الحل: ارفع المهلة، أو اجعل العملية أسرع. مثال: خطوة flow فيها timeoutMs وتستغرق محاولتها أطول من ذلك (قيمة error.operation هي flow.node <type>).

LOUSHO_OUTPUT_INVALID

المعنى: محجوز. الرد غير الصالح في الـ structured output لا يُرمى حاليًا: ينتهي الـ run بـ finishReason: 'output-invalid' وoutputError. الحل: راجع Structured output. مثال: رد لا يطابق output: zodSchema بعد خطوة الإصلاح.

LOUSHO_BUDGET_EXCEEDED

المعنى: تجاوزت ميزانية limits الخاصة بـ run أو session (maxTokens أو maxCostUsd أو maxDurationMs وغيرها) الحدّ تحت onExceeded: 'throw'. يحمل BudgetExceededError الحقل budget: { limit, value, max, scope }. ومع الافتراضي onExceeded: 'stop' لا يُرمى شيء: ينتهي الـ run بـ finishReason: 'budget-exceeded'. الحل: ارفع الحدّ الذي تسمّيه الرسالة، أو احذف onExceeded: 'throw'. راجع الميزانيات. مثال: createAgent({ provider, limits: { maxCostUsd: 0.01, onExceeded: 'throw' } }) والـ run الخاص به يكلّف أكثر من سنت.

LOUSHO_GUARDRAIL_TRIPPED

المعنى: أوقف guardrail للـ input أو الـ output أو الـ tool run تحت onTripped: 'throw'. يحمل GuardrailError الحقل guardrail: { name, kind, reason, toolName? }. ومع الافتراضي onTripped: 'stop' لا يُرمى شيء: ينتهي الـ run بـ finishReason: 'guardrail'. الحل: افحص error.guardrail لتعرف أي guardrail أوقف الـ run ولماذا، أو احذف onTripped: 'throw'. راجع guardrails الـ input والـ output. مثال: createAgent({ provider, guardrails: { input: [maxLengthGuardrail({ maxChars: 10 })], onTripped: 'throw' } }) أُرسلت إليه رسالة أطول.

المصادقة

LOUSHO_AUTH_CONFIG_INVALID

المعنى: تلقّى مساعد route auth من lousho/auth (jwt() أو oidc() أو basic() أو apiToken()) خيارات لا يستطيع التحقق بها، فرفضها لحظة إنشائه، لا عند أول طلب. تسمّي الرسالة الخيار: لا مصدر للمفاتيح أو مصدران، أو secret HMAC أقصر من 32 بايت، أو خوارزمية لا تناسب المفتاح (secret مع RS256، أو مفتاح عام مع HS256)، أو لا audience (ولا allowAnyAudience: true)، أو clockToleranceSec أكبر من 300، أو URL لمجموعة مفاتيح أو issuer ليس https، أو قائمة مستخدمين أو token فارغ (ومنه createRouteHandler({ auth: '' }) وserveFetch(request, ctx, '')). الحل: غيّر الخيار الذي تسمّيه الرسالة. راجع Route auth والـ principals. مثال: jwt({ secret: process.env.JWT_SECRET! }) دون audience.

OAuth

LOUSHO_TOKEN_KEY_MISSING

المعنى: طُلب من store ملفات أو SQLite أو KV أن يخزّن OAuth token أو sign-in معلّقًا أو client مسجّلًا (أو أن يقرأ واحدًا موجودًا)، وليس لديه مفتاح للـ tokens: لم يُضبط الخيار tokenKey ولا متغير البيئة LOUSHO_TOKEN_KEY. لا تُخزَّن الـ tokens إلا مشفّرة، ولا يوجد مفتاح افتراضي. وقراءة سجلات غير موجودة لا تحتاج إلى مفتاح. الحل: ولّد مفتاحًا مرة واحدة بـ generateTokenKey() (32 بايت عشوائية بترميز base64)، وأبقِه سرّيًا، ومرّره كـ tokenKey أو اضبط LOUSHO_TOKEN_KEY. وعلى Cloudflare Workers أضفه بـ wrangler secret put LOUSHO_TOKEN_KEY. راجع تخزين الـ tokens. مثال: new SqliteStore('./agent.db').tokens.set('github', { owner: 'app' }, token) وLOUSHO_TOKEN_KEY غير مضبوط.

LOUSHO_TOKEN_DECRYPT_FAILED

المعنى: تعذّر فك تشفير سجل OAuth مخزّن: مفتاح الـ store ليس المفتاح الذي كُتب به، أو تغيّر السجل أو نُسخ إلى مالك آخر. تسمّي الرسالة الـ provider، ولا تسمّي الـ token أبدًا. الحل: استخدم المفتاح الذي كُتبت به الـ tokens. وأثناء الـ rotation ضع المفتاح القديم بعد الجديد (tokenKey: [newKey, oldKey]، أو LOUSHO_TOKEN_KEY="<new>,<old>"). وإذا ضاع المفتاح القديم، فاحذف السجل (tokens.delete(provider, owner)) وسجّل الدخول من جديد. راجع تخزين الـ tokens. مثال: ملف SqliteStore كُتب بـ tokenKey وفُتح بمفتاح آخر.

LOUSHO_OAUTH_PRINCIPAL_REQUIRED

المعنى: استدعت tool الدالة ctx.getToken() (أو requireAuth()) لـ provider تكون الـ credential الخاصة به لكل مستخدم (credentialOwner: 'user'، الافتراضي)، لكن الـ run بلا principal (هوية المستخدم)، فلا يوجد مستخدم يملك الـ token. يفشل الاستدعاء بهذا الخطأ؛ ولا يتوقف الـ run ولا يُنشأ رابط sign-in. الحل: قدّم الـ agent خلف route auth أو channel، لكي يكون لكل run principal (المصادقة)، أو عرّف الـ provider بـ credentialOwner: 'app' عندما تكون هناك credential واحدة للجميع. راجع أدوات تحتاج sign-in. مثال: agent.send('List my repositories') دون { principal }، مع tool تستدعي ctx.getToken(github).

LOUSHO_OAUTH_APP_SIGNIN_REQUIRED

المعنى: طلبت tool الـ credential الخاصة بالتطبيق نفسه (credentialOwner: 'app') ولا يوجد شيء مخزّن (أو سُحب). لا يصل مستخدمَ الـ chat رابطُ sign-in التطبيق أبدًا، لذا يفشل الاستدعاء بدلًا من أن يتوقف. الحل: سجّل دخول التطبيق مرة واحدة: افتح الـ URL الذي تُرجعه agent.oauth.signInUrl(provider) واترك الـ callback يخزّن الـ token. راجع credentials التطبيق. مثال: أداة post_update تستدعي ctx.getToken(slackBot) قبل أن يربط المشغّل Slack.

LOUSHO_OAUTH_STORE_MISSING

المعنى: استدعت tool الدالة ctx.getToken()، أو استُخدم agent.oauth، على agent بلا token store، فلا يوجد مكان يُقرأ منه token أو يُحفظ فيه. يتوقف الـ run بهذا الخطأ. ويحتاج سيرفر MCP على HTTP مع oauth إلى الـ store أيضًا: يفشل توصيله (ready()، أو connectMcp() دون tokens) بهذا الخطأ. الحل: مرّر createAgent({ store }) يحتوي على tokens: memoryStore() أو fileStore() أو SqliteStore أو KVStore (يحتاج الدائم منها إلى tokenKey). راجع تخزين الـ tokens. مثال: createAgent({ provider, tools: [listRepos] }) دون store.

LOUSHO_OAUTH_STATE_INVALID

المعنى: تلقّت agent.oauth.complete() (مسار /oauth/callback) قيمة state مجهولة، أو مستخدمة من قبل، أو أقدم من 10 دقائق، أو (مع طلب callback موثّق) sign-in بدأ لمستخدم آخر. يردّ المسار بـ 400. الحل: ابدأ من جديد برابط جديد: لا توافق على شيء، ودع الـ tool تطلب مرة أخرى (للتوقف الجديد رابط جديد)، أو استدعِ agent.oauth.signInUrl() من جديد لـ sign-in التطبيق. راجع مسار الـ callback. مثال: فتح redirect الـ provider نفسه مرتين، أو بعد 10 دقائق.

LOUSHO_SIGNIN_PENDING

المعنى: استُدعيت agent.approvals.resolve({ id, approved: true }) على توقف sign-in (kind: 'sign-in') قبل تخزين token المستخدم. يبقى التوقف كما هو. وعلى POST /chat/:id/approvals/:approvalId يكون هذا HTTP 409. الحل: افتح رابط الـ sign-in أولًا ودع الـ provider يوجّهك إلى الـ callback، ثم وافق مرة أخرى؛ أو وافق بـ false لإلغاء الاستدعاء. راجع ما يراه المستخدم. مثال: الضغط على “I’ve signed in” قبل اكتمال صفحة الـ provider.

LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED

المعنى: رفضت نقطة نهاية الـ token لدى الـ provider استبدال الـ authorization code (أو فشل طلب إليها)، أو وصل الـ callback دون code، أو لا يوجد provider معرّف في هذه العملية باسم الـ sign-in المعلّق. تسمّي الرسالة الـ provider وحالة HTTP وكود error الخاص بـ OAuth، ولا تسمّي الـ code ولا جسم الرد أبدًا. يردّ مسار الـ callback بـ 502. ولسيرفر MCP مع oauth تسمّي الرسالة السيرفر وكود error الخاص بـ OAuth. الحل: تحقق من tokenUrl وclientId وclientSecret وclientAuth، ومن أن redirectUri يطابق تمامًا ما هو مسجّل لدى الـ provider، ومن أن الوحدة التي تعرّف الـ provider محمّلة في العملية التي تخدم الـ callback. ثم سجّل الدخول من جديد. راجع مسار الـ callback. مثال: invalid_client من GitHub بعد تدوير سر العميل.

LOUSHO_MCP_AUTH_REQUIRED

المعنى: رفض سيرفر MCP على HTTP مع oauth الاتصال أو tool call لأن التطبيق ليس لديه token صالح له: لم يسجّل أحد دخول التطبيق بعد، أو سُحب الـ grant، أو تغيّر url السيرفر منذ الـ sign-in (لا يُرسل الـ token إلا إلى الـ url الذي أُخذ له). تصبح حالة السيرفر 'needs-auth'. عند التوصيل تفشل ready() (وconnectMcp()) بهذا الخطأ؛ وأثناء الـ run تكون نتيجة الـ tool call هي هذا الخطأ ويستمر الـ run. ولا يُطلب من مستخدم الـ chat أبدًا تسجيل الدخول لسيرفر MCP، ولا تحتوي الرسالة أبدًا على authorization URL. الحل: سجّل دخول التطبيق مرة واحدة: افتح الـ URL من agent.oauth.mcpSignInUrl('<server>') ودع الـ provider يوجّهك إلى مسار الـ callback. يستخدم الاتصال التالي أو الـ tool call التالي الـ token المخزّن. راجع سيرفرات MCP مع OAuth. مثال: createAgent({ mcpServers: { linear: { url, oauth: { redirectUri } } }, store }) وawait agent.ready() قبل أن يسجّل المشغّل الدخول.