halo-record

سجلات وقت تشغيل مقاومة للعبث لوكلاء الذكاء الاصطناعي: مسار تدقيق يشغّله البائع ولا يمكنه تعديله.

كل إجراء يقوم به وكيلك (استدعاءات الأدوات، استدعاءات النماذج، الوصول إلى البيانات، الموافقات) يصبح سجلًا واحدًا في سجلّ مترابط التجزئة ذي بنية إلحاقية. يمكن لأي طرف يحمل نقطة تفتيش للسلسلة أن يتحقق من أن السجلات التي خلفها لم تُعدَّل أبدًا، دون الحاجة إلى الثقة بمن أنتجها. عندما يسأل فريق الأمان لدى عميلك «ماذا فعل وكيلك ببياناتنا؟»، تمنحه رابطًا بدلًا من فقرة. مراجعات الأمان تطرح بالفعل أسئلة عن الذكاء الاصطناعي إلى جانب قائمة فحص SOC 2، وما زال الضمان المكتوب يُقبل اليوم. الرهان الذي يقوم عليه هذا المشروع هو أن ذلك لن يستمر طويلًا.

تنسيق السجل مفتوح ومجاني التنفيذ. هذه الحزمة هي التنفيذ المرجعي: المُسجِّل، والمُتحقِّق، وعميل الشاهد، وخادم التقارير.

لماذا يمكنك الوثوق بهذا الكود

يُطلب منك وضع مُسجِّل داخل وكيلك. لا ينبغي أن تتقبّل ذلك على أنه أمر مسلَّم به:

• صفر تبعيات لوقت التشغيل. مكتبة Python القياسية فقط. pip install halo-record يثبّت حزمة واحدة بالضبط.
• لا استدعاءات شبكة، باستثناء الشاهد، وهو اختياري ولا يتلقى سوى عدد السجلات وبصمة السلسلة. محتويات السجلات لا تغادر بنيتك التحتية أبدًا.
• المدخلات الخام لا تدخل السجل أبدًا. تُجزَّأ الوسائط وتُخزَّن فقط كملخص مُنقَّح — لا القيمة الخام أبدًا. التنقيح هو جهد بأفضل ما يمكن (regex على الصيغ الشائعة للأسرار والبيانات الشخصية PII): تعامل معه كدفاع متعمّق، لا كضمان.
• صغير بما يكفي لتدقيقه. نحو 4,300 سطر من Python. اقرأه كاملًا في أمسية.
• Apache-2.0.

عرض توضيحي في 60 ثانية

لا حاجة إلى وكيل. مع uv، لا شيء يستلزم التثبيت:

uvx --from halo-record halo demo --serve

أو بالطريقة التقليدية:

pip install halo-record
halo demo --serve

أيُّ الطريقتين يُنشئ هيكل موزّع وكيل دعم افتراضي بعميلين، ويشهد على السلاسل، ويقدّم تقارير وقت التشغيل المقيّدة (gated) لكل منهما، ويفتح لوحة تحكم المشغِّل في متصفحك. ثم جرّب اختبار العبث: احذف سطرًا من أحد ملفات .jsonl وأعد التحميل. التقرير سيلتقط ذلك.

سجّل وكيلك الخاص

سطر واحد عند الحدود:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

بدون log=، تُحفظ السجلات في ~/.halo/my-agent.jsonl (سلسلة واحدة لكل وكيل). أو استخدم المحوِّل لما تشغّله بالفعل (انظر الجدول أدناه). ثم اعرض التقرير:

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

ينتهي البدء السريع عندما ترى تقرير وقت التشغيل الخاص بوكيلك في المتصفح. إذا حصلت على ملف JSONL دون تقرير، فثمة خلل ما: افتح مشكلة (issue).

اربط بما تشغّله بالفعل

يحمل كل سجل وسم source، لذا يكشف التقرير كيف جُمعت كل قطعة دليل. السجلات الملتقطة والمستوردة تعيش في السلسلة نفسها.

أي شيء يُصدر OpenTelemetry GenAI spans (مثل CrewAI وLlamaIndex ومعظم أطر الوكلاء المزوّدة بأدوات OTel) يصل إلى السلسلة عبر محوّل OTel، وتأتي حزمة TypeScript مزوّدة بمحوّلات أصلية لـ Vercel AI SDK ولنظام الوكلاء في JavaScript. هل ينقصك محوّل لبيئتك التقنية؟ افتح مشكلة (issue). معظم المحوّلات نحو مئة سطر.

سجّل وكيل البرمجة الخاص بك

يُطلق Claude Code خطاف PostToolUse بعد كل استدعاء أداة. وجّهه إلى halo hook، فيصبح كل إجراء — كتابة ملفات، أوامر shell، استدعاءات موصلات MCP — سجلًا في سلسلة محلية. لا تغييرات في الكود؛ إدخال واحد في الإعدادات:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

أضف ذلك إلى ~/.claude/settings.json وستصبح السجلات في ~/.halo/audit.jsonl (يمكنك تجاوز ذلك عبر $HALO_LOG). تُتجاوز الأدوات الخالصة للتنسيق (orchestration) التي لا تلمس بيانات أو شبكة أو حالة خارجية — تسجّل السلسلة إجراءات حدود الثقة، لا التفكير. اضبط HALO_HASH_ONLY=1 لتسجيل تجزئات المحتوى دون ملخصات. اضبط HALO_AGENT_VERSION (واختياريًا HALO_AGENT_MODEL) لربط كل سجل بالبناء البرمجي للوكيل الذي أنتجه — عندما يسأل مدقّق عن الإصدار الذي كان يعمل في نافذة زمنية معينة، يجيب التصدير بالعمود بدلًا من الاعتماد على التذكُّر.

إذا احتجت التقرير ليجيب عن «تحت أي قواعد حدث هذا التشغيل؟»، اضبط HALO_AUTHORITY_FILE على لقطة JSON للسلطة الفعلية (effective authority) للجلسة. أبقِها آمنة للخصوصية: تجزئات ومراجع، لا المطالبات الخام، ولا نصوص السياسات الخاصة، ولا الأسرار، ولا مخططات الأدوات الكاملة.

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

تُختَم اللقطة في سلسلة التجزئة نفسها التي تضم سجلات الإجراءات. القيمة الافتراضية الجيدة هي لقطة واحدة على مستوى الجلسة في البداية، مع لقطة جديدة عند تغيّر القواعد أو المهارات (Skills) أو الخطافات أو سجلات أدوات MCP أو سياسة الضغط. لإبقاء الجلسات الطويلة خفيفة، تُضغط السجلات المتتالية ذات authority.snapshot_id نفسه بعد أول لقطة كاملة: تحتفظ السجلات اللاحقة فقط بـ {"snapshot_id": "...", "same_as_previous": true}. يبقى المؤشر مربوطًا بسلسلة التجزئة، لكن لا تتكرر كتلة refs/omissions/stale-if الضخمة في كل إجراء. ثم، كالمعتاد:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

أي بيئة تشغيل وكلاء تعرّض خطاف ما بعد الإجراء يمكنها تغذية الأمر نفسه — يقرأ الخطاف حدثًا واحدًا بصيغة JSON من stdin ويُلحق سجلًا واحدًا.

النزاهة مقابل الاكتمال (اقرأ هذا الجزء)

كن دقيقًا بشأن ما يثبته كل مستوى — لأنها ادعاءات مختلفة، والاختلافات هي جوهر الفكرة:

السلسلة المُمسكة ذاتيًا تثبت النزاهة بالنسبة إلى رأس مُرسّخ: ما دام هناك رأس سلسلة يمسكه شخص بالفعل، يصبح أي تعديل أو إعادة ترتيب أو حذف في السجلات التي خلفه قابلاً للاكتشاف. وبمفردها — قبل أن يرى أي شخص خارج نطاق المشغِّل رأسًا — تثبت السلسلة الاتساق الداخلي، لا التاريخ: يمكن لمشغِّل أن يُسقط سجلًا ويعيد الختم، وسيتحقق الملف الجديد. تصبح السلسلة ملتزمة تاريخيًا في اللحظة التي يغادر فيها رأسها سيطرة المشغِّل.

هذا هو الشاهد: طرف خارج نطاق المشغِّل يمسك بصمات دورية للسلسلة (عددًا وتجزئة رأس، لا شيء غير ذلك). نقاط التفتيش تجعل إعادة كتابة التاريخ الملتزم قابلة للاكتشاف، ونقطة التفتيش الفائتة بحد ذاتها حدث مرئي:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

حدود أخرى، بعبارة صريحة: لا السلسلة ولا الشاهد تثبت أن كل إجراء واقعي مرّ عبر المسجِّل. هذا هو اكتمال الالتقاط — وهي خاصية لموضع المسجِّل في الحزمة التقنية (الأدوات الأصلية، الخطافات، استيعاب البوابة)، وليست خاصية لأي تجزئة. تحمل السجلات وسم source لهذا السبب تحديدًا.

يمكن لأي شخص تشغيل شاهد. الشاهد الذي تشغّله بنفسك يُلزم التاريخ تجاه نفسك؛ أما إلزامه تجاه عميلك فيتطلّب شاهدًا لديه سبب للثقة به. البروتوكول مفتوح في الحالتين.

الشاهد المُستضاف والمعترف به هو السبيل الذي سيُبقي هذا المشروع مستدامًا. وصول مبكر: [email protected].

أين يقع هذا في حزمة الامتثال

halo-record هو طبقة أدلة، وليس شهادة اعتماد. إنه يُنتج الأثر الذي تطلبه أطر التقييم مرارًا بكلمات مختلفة:

• استبيانات الأمان ومراجعات SOC 2: أجب عن أقسام الذكاء الاصطناعي بتقرير وقت تشغيل قابل للتحقق بدلًا من لقطات الشاشة والنص الوصفي.
• AIUC-1: يُنتج التسجيل المقاوم للعبث (E015.4) وسجلات سلسلة التنفيذ الكاملة مع أحداث التفويض (E015.2) التي تتطلبها ضوابط المساءلة في المعيار — أدلة وقت تشغيل مستمرة، لا مُعاد بناؤها وقت التدقيق.
• OWASP (مشروع أمان GenAI): أدلة وقت التشغيل خلف مخاطر سلوك الوكلاء في OWASP Top 10 لتطبيقات الوكلاء 2026 وLLM Top 10 — اختطاف الأهداف، وإساءة استخدام الأدوات، وإساءة استخدام الهوية والصلاحيات — مُسجَّلة كما فعل الوكيل فعلًا، وبأي أدوات وبيانات.
• AARM (CSA): يُنتج إيصال الإجراء المقاوم للعبث الذي تحدده AARM (R5/R6) — مترابط السلسلة ومشهود عليه بشكل مستقل. halo-record هو طبقة الإيصال؛ اقرنه ببوابة إنفاذ لنظام AARM كامل. انظر AARM.md.
• ضوابط الثقة للوكلاء (Agentic Trust Controls): سجلات وقت التشغيل خلف ضوابط الأدلة في ATC — تسجيل الإجراءات المقاوم للعبث (RBM-03) وإثبات السلطة (AID-05) في سجل واحد مترابط، مع طبقة الشاهد خلفهما معًا. انظر ATC.md.
• قانون الذكاء الاصطناعي الأوروبي (EU AI Act): التزامات التسجيل وحفظ السجلات لأنظمة الذكاء الاصطناعي عالية الخطورة.
• ISO 42001 / NIST AI RMF: الأدلة التشغيلية خلف ضوابط نظام الإدارة.

لا يصدّق أيٌّ من هذا أي شيء بحد ذاته. إنه يمنح المقيِّم شيئًا قابلاً للتحقق لينظر إليه. الحدود — ما لا يفعله halo-record عمدًا، وماذا تقول عندما يسأل مراجع — موثقة في LIMITS.md.

CLI

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

نموذج النزاهة

لحساب تجزئة سجل: خذ السجل مستبعدًا integrity.hash، مع ضبط integrity.prev_hash على تجزئة السجل السابق؛ طبّعه باستخدام RFC 8785 (JSON Canonicalization Scheme)؛ ثم طبّق SHA-256 على البايتات. قيمة prev_hash للسجل الأول هي 64 صفرًا. يعيد التحقق حساب كل تجزئة ويفحص كل رابط. لا يُشترط أي سر؛ هذا هو جوهر الفكرة.

هل تظن أنك تستطيع العبث بسلسلة دون أن يلاحظ المُتحقِّق؟ المحاولات والنتائج هنا.

المرجع الكامل للحقول: halo-record.schema.json.

TypeScript

المسجِّل نفسه متاح لـ Node: halo-record-ts. نفس تنسيق السلسلة، نفس بروتوكول الشاهد. السجلات المكتوبة بأيٍّ من اللغتين تتحقق مع أيٍّ من المُتحقِّقين.

المساهمة

المشكلات (issues) والمناقشات وطلبات السحب (pull requests) مرحّب بها — انظر CONTRIBUTING.md للقواعد الأساسية (النسخة المختصرة: اختبارات مطلوبة، طلبات سحب صغيرة، تغييرات المخطط تُناقَش أولًا).

الترخيص

Apache-2.0