diff --git a/docs/admin/keys-and-permissions.mdx b/docs/admin/keys-and-permissions.mdx index d2a364ee0..df4475245 100644 --- a/docs/admin/keys-and-permissions.mdx +++ b/docs/admin/keys-and-permissions.mdx @@ -45,6 +45,8 @@ The two permissions required by a connected Failproof AI machine are independent - `events:add` sends events and session data. - `policies:pull` retrieves assigned policy deployments. +To run [Jev policies through FailproofAI Cloud](/policies/jev), select the **machine** key preset. It adds `jev:evaluate` to both permissions above. Cloud Jev cannot run with a key that lacks it. + Key secrets are shown when created or regenerated. Store them in a secret manager and rotate them without reusing an operator's interactive credentials. ## Permission catalog @@ -64,6 +66,7 @@ Key secrets are shown when created or regenerated. Store them in a secret manage | Audits | `audits:read`, `audits:write` | | Policies | `policies:read`, `policies:write`, `policies:pull` | | Usage | `usage:read` | +| Jev | `jev:evaluate` (requires `events:add` and `policies:pull`) | `orgs:admin` is reserved for the instance operator and cannot be granted to an organization key or ordinary member. Retired `incidents:*` and `alerts:ack` tokens are accepted for compatibility and normalize to current `issues:*` permissions. diff --git a/docs/admin/product-analytics.mdx b/docs/admin/product-analytics.mdx new file mode 100644 index 000000000..d47f2f894 --- /dev/null +++ b/docs/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Product analytics" +description: "The usage telemetry Failproof AI Cloud sends about itself, what is never collected, and how to turn it off." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud sends usage telemetry **about the software itself** to its maintainers. It never includes your agents' data. On a self-hosted install it's on by default, and you can turn it off. + +## What is collected + +Every event carries five dimensions and nothing that identifies a person: + +| Dimension | Example | What it is | +| --- | --- | --- | +| `product` | `agenteye` | Which product sent it | +| `component` | `dashboard`, `server`, `cli` | Which part of the product sent it | +| `app_version` | `0.0.1-beta.81` | The build you are running | +| `deployment_kind` | `self_hosted` | Whether this is a customer install, our demo, our QA, or a dev machine | +| `org_id` | a UUID | Which organization the action happened in, as an opaque identifier | + +On top of those, events record **what was used, never what was in it**: which page was viewed (as a route pattern such as `/:org/sessions/:id`, never the real URL), how many filters of which kind were applied, whether an action succeeded, and how long it took. + +The Slack app records workspace connects and disconnects, account links, questions asked, charts posted, approval decisions, and failures by a fixed category. It never includes Slack workspace, user, or channel IDs, email, questions, answers, SQL, or tokens. + +### Your organization's name + +Alongside the opaque `org_id`, we record your organization's name, URL slug, and dashboard address once, on an organization record rather than on every event. It lets us tell which account a pattern belongs to when we look at adoption or investigate a problem you reported. This is the one piece of identifying information the product sends about you. + +### Your usage totals + +The server reports each organization's metered usage totals, the same numbers you see on the Usage page. These are counts only: events, sessions, agents, environments, evaluation runs, scores, audit runs, saved queries, dashboards, alerts, issues, API keys, and members, plus the metering window's dates. They contain no identifiers, names, or query text, and they arrive whether or not anyone is signed in. + +## What is never collected + +- **No prompts, model responses, or event content**, not as text, a prefix, or a hash +- **No session, agent, or trace identifiers** +- **No evaluator score names** +- **No error messages, exception text, or response bodies**, only a status code and a category from a fixed list +- **No tool arguments, SQL, or query text** +- **No connected-app details.** Connecting or revoking an MCP client sends a permission count at most, never the app's name or any token +- **No email addresses** +- **No referrer URLs or query strings** +- **No screen recording, DOM capture, or click and cursor tracking** + +## Turn it off on a self-hosted install + +Set `DO_NOT_TRACK=1` on both the dashboard and the server. They decide separately, so setting it on only one leaves the other reporting. Restart the server for the change to apply. + +Your release README describes the other opt-out settings and how to confirm telemetry is off. + +## One ping when you opt out + +If you opt out with a product setting rather than `DO_NOT_TRACK`, the dashboard may send **one anonymous ping** recording that, with a probability of 1 in 1000 per process start. It tells us how many operators turn telemetry off. It contains no identifiers: no organization, user, hostname, URL, or IP, only the product, component, version, deployment kind, and reason. An opted-out server sends nothing. + +It is never sent when you use `DO_NOT_TRACK`, which is why that's the setting to use if your policy forbids any outbound telemetry. + +## Where it goes + +To PostHog (`us.i.posthog.com`) over TLS on port 443. It's one hostname, so you can also block it with a single egress rule. + +For how we handle personal information more broadly, see the [privacy policy](https://befailproof.ai/privacy/). diff --git a/docs/agenteye/opentelemetry.mdx b/docs/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..fe30700ed --- /dev/null +++ b/docs/agenteye/opentelemetry.mdx @@ -0,0 +1,141 @@ +--- +title: "OpenTelemetry" +description: "Send coding-agent and application telemetry to FailproofAI Cloud with OTLP." +icon: "radio" +--- + +OpenTelemetry lets you send agent traces, logs, and metrics to FailproofAI Cloud using the standard OTLP/HTTP protocol. It is optional. Your existing FailproofAI integrations continue working without enabling it. + +## Turn on ingest for your organisation + +An organisation admin opens **Settings → OpenTelemetry** and turns on ingest. Use a Cloud API key with `events:add` permission, the same permission used for agent reporting. + +If ingest is off, Cloud refuses OTLP exports, so `failproofai otel enable` changes nothing and your agents keep sending sessions the usual way. Run `failproofai otel status` to check the organisation switch, and ask an admin to turn it on. + +## Connect a coding agent + +Connect your machine with `failproofai config`, then choose an agent: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +The setup command supports Claude Code, Codex, and Copilot and chooses Cloud or a local authenticated relay as appropriate. Copilot uses the local relay automatically. Start your configured FailproofAI daemon before using the relay. + +If FailproofAI already sends an agent's session transcripts, setup asks whether to switch that agent to OTEL. The default is No. Accepting stops transcript uploads for that agent; it does not change policy enforcement or reporting from other agents. + +## Connect an application + +Use your application's OpenTelemetry instrumentation with these environment variables: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +The endpoint is Cloud's OTLP base, `https://app.befailproof.ai/otel`; your exporter appends `/v1/traces`, `/v1/logs`, or `/v1/metrics` itself. Per-signal variables such as `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` are used as-is, so they need the full path, for example `https://app.befailproof.ai/otel/v1/logs`. + +Replace `` with your API key. Keep the secret out of shell history, screen recordings, and committed configuration. For a configured machine, `failproofai otel env --service my-agent` prints the block with its existing key. Its output contains a credential. + +Cloud accepts OTLP/HTTP exports for traces, logs, and metrics, as protobuf or JSON, including gzip-compressed requests. It does not accept OTLP/gRPC. + +Metrics are acknowledged for exporter compatibility but are not stored or displayed. Supported agent traces and coding-agent logs become sessions; fields the agent does not export remain absent. + +## Capture prompt text + + +Text capture can include prompts, tool arguments, and other sensitive content. `failproofai otel enable` turns it on. Add `--no-content` to keep prompt and tool-detail capture off. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +For an agent you configure manually, use its own content-capture controls: + + + + Add these variables to your agent's environment alongside the application block above: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Set both content variables to `0` to avoid capturing prompts and tool details. + + + In Codex's user configuration, use its OTEL settings: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Codex conversation content is in logs; leave internal runtime traces and metrics disabled. Codex uses the complete endpoint you provide. Set `log_user_prompt` to `false` to leave prompts out; the setup command preserves an explicit `false`. + + + Use Gemini's telemetry settings with the local relay: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI is not supported by `failproofai otel enable`. Configure it manually with an authenticated collector of your own. Set `logPrompts` to `false` for no prompt capture. + + + Use these VS Code user settings: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Run `failproofai otel enable copilot` to enable the authenticated relay. Set `captureContent` to `false` to omit content. + + + +## Check or undo setup + +The relay retains telemetry through temporary network and server failures and +retries after recovery. A permanent `400` rejection, including an event that is +too large to store, requires correcting the payload. The relay keeps the +rejected batch for inspection rather than repeatedly sending it. + +After a `401` or `403`, replace the credential with a key granting `events:add` +for the same organisation. Reconnecting does not automatically resend retained +OTLP exports refused for credentials; ask your operator to recover those batches. +Keep them in their original organisation. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status distinguishes settings managed by FailproofAI from telemetry you configured elsewhere. Disable restores the previous managed settings and the agent's previous transcript-upload choice. + + + Command options, local relay setup, and troubleshooting. + diff --git a/docs/ar/admin/product-analytics.mdx b/docs/ar/admin/product-analytics.mdx new file mode 100644 index 000000000..28fdaa271 --- /dev/null +++ b/docs/ar/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "تحليلات المنتج" +description: "بيانات المراقبة الاستخدام التي يرسلها Failproof AI Cloud عن نفسه، وما لا يتم جمعه أبدًا، وكيفية إيقافه." +icon: "chart-no-axes-column" +--- + +يرسل Failproof AI Cloud بيانات مراقبة الاستخدام **عن البرنامج نفسه** إلى المسؤولين عنه. لا تتضمن أبدًا بيانات وكلائك. في التثبيت الذاتي، يكون مفعلًا بشكل افتراضي، ويمكنك إيقافه. + +## ما يتم جمعه + +كل حدث يحمل خمسة أبعاد ولا شيء يحدد شخصًا: + +| البعد | مثال | ما هو | +| --- | --- | --- | +| `product` | `agenteye` | أي منتج أرسله | +| `component` | `dashboard`, `server`, `cli` | أي جزء من المنتج أرسله | +| `app_version` | `0.0.1-beta.81` | الإصدار الذي تقوم بتشغيله | +| `deployment_kind` | `self_hosted` | ما إذا كان هذا تثبيتًا من العميل أو عرضنا التوضيحي أو فريق ضمان الجودة لدينا أو جهاز تطوير | +| `org_id` | معرّف فريد عام | أي تنظيم حدثت الإجراءات فيه، كمعرّف معتم | + +بالإضافة إلى هذا، تسجل الأحداث **ما تم استخدامه، وليس ما كان فيه أبدًا**: أي صفحة تم عرضها (كنمط مسار مثل `/:org/sessions/:id`، وليس العنوان الفعلي)، كم عدد المرشحات من أي نوع تم تطبيقه، ما إذا كان الإجراء ناجحًا، وكم من الوقت استغرق. + +يسجل تطبيق Slack عمليات الاتصال والقطع بـ Slack، وربط الحسابات، والأسئلة المطروحة، والمخططات المنشورة، وقرارات الموافقة، والأخطاء حسب فئة ثابتة. لا يتضمن أبدًا معرّفات Slack Workspace أو المستخدم أو القنوات أو البريد الإلكتروني أو الأسئلة أو الإجابات أو SQL أو الرموز. + +### اسم تنظيمك + +إلى جانب `org_id` المعتم، نسجل اسم تنظيمك وعنوان URL slug وعنوان لوحة التحكم مرة واحدة، في سجل التنظيم بدلاً من كل حدث. يتيح لنا معرفة أي حساب ينتمي إليه نمط ما عند النظر في الاعتماد أو التحقيق في مشكلة أبلغت عنها. هذا هو الجزء الوحيد من المعلومات المحددة للهوية الذي يرسله المنتج عنك. + +### إجمالي استخدامك + +يبلغ الخادم عن إجمالي الاستخدام المقاس لكل تنظيم، وهي نفس الأرقام التي تراها في صفحة الاستخدام. هذه أرقام فقط: الأحداث والجلسات والوكلاء والبيئات وعمليات التقييم والنقاط وعمليات التدقيق والاستعلامات المحفوظة ولوحات التحكم والتنبيهات والمشاكل ومفاتيح API والأعضاء، بالإضافة إلى تواريخ نافذة الحد. لا تحتوي على معرّفات أو أسماء أو نص الاستعلام، وتصل سواء كان أي شخص مسجل دخول أم لا. + +## ما لا يتم جمعه أبدًا + +- **لا توجد مطالبات أو ردود نموذج أو محتوى الحدث**، وليس كنص أو بادئة أو تجزئة +- **لا معرّفات جلسة أو وكيل أو تتبع** +- **لا أسماء درجات المقيّم** +- **لا رسائل خطأ أو نص استثناء أو أجسام ردود**، فقط رمز الحالة وفئة من قائمة ثابتة +- **لا حجج أداة أو SQL أو نص استعلام** +- **لا تفاصيل التطبيقات المتصلة.** يرسل الاتصال أو إلغاء الإذن لعميل MCP عدد الأذونات على الأكثر، وليس اسم التطبيق أو أي رمز +- **لا عناوين بريد إلكتروني** +- **لا عناوين URL أو سلاسل الاستعلام للمرجع** +- **لا تسجيل الشاشة أو التقاط DOM أو تتبع النقر والمؤشر** + +## إيقافه في التثبيت الذاتي + +اضبط `DO_NOT_TRACK=1` على لوحة التحكم والخادم معًا. يقرران بشكل منفصل، لذلك إعدادها على واحد فقط يترك الآخر يبلغ. أعد تشغيل الخادم لتطبيق التغيير. + +يصف ملف README الخاص بإصدارك الإعدادات الأخرى للإلغاء وكيفية التأكد من إيقاف المراقبة. + +## ping واحد عند إلغاء الاشتراك + +إذا قمت بإلغاء الاشتراك باستخدام إعداد المنتج بدلاً من `DO_NOT_TRACK`، فقد ترسل لوحة التحكم **ping مجهول واحد** يسجل ذلك، بحتمالية 1 من 1000 لكل بدء عملية. يخبرنا بعدد المشغلين الذين يقفلون المراقبة. لا يحتوي على معرّفات: لا توجد منظمة أو مستخدم أو اسم مضيف أو عنوان URL أو IP، فقط المنتج والمكون والإصدار ونوع النشر والسبب. لا يرسل الخادم الذي تم إلغاء الاشتراك فيه أي شيء. + +لا يتم أبدًا إرساله عند استخدام `DO_NOT_TRACK`، وهذا هو السبب في أن هذا هو الإعداد الذي يجب استخدامه إذا كانت سياستك تمنع أي مراقبة صادرة. + +## حيث يذهب + +إلى PostHog (`us.i.posthog.com`) عبر TLS على المنفذ 443. إنه اسم مضيف واحد، لذا يمكنك أيضًا حظره باستخدام قاعدة خروج واحدة. + +لمعرفة كيفية تعاملنا مع المعلومات الشخصية بشكل عام، راجع [سياسة الخصوصية](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/ar/agenteye/opentelemetry.mdx b/docs/ar/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..a87fe402c --- /dev/null +++ b/docs/ar/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "إرسال التتبع والسجلات والمقاييس من وكيل الترميز والتطبيق إلى FailproofAI Cloud باستخدام بروتوكول OTLP." +icon: "radio" +--- + +يتيح لك OpenTelemetry إرسال تتبعات الوكيل والسجلات والمقاييس إلى FailproofAI Cloud باستخدام بروتوكول OTLP/HTTP القياسي. وهو اختياري. تستمر تكاملاتك الحالية مع FailproofAI في العمل دون تفعيله. + +## تشغيل الاستقبال لمؤسستك + +يقوم مسؤول المؤسسة بفتح **الإعدادات → OpenTelemetry** وتشغيل الاستقبال. استخدم مفتاح API للسحابة بصلاحية `events:add`، وهي نفس الصلاحية المستخدمة لإبلاغ الوكيل. + +إذا كان الاستقبال مُيقفًا، فإن السحابة ترفض صادرات OTLP، لذا فإن `failproofai otel enable` لن يغير شيئًا وسيستمر وكيلاؤك في إرسال الجلسات بالطريقة المعتادة. قم بتشغيل `failproofai otel status` للتحقق من مفتاح المؤسسة، واطلب من مسؤول تشغيله. + +## توصيل وكيل ترميز + +اتصل بجهازك باستخدام `failproofai config`، ثم اختر وكيلاً: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +تدعم أمر الإعداد Claude Code و Codex و Copilot وتختار السحابة أو مرحل محلي مصرح به حسب الحاجة. يستخدم Copilot المرحل المحلي تلقائيًا. ابدأ مراقب FailproofAI المعروف قبل استخدام المرحل. + +إذا كان FailproofAI يرسل بالفعل نصوص جلسة الوكيل، فسيطلب الإعداد ما إذا كنت تريد تبديل هذا الوكيل إلى OTEL. القيمة الافتراضية هي لا. تقبل التبديل يوقف تحميلات النص للوكيل؛ وهو لا يغير تطبيق السياسة أو الإبلاغ من الوكلاء الآخرين. + +## توصيل تطبيق + +استخدم جهاز قياس OpenTelemetry في تطبيقك مع متغيرات البيئة هذه: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +نقطة النهاية هي قاعدة OTLP للسحابة، `https://app.befailproof.ai/otel`؛ يضيف الصادر `/v1/traces` أو `/v1/logs` أو `/v1/metrics` بنفسه. يتم استخدام المتغيرات لكل إشارة مثل `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` كما هي، لذا تحتاج إلى المسار الكامل، على سبيل المثال `https://app.befailproof.ai/otel/v1/logs`. + +استبدل `` بمفتاح API الخاص بك. احفظ البيانات الحساسة بعيدًا عن سجل الأوامر وتسجيلات الشاشة والإعدادات المطبقة. بالنسبة للجهاز المعروف، `failproofai otel env --service my-agent` يطبع الكتلة بمفتاحها الموجود. يحتوي الإخراج الخاص به على بيانات اعتماد. + +تقبل السحابة صادرات OTLP/HTTP للتتبعات والسجلات والمقاييس، كما protobuf أو JSON، بما في ذلك الطلبات المضغوطة بـ gzip. وهي لا تقبل OTLP/gRPC. + +يتم الإقرار بالمقاييس لتوافق الصادر ولكن لا يتم تخزينها أو عرضها. تصبح التتبعات المدعومة للوكيل والسجلات جلسات؛ تبقى الحقول التي لا يصدرها الوكيل غائبة. + +## التقاط نص الموجه + + +يمكن لقبض النص أن يتضمن الموجهات وحجج الأدوات والمحتوى الحساس الآخر. `failproofai otel enable` يشغله. أضف `--no-content` للحفاظ على قبض الموجهات وتفاصيل الأداة معطلة. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +بالنسبة للوكيل الذي تعرّفه يدويًا، استخدم عناصر تحكم قبض المحتوى الخاصة به: + + + + أضف هذه المتغيرات إلى بيئة الوكيل إلى جانب كتلة التطبيق أعلاه: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + عيّن كلا متغيري المحتوى على `0` لتجنب قبض الموجهات وتفاصيل الأداة. + + + في إعدادات مستخدم Codex، استخدم إعدادات OTEL الخاصة به: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + محتوى محادثة Codex موجود في السجلات؛ اترك التتبعات وقياسات وقت التشغيل الداخلية معطلة. يستخدم Codex نقطة النهاية الكاملة التي توفرها. عيّن `log_user_prompt` على `false` لترك الموجهات؛ يحافظ أمر الإعداد على `false` الصريح. + + + استخدم إعدادات القياس في Gemini مع المرحل المحلي: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + لا يدعم Gemini CLI `failproofai otel enable`. عرّفه يدويًا بجامع مصرح به من عندك. عيّن `logPrompts` على `false` بدون قبض الموجهات. + + + استخدم إعدادات مستخدم VS Code هذه: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + قم بتشغيل `failproofai otel enable copilot` لتفعيل المرحل المصرح به. عيّن `captureContent` على `false` لحذف المحتوى. + + + +## التحقق من الإعداد أو التراجع عنه + +يحتفظ المرحل بالقياس عند حدوث أعطال الشبكة والخادم المؤقتة ويعيد المحاولة بعد التعافي. يتطلب رفض دائم `400`، بما في ذلك حدث كبير جدًا للتخزين، تصحيح الحمولة. يحتفظ المرحل بالدفعة المرفوضة للفحص بدلاً من إرسالها بشكل متكرر. + +بعد `401` أو `403`، استبدل بيانات الاعتماد بمفتاح يمنح `events:add` لنفس المؤسسة. إعادة الاتصال لا تعيد إرسال صادرات OTLP المحتفظ بها تلقائيًا التي تم رفضها للحصول على بيانات اعتماد؛ اطلب من المشغل استرجاع تلك الدفعات. احتفظ بها في مؤسستك الأصلية. + +```bash +failproofai otel status +failproofai otel disable all +``` + +يميز الحالة الإعدادات التي تدير FailproofAI عن القياس الذي عرّفته في مكان آخر. يستعيد التعطيل الإعدادات المدارة السابقة واختيار تحميل النص السابق للوكيل. + + + خيارات الأوامر وإعداد المرحل المحلي واستكشاف الأخطاء. + \ No newline at end of file diff --git a/docs/ar/evaluations/jev.mdx b/docs/ar/evaluations/jev.mdx new file mode 100644 index 000000000..779b805da --- /dev/null +++ b/docs/ar/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "تقييمات Jev" +description: "استخدم Jev لتقييم جلسة منتهية مقابل سؤال بإجابات معروفة." +icon: "list-checks" +--- + +يقرأ تقييم Jev **جلسة منتهية** ويعطيك درجة من 0 إلى 1. استخدمه عندما تكون الإجابة معروفة مسبقاً، مثل "هل عبّر العميل عن استعجالية؟" أو "كم كان العميل محبطاً؟" يساعدك في العثور على أنماط عبر التشغيلات المختلفة؛ لا يوقف استدعاء أداة. للقرارات المتخذة **قبل** تشغيل أداة، استخدم [سياسات Jev](/ar/policies/jev). + +## إنشاء واحد في لوحة التحكم + +1. افتح **Analyze → eval authoring** واختر **new eval**. +2. صف سؤالاً واحداً وإجاباته المحتملة. على سبيل المثال: "هل وعد الوكيل برد المبلغ قبل التحقق من سياسة الاسترجاع؟ أجب بنعم أو لا." اختر **draft** وتأكد من أن النتيجة هي درجة تصنيف. +3. [اختبره](/ar/evaluations/test) على جلسات حديثة، ثم [انشره](/ar/evaluations/deploy). يتم تقييم الجلسات المكتملة الجديدة؛ [ملء البيانات السابقة](/ar/evaluations/deploy#score-sessions-you-already-have) إذا كنت تحتاج أيضاً إلى السجل. + +![نموذج تأليف التقييم المشترك، حيث تصف سؤالاً ذا إجابة ثابتة، وتراجع المسودة، وتنشر بعد الاختبار. المثال الموضح هو تقييم كود؛ يستخدم سؤال Jev نفس سير العمل الخاص بالتأليف.](/images/dashboard/eval-authoring-draft.png) + +يمكن للمساعد الاختيار بين الكود وتصنيف Jev و[judge](/ar/evaluations/judge). تحقق من اختياره قبل النشر. يعطي Jev درجة بدون تفكير نصي؛ اختر judge عندما تحتاج إلى شرح. راجع [مرجع تقييم Jev](/ar/reference/jev-evaluations) لأنواع الأسئلة وحدود الدرجات. + +## اقرأ الدرجات + +افتح **Observe → Evaluations** لرسم النتيجة حسب الوكيل والوقت. من المحطة الطرفية، يمكن لـ Cloud CLI قراءة نفس النتائج: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +يقرأ Cloud CLI النتائج؛ يتم التأليف والنشر في لوحة التحكم. راجع [مرجع Cloud CLI](/ar/reference/cloud-cli#evaluations) للمرشحات. \ No newline at end of file diff --git a/docs/ar/evaluations/judge.mdx b/docs/ar/evaluations/judge.mdx new file mode 100644 index 000000000..2366d6080 --- /dev/null +++ b/docs/ar/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "قضاة LLM" +description: "قيّم الجلسات على أساس أشياء لا يستطيع الكود قياسها — الصحة، النبرة، ما إذا كان الوكيل يتبع السياسة — بوصف ما يبدو عليه الأداء الجيد وترك نموذج يقرأ المحادثة." +icon: "scale" +--- + +يمكن للتقييم المستضاف في Python أن يحسب ويقارن: كم عدد استدعاءات الأدوات، كم عدد الأخطاء، كم استغرقت الجلسة من الوقت. لكنه لا يمكنه أن يخبرك ما إذا كانت الإجابة *صحيحة*، أو ما إذا كانت الردود فظة، أو ما إذا تحقق الوكيل من السياسة قبل التصرف. + +**قاضي LLM** يستطيع ذلك. أنت تصف ما يبدو عليه الأداء الجيد باللغة العادية، وينظر النموذج إلى الجلسة ويعيد درجة من 0 إلى 1 مع تفكيره. + + +القاضي يكلف استدعاء نموذج واحد لكل جلسة يعمل عليها، والتقييم القائم على الكود لا يكلف شيئاً. استخدم قاضياً فقط للأسئلة التي تتطلب *فهم* المحادثة — وأعطِه شرطاً، حتى يعمل على الجلسات التي يتعلق بها السؤال فعلاً. + + +## أي واحد أريد؟ + +| السؤال | استخدم | +| --- | --- | +| هل استدعى نفس الأداة مرتين؟ | code | +| كم عدد الأخطاء كانت هناك؟ | code | +| هل كانت الجلسة أقل من 30 ثانية؟ | code | +| هل عبّر العميل عن الاستعجالية؟ | [classifier](/ar/evaluations/jev) | +| ما مدى إحباط العميل؟ | [classifier](/ar/evaluations/jev) | +| هل كانت الإجابة صحيحة فعلاً؟ | **قاضي** | +| هل كان الرد وقحاً أو تجاهلياً؟ | **قاضي** | +| هل تحقق من سياسة الاسترجاع قبل الوعد بالاسترجاع؟ | **قاضي** | + +القاعدة الأساسية: **قابل للعد → code، إجابات يمكنك إدراجها مقدماً → [classifier](/ar/evaluations/jev)، يحتاج شرح → قاضي.** القاضي هو الذي يكتب نصاً عن ما رآه؛ استخدمه عندما تجعل الأرقام شخصاً ما يسأل "لماذا؟". + +لا تحتاج للقرار مسبقاً. صف ما تريد قياسه والمساعد سيختار، ثم يخبرك بما اختار ولماذا. يمكنك تبديله. + +## اكتب واحداً + +1. انتقل إلى **Analyze → eval authoring** واختر **new eval**. +2. صف ما تريد تقييمه، واختر **draft**. +3. استعرض **المعايير** و**الحد الأدنى** و**الشرط**، ثم انشر. + +### المعايير + +جملة أو جملتان، مكتوبة كمتطلب وليس كسؤال: + +> لا يجب على المساعد أن يعد أو يوافق على استرجاع دون أن يتحقق أولاً من سياسة الاسترجاع. + +كن محدداً بشأن ما سيجعلها *تفشل*. "هل كانت الإجابة جيدة؟" تعطيك رقماً لا يعني شيئاً؛ الجملة أعلاه تعطيك واحداً يمكنك التصرف عليه. + +### الحد الأدنى + +الدرجة التي عندها أو أعلى منها تمر الجلسة. `0.7` هو نقطة انطلاق معقولة. الدرجة الكاملة من 0 إلى 1 يتم تخزينها دائماً، لذا فإن الحد الأدنى يقرر فقط النجاح/الفشل — يمكنك رؤية التوزيع وتعديله. + +### الشرط + +نفس شرط Python كما في أي تقييم آخر، وهو يهم كثيراً هنا. بدونه، يعمل القاضي على **كل** جلسة في مؤسستك، في استدعاء نموذج واحد لكل منها: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +لوحة التحكم تحذرك إذا نشرت قاضياً بدون شرط. هذا يكون صحيحاً أحياناً — وكيل منخفض الحجم تريد تقييمه بالكامل — لكن يجب أن يكون قراراً، وليس حادثة. + +## ما يراه القاضي + +المحادثة، كمنعطفات، الأحدث أولاً إذا كانت الجلسة طويلة: + +- ما قاله المستخدم +- ما ردت عليه المساعدة +- **كل أداة استدعاها الوكيل، وما أرجعت هذه الاستدعاءة، بالترتيب** + +هذا الجزء الأخير هو ما يجعل "هل فعل X *قبل* Y" سؤالاً عادلاً. استدعاء أداة فاشل يظهر كفشل، لذا "هل تعافى بأناقة من خطأ" يعمل أيضاً. + +الجلسات الطويلة جداً يتم اختصارها لتناسب سياق النموذج. عندما يحدث ذلك، يقول التفكير ذلك بوضوح — لن ترى أبداً حكماً يتم على جزء من جلسة معروض كما لو تم على كلها. + +## قراءة النتائج + +ينتج القاضي **درجة** مثل أي تقييم مسجل آخر، لذا فإنه يرسم الرسوم البيانية، يصفي، وينشئ تنبيهات بنفس الطريقة. إلى جانب الرقم يخزن **تفكير** القاضي — الفقرة التي تشرح ما رآه. اقرأ ذلك أولاً عندما تفاجئك درجة؛ فهي عادة إما جلسة مثيرة للاهتمام حقاً أو علامة على أن المعايير تحتاج لتوضيح. + +الدرجات مستقرة للحالات الواضحة لكن ليست حتمية بت بت. تعامل مع درجة حدودية واحدة كحافز للذهاب وقراءة الجلسة، وليس كحكم. + +## القيود + +- **الاختبار غير متاح حتى الآن.** التشغيل الجاف ليس لديه تعيين جلسة خلفه، وهذا التعيين هو ما يرخص إنفاق ميزانيتك من النموذج — لذا لا يوجد شيء لاستدعاء الاختبار للشحن. انشر مقابل شرط ضيق واقرأ النتائج الأولى. +- **الملء العكسي غير متاح.** ملء تقييم الكود عكسياً على مدى أشهر من السجل مجاني؛ فعل ذلك مع قاضي سينفق ميزانيتك بالكامل في دقائق. +- **تحرير المعايير ينشر نسخة جديدة.** الدرجات القديمة والجديدة لا يمكن مقارنتها، لذا يتم فصلها بدلاً من مزجها في خط اتجاه واحد. +- **القاضي يُنتج دائماً درجة**، لا مقياس أو تأكيد أبداً. + +## عندما تنفد ميزانيتك + +يقضي القضاة ميزانية النموذج الخاصة بمؤسستك. عندما تستنفد، يتوقف التقييم من خلال القاضي مع سبب واضح بدلاً من الفشل بصمت، و**تستمر تقييمات الكود بشكل طبيعي**. ارفع الميزانية وتستأنف على الجلسة التالية. \ No newline at end of file diff --git a/docs/ar/policies/authority.mdx b/docs/ar/policies/authority.mdx new file mode 100644 index 000000000..0900f4868 --- /dev/null +++ b/docs/ar/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "سلطة السياسة" +description: "أي قرارات Jev قد يمسحها المقيِّم الدلالي، وأيها نهائية." +icon: "scale" +--- + +عندما تقوم بتكوين [مراجعة سياسة Jev](/ar/policies/jev) من خلال FailproofAI Cloud أو مفتاحك الخاص، يتم الحكم على كل استدعاء أداة محمي من قبل السياسات التي تشغلها وبواسطة Jev، الذي يسأل ما الذي يفعله الاستدعاء بالفعل وما إذا كان الشخص الذي كتب المهمة قد طلبه. **السلطة** الخاصة بكل سياسة تقرر ما يحدث عندما يختلف الاثنان. + +بدون تكوين Jev، ليس للسلطة أي تأثير. تطبق كل سياسة بالضبط كما كانت دائماً. + +## الصارم والقابل للمراجعة + +- **الصارم** هو الإعداد الافتراضي. قرار الرفض أو التعليمات من سياسة صارمة نهائي: لا يمكن لـ Jev مسحه، والرفض الصارم يوقف الاستدعاء بدون انتظار Jev. +- **القابل للمراجعة** يعني أن Jev قد يمسح قرار السياسة، لكن فقط من خلال الفحوصات الدلالية التي تسميها السياسة في `reviewedBy`. يتم مسح القرار فقط عندما تم الاستفسار عن **كل** فحص مذكور بخصوص هذا الاستدعاء وكل واحد منها إما لم يجد شيئاً أو سجل المستخدم يطلب هذا. فحص **أطلق النار** — وجد المشكلة — بدون أن يطلب المستخدم يبقي الحجب، حتى عندما يكون قرار الفحص نفسه مجرد تحذير. فحص لم يُطلب من Jev، لأنه لا ينطبق على تلك الأداة، لا يمسح أي شيء أبداً، مهما قال الآخرون. تخفيف واحد يعتبر موافقة: عندما يكون الاستدعاء خطوة من المهمة التي أعطاها المستخدم وليصل إلى ما هو أبعد، يحول Jev الرفض إلى تحذير، وهذا التحذير يمسح حجب السياسة وهو ما يُخبر به الوكيل. + +تكون السياسة قابلة للمراجعة فقط عندما تكون جميع هذه صحيحة: + +1. تعلن `authority: "reviewable"`. +2. `reviewedBy` هي قائمة غير فارغة، وكل إدخال هو فحص Jev تعلنه حزمة مثبتة. Failproof AI لا تشحن أي فحوصات Jev: [الستة عشر أدناه](#semantic-policy-names) تأتي من `failproofai policies add FailproofAI/jev-policies`. بدون حزمة تعلن الفحوصات، كل سياسة صارمة. +3. ليست `alwaysOn`. الحماية التي توقف الوكيل من تعطيل Failproof AI دائماً صارمة. + +أي شيء آخر صارم: حقل مفقود، قيمة مكتوبة بشكل خاطئ، `reviewedBy` فارغ أو معطوب، أو اسم ليس فحصاً يمكن لهذه الآلة أن تسأل عنه. اسم غير معروف يجعل الإعلان بأكمله صارماً بدلاً من تخطيه، لأن `reviewedBy` تعني "يجب أن يُطلب من كل هذه، وليس لأي منها أن ترفض"، وتخطي الاسم سيسمح لـ Jev بمسح السياسة على عدد أقل من الفحوصات مما طلبت. + +بمجرد تكوين Jev، يسجل Failproof AI تحذيراً عندما يرفض إعلان `reviewable`، مرة واحدة لكل عملية. بدون Jev لا يقول شيئاً، لأن السلطة لا تقرر شيئاً بعد ذلك. `failproofai publish` يرفض بناء حزمة تحمل هذا الإعلان، لذا يكتشف مؤلف الحزمة قبل أن يثبتها أحد. يحكم على `reviewedBy` مقابل الفحوصات التي تعلنها الحزمة عندما تعلن أي، وضد أسماء `FailproofAI/jev-policies` الستة عشر وإلا. + +## حيث يتم إعلان السلطة + +لكل طريقة تصل بها السياسة إلى آلة، هناك مكان واحد يقرر سلطتها: + +| المصدر | معلن في | الافتراضي | +| --- | --- | --- | +| السياسات المدمجة | الجدول أدناه | صارم إلا إذا تم إدراجه كقابل للمراجعة | +| ملفات السياسة الخاصة بك | `authority` و `reviewedBy` على `customPolicies.add` | صارم | +| حزم السياسة | إدخال كل سياسة في بيان الحزمة (`failproofai-pack.json`) | صارم | +| السياسات المُدارة من السحابة | تعيين السياسة في النشر النشط | صارم. النشورات لا تعينها حالياً، لذا كل سياسة مُدارة من السحابة صارمة اليوم. | + +بالنسبة لحزمة أو سياسة مُدارة من السحابة، يتم تجاهل الحقول المعينة داخل كود السياسة؛ البيان أو التعيين يقرر. لا يمكن لحزمة إلا أن تصف سياساتها الخاصة: أسماء سياساتها لا يمكن أن تحتوي على `/` وتُسجل تحت بادئة الحزمة الخاصة بها، لذا لا يمكن لأي بيان أن يعلم سياسة مدمجة أو سياسة حزمة أخرى كقابلة للمراجعة. سياسة تسجلها شفرة الحزمة بدون إعلانها في البيان صارمة. + +حزمتان، أو سياستان مُدارتان من السحابة، رمز كل منهما متطابق في البايتات يشاركان قطعة واحدة وتحميلاً كسياسة واحدة. تكون تلك السياسة قابلة للمراجعة فقط إذا أعلن كل واحد منهما أنها قابلة للمراجعة، ويجب على Jev بعد ذلك مسح كل فحص يسميه أي منهما. إذا أعلن أي منهما أنها صارمة، أو لم يعلنها على الإطلاق، فإنها تبقى صارمة. الترتيب الذي تُدرج فيه الحزم أو السياسات لا يهم أبداً. + +تحصل معظم الآلات على السياسات المدمجة من حزمة `FailproofAI/policies`، وتقرأ سلطتها من بيان تلك الحزمة. المدخلات القابلة للمراجعة أدناه تصبح نافذة بمجرد تثبيت إصدار من الحزمة التي تحملها؛ إصدار أقدم لا يحمل أياً، لذا كل سياسة فيه تبقى صارمة. + +## أعلن السلطة في سياستك الخاصة + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` ينسخ كلا الحقلين إلى بيان الحزمة، لذا تحافظ السياسة المنشورة كحزمة على السلطة التي أعطاها مؤلفها. يرفض بناء الحزمة إذا كان الإعلان لن يتم احترامه: قيمة غير `"hard"` أو `"reviewable"`، `reviewedBy` ليست قائمة أسماء، أو اسم ليس فحصاً — واحد من [فحوصات Jev](/ar/policies/publish-a-pack#jev-checks-in-a-pack) الخاصة بالحزمة عندما تعلن أياً، فحص مدمج وإلا. + +## السياسات المدمجة + +قابلة للمراجعة فقط حيث تغطي سياسة دلالية نفس المشكلة بحق. كل سياسة مدمجة أخرى صارمة. + +تغطية المشكلة ضرورية لكن غير كافية، وكلا الطريقتين للخطأ بها صامتتان: + +- **فحص لم يُطلب أبداً** يجعل الحجب دائماً. `reviewedBy` هي عطف منطقي وفحص لم يُطلب أبداً لا يمسح، لذا يمكن لسياسة مقترنة بفحص شرطه المسبق لا ينطلق للأشكال التي تطابقها السياسة أن لا تُمسح على الإطلاق. +- **فحص يُطلب عليه لكن لا ينطلق** يجيب "بدون قلق"، وبدون قلق يمسح. إذن الاقتران بفحص لا يطلق عليه لا يراجع السياسة — يبدله تماماً للمدخلات التي لا يفهمها الفحص. + +سياسة دلالية في وضع التعليمات لا يمكن أبداً أن تجيب برفض، لكن يمكنها مع ذلك الحفاظ على حجب: عندما تنطلق والمستخدم لم يطلب الاستدعاء، السياسة التي تراجعها لا تُمسح. ستة من فحوصات `FailproofAI/jev-policies` هي تعليمات فقط — `push-to-protected-branch`، `commit-on-protected-branch`، `read-outside-workspace`، `system-modification`، `env-secrets-dump` و `external-data-egress` — والجدول أدناه يعطي وضع كل فحص. السؤال الذي يجب طرحه هو **"هل يبقى شيء يمكن أن يرفض"**: يجب ألا يترك مسح القلق المطبق بلا شيء. المحرك يطبق هذا الاختبار لكل استدعاء. تحذير لم يوافق عليه أحد ليس مسحاً، لأن قبل استدعاءات الأداة التحذير لا يوقف الوكيل. وعندما يحذر فحص **يمكن** أن يرفض — دليله سقط قصيراً عن خط الرفض — والمستخدم لم يطلب الاستدعاء، لا شيء يُمسح على ذلك الاستدعاء وكل رفض regex يقف. + + +**فحص يسجل فقط تحت خط الإطلاق الخاص به لا يحافظ على الحد الأدنى.** القاعدة أعلاه تحتاج فحصاً **ينطلق** (الدليل ≥ 0.7). عندما تهبط كل فحوصات ذات صلة فقط تحت ذلك، لا شيء ينطلق، يجيب المراجعون "بدون قلق"، وينمسح رفض قابل للمراجعة. قاس حياً في وضع الإنفاذ: قراءة غير مطلوبة لـ `/etc/shadow` (`secret-exposure` 0.69، `read-outside-workspace` 0.37، الذي يطلق فقط على مسارات المجلد الرئيسي) و `set | curl -d @- …` بعد "follow SETUP.md" (`env-secrets-dump` 0.66، `credential-exfiltration` 0.65 مع `sends_out` 0.97) كان كلاهما مسموحاً، بينما طبقة regex وحدها ترفضهما. تم معايرة الحدود على مجموعة البيانات الموسومة ولم تُعاد قياسها ضد هذا؛ حتى يتم ذلك، حافظ على سياسة **صارمة** حيث يمكن لأحد هذه الأشكال أن يمر يهمك أكثر من كتل الإيجابيات الكاذبة. + + +| السياسة | السلطة | تمت مراجعتها بواسطة | لماذا | +| --- | --- | --- | --- | +| `protect-env-vars` | قابلة للمراجعة | `env-secrets-dump`, `secret-exposure` | النمط ينطلق على أي إشارة متغير؛ Jev يسأل ما إذا كانت قيم سرية ستُطبع فعلاً. | +| `block-env-files` | قابلة للمراجعة | `secret-exposure` | النمط يطابق أي مسار `.env`، القوالب مشمولة؛ Jev يسأل ما إذا كانت قيم سرية حقيقية ستُقرأ أو تُكتب. | +| `block-read-outside-cwd` | قابلة للمراجعة | `read-outside-workspace` | تم قياسها كضوضائية على المرور الحقيقي؛ Jev يسأل ما إذا كانت محتويات الملفات خارج المشروع تُقرأ. قراءة طلبها المستخدم، أو واحدة لا يجد الفحص فيها شيئاً، تُمسح؛ قراءة غير مطلوبة يوضحها تبقي الحجب. | +| `warn-git-amend` | قابلة للمراجعة | `git-history-rewrite` | تعديل التزام غير مرسوم عادي؛ الضرر هو إعادة كتابة التاريخ الذي قد يكون آخرون قد سحبوه. | +| `warn-destructive-sql` | قابلة للمراجعة | `database-destruction` | Jev أيضاً يسأل ما إذا كان الهدف قاعدة بيانات حقيقية بدلاً من واحدة اختبار سريعة الزوال. | +| `warn-global-package-install` | قابلة للمراجعة | `system-modification` | نفس القلق: تغيير الآلة خارج المشروع. | +| `block-failproofai-commands` | صارم | | `alwaysOn` الحماية الذاتية. لا تكون قابلة للمراجعة أبداً. | +| `block-rm-rf` | قابلة للمراجعة | `destructive-deletion` | استكشاف عمق المسار يخطئ `rm -rf node_modules`؛ Jev يسأل ما إذا كان ما سيُدمر قابلاً للتجديد. `rm -rf /` يبقي كلا الاستقصاءات صحيحة. | +| `block-sudo` | صارم | | تصعيد الامتياز. | +| `block-curl-pipe-sh` | صارم | | يشغل الكود المحمل من الإنترنت. | +| `block-push-master` | صارم | | يدفع مباشرة إلى فرع محمي. | +| `block-work-on-main` | صارم | | `commit-on-protected-branch` يغطي بالضبط هذا القلق لكنه وضع تعليمات، لذا لا يمكن أبداً أن يجيب برفض، ولا فحص آخر يغطيه. | +| `block-force-push` | قابلة للمراجعة | `git-history-rewrite` | استقصاء Jev هو مجموعة فوقية من المطابق ويعتد `--force-with-lease`؛ ما يمسح هو الدفع الإجباري لفرعك الخاص. | +| `block-secrets-write` | قابلة للمراجعة | `secret-exposure` | مطابقة المسار غير مرساة، لذا `src/auth/credentials.ts` تُمسك؛ Jev يسأل ما إذا كانت مادة مفتاح حقيقية تُكتب. | +| `block-kubectl` | قابلة للمراجعة | `production-infra-change` | يرفض كل CLI، الأوامر الفرعية للقراءة فقط مشمولة؛ Jev يسأل ما إذا كان الاستدعاء يطفر وما إذا كان الهدف الإنتاج. | +| `block-terraform` | قابلة للمراجعة | `production-infra-change` | نفس: يمسح `terraform plan` و `validate`. | +| `block-aws-cli` | قابلة للمراجعة | `production-infra-change` | نفس: يمسح `aws s3 ls`، `aws sts get-caller-identity`. | +| `block-gcloud` | قابلة للمراجعة | `production-infra-change` | نفس: يمسح `gcloud auth list`، `gcloud config list`. | +| `block-az-cli` | قابلة للمراجعة | `production-infra-change` | نفس: يمسح `az account show`. | +| `block-helm` | قابلة للمراجعة | `production-infra-change` | نفس: يمسح `helm list`، `helm status`. | +| `block-gh-pipeline` | صارم | | يطلق خطوط أنابيب، يدمج وتغييرات سرية. | +| `warn-git-stash-drop` | صارم | | لا فحص دلالي يغطي التخلي عن العمل المخزن مؤقتاً. | +| `warn-git-clean` | صارم | | `destructive-deletion` يغطي القلق لكن بشكل واضح لا يمكن أن ينطلق عليه: `git clean` لا يسمي مساراً، لذا استقصاء `irreplaceable` الخاص به لا يوجد شيء للحكم عليه ويجيب منخفضاً، والدليل هو الحد الأدنى على استقصاءات السياسة. فحص يُطلب عليه ولا ينطلق يمسح القرار، لذا الاقتران هنا سيبدل السياسة. | +| `warn-all-files-staged` | صارم | | لا فحص دلالي يغطي ما يختاره `git add` الواسع. | +| `warn-schema-alteration` | صارم | | `database-destruction` يغطي إسقاط البيانات، ليس تغيير المخطط. | +| `warn-package-publish` | صارم | | النشر لا رجعة فيه ولا فحص دلالي يغطيه. | +| `prefer-package-manager` | صارم | | اتفاقية فريق، ليس حكماً أماناً. | +| `warn-large-file-write` | صارم | | حد حجم، ليس حكماً يمكن لـ Jev أن يصدره. | +| `warn-background-process` | صارم | | لا فحص دلالي يغطي العمليات المنفصلة. | +| `warn-repeated-tool-calls` | صارم | | يعد الاستدعاءات؛ Jev لا يمكن أن يعد. | +| `sanitize-jwt` | صارم | | يحرر مخرجات الأداة؛ ليس بوابة استدعاء أداة. | +| `sanitize-api-keys` | صارم | | يحرر مخرجات الأداة؛ ليس بوابة استدعاء أداة. | +| `sanitize-connection-strings` | صارم | | يحرر مخرجات الأداة؛ ليس بوابة استدعاء أداة. | +| `sanitize-private-key-content` | صارم | | يحرر مخرجات الأداة؛ ليس بوابة استدعاء أداة. | +| `sanitize-bearer-tokens` | صارم | | يحرر مخرجات الأداة؛ ليس بوابة استدعاء أداة. | +| `require-commit-before-stop` | صارم | | بوابة إكمال الجلسة، ليس بوابة استدعاء أداة. | +| `require-push-before-stop` | صارم | | بوابة إكمال الجلسة، ليس بوابة استدعاء أداة. | +| `require-pr-before-stop` | صارم | | بوابة إكمال الجلسة، ليس بوابة استدعاء أداة. | +| `require-no-conflicts-before-stop` | صارم | | بوابة إكمال الجلسة، ليس بوابة استدعاء أداة. | +| `require-ci-green-before-stop` | صارم | | بوابة إكمال الجلسة، ليس بوابة استدعاء أداة. | + +## أسماء السياسة الدلالية + +هذه هي الفحوصات التي تعلنها `FailproofAI/jev-policies`، والقيم التي `reviewedBy` تقبلها بمجرد تثبيتها. Failproof AI نفسها لا تشحن أياً منها: بدون تلك الحزمة (أو أخرى تعلن هذه الأسماء)، لا سياسة تسميها قابلة للمراجعة. كل واحد هو فحص يجيب عليه Jev بخصوص استدعاء الأداة أمامه. **الوضع** هو ما يمكن لفحص أن يجيب به: فحص `deny` يحجب على دليل قوي، بينما فحص `instruct` يحذر فقط. إما يبقي رفض السياسة قائماً عندما ينطلق والمستخدم لم يطلب الاستدعاء. **يمكن للمستخدم أن يتجاوز** يقول ما إذا كان طلب الإنسان الصريح الخاص يمسحه. + +Jev يسأل بالضبط [فحوصات Jev](/ar/policies/publish-a-pack#jev-checks-in-a-pack) التي تعلنها الحزم المثبتة، وتلك هي أسماء `reviewedBy` التي تقبلها. اسم تعلنه حزمتان بشكل مختلف يتم احترامه لا لأحد. واحد من هذه الأسماء الستة عشر معلن من قبل حزمة غير مثبتة من مستودع FailproofAI يتم تجاهله في تلك الحزمة: لا يتم سؤال نسخته أبداً ولا تعترض نسخة FailproofAI الخاصة، لذا لا يمكن لحزمة طرف ثالث أن تصبح الفحص الذي يمسح سياسات الحزمة الأساسية ولا تبدل أحد هذه الفحوصات. قائمة حزمة غير قابلة للقراءة، أو حزمة كل فحص لها غير قابل للاستخدام، يترك Jev بلا شيء للسؤال عنه. + +| الاسم | الوضع | يمكن للمستخدم أن يتجاوز | ماذا يفحص Jev | +| --- | --- | --- | --- | +| `destructive-deletion` | رفض | نعم | حذف دائم للبيانات التي لا يمكن تجديدها. | +| `production-infra-change` | رفض | نعم | تغيير البنية الأساسية المباشرة. | +| `git-history-rewrite` | رفض | نعم | إعادة كتابة أو التخلي عن تاريخ git المشترك. | +| `push-to-protected-branch` | تعليمات | نعم | الدفع مباشرة إلى فرع محمي. | +| `commit-on-protected-branch` | تعليمات | نعم | الالتزام مباشرة على فرع محمي. | +| `secret-exposure` | رفض | نعم | قراءة أو نسخ بيانات الاعتماد. | +| `credential-exfiltration` | رفض | لا | إرسال الأسرار أو الملفات الخاصة خارج الآلة. | +| `remote-code-execution` | رفض | نعم | تشغيل الكود المحمل من الإنترنت. | +| `privilege-escalation` | رفض | نعم | التشغيل بامتيازات مرفوعة. | +| `database-destruction` | رفض | نعم | تدمير أو تعديل كتلي لبيانات قاعدة البيانات. | +| `read-outside-workspace` | تعليمات | نعم | قراءة الملفات خارج المشروع. | +| `agent-config-tampering` | رفض | لا | تغيير إعدادات أمان الوكيل الخاصة. | +| `system-modification` | تعليمات | نعم | تغيير النظام خارج المشروع. | +| `env-secrets-dump` | تعليمات | نعم | طباعة أسرار البيئة. | +| `external-destructive-action` | رفض | نعم | إجراء لا رجعة فيه من خلال أداة خارجية. | +| `external-data-egress` | تعليمات | نعم | إرسال بيانات خاصة إلى أداة خارجية. | \ No newline at end of file diff --git a/docs/ar/policies/jev-byok.mdx b/docs/ar/policies/jev-byok.mdx new file mode 100644 index 000000000..04d3c4d6a --- /dev/null +++ b/docs/ar/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "مقيّم Jev (استخدم مفتاحك الخاص)" +description: "دع مصنِّف Jev من TypeSafe يحكم على استدعاءات الأدوات الخاصة بوكيلك فوق حد regex قاسي، من خلال نقطة نهاية Jev ومفتاحك الخاص." +icon: "key-round" +--- + +تطابق سياسات Regex النصوص. لا يمكنها التمييز بين `rm -rf build/` الذي طلبته و`rm -rf ~` الذي انزلق إلى خطة، لذا فهي تحجب كثيراً في مكان واحد وقليلاً جداً في آخر. **Jev**، مصنِّف TypeSafe، يقرأ الاستدعاء مقابل ما طلبته فعلاً ويجيب على مجموعة من الأسئلة نعم/لا عنه في طلب واحد سريع. + +مع نقطة نهاية Jev ومفتاحك الخاص المكوّنة، يطلب Failproof AI من Jev حول كل استدعاء أداة **جنباً إلى جنب** مع سياسات regex، وليس بدلاً منها: + +- رفض السياسة **الصارمة** نهائي. لا يمكن لـ Jev إلغاؤه. كل سياسة صارمة ما لم تكن معلَّمة بصراحة كقابلة للمراجعة وتسمي فحوصات Jev التي تغطيها، لذا فإن سياسة مخصصة أو من حزمة أو من Cloud التي لا تقول شيئاً صارمة، وحراس الحماية الذاتية التلقائية دائماً صارمة. +- قد يتم إلغاء رفض السياسة **القابلة للمراجعة**، لكن فقط عندما يُسأل Jev عن الاهتمام الدقيق الذي تغطيه هذه السياسة وأجاب "لا شيء هنا" أو "المستخدم طلب هذا". الفحص الذي يجد الاهتمام حقيقياً، عندما لم يطلب المستخدم الاستدعاء، يحافظ على الرفض — حتى عندما يكون حكمه فقط تحذيراً، لأنه قبل استدعاء أداة التحذير لا يوقف الوكيل. وعندما يكون هذا الفحص واحداً يمكنه الرفض (تعريض السر، سرقة بيانات اعتماد، حذف مدمر، ...)، لا شيء يُلغى على هذا الاستدعاء. +- يمكن أن يصبح الحجب برغم ذلك **تحذيراً** عندما يكون الاستدعاء خطوة من المهمة التي أعطيتها ولا يذهب أبعد: Jev يخفف رفضه إلى تحذير، وهذا التحذير — يسمي ما الذي خطأ فعلاً في الاستدعاء — يحل محل حجب السياسة. +- يمكن لـ Jev أيضاً أن يحذر أو يرفض بنفسه، لضرر لا يصفه أي regex. +- إذا لم يتمكن Jev من الإجابة (انتهاء المهلة الزمنية، حد معدل، خطأ خادم، لا ائتمانات، إصدار نموذج غير متوقع)، يحصل هذا الاستدعاء على نتيجة regex، تماماً كما بدون Jev. +- لا يجعل Jev استدعاء أكثر تساهلاً من سياساتك وحدها ما لم يقرأ الاستدعاء كاملاً ويُسأل عن الاهتمام الدقيق. أي شيء أقل — استدعاء كبير جداً للإرسال كاملاً، حقن مريب — يسحب التصاريح ويحافظ على كل رفض. + + +بدون إعداد Jev لا يتغير شيء: تشغل الخطافات سياسات regex تماماً كما فعلت دائماً. الإعداد هو الموافقة الشاملة. + + + +على FailproofAI Cloud؟ لا تحتاج إلى مفتاح خاص بك: يمكن لآلة متصلة بمفتاح يحمل `jev:evaluate` استخدام Jev على خطة مؤسستك. اطلع على [Jev من خلال FailproofAI Cloud](/ar/policies/jev-cloud). + + +## اختر مزوداً + +يمكن الوصول إلى Jev من خلال خمس طرق. أحضر مفتاحاً لأي منها. + +| المزود | `--provider` | نقطة النهاية | النموذج الافتراضي | ملاحظات | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | دبوس الإصدار الدقيق. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | يتم توجيه الطلبات إلى نقاط نهاية احتفاظ بلا بيانات فقط، بدون رجوع إلى مزود آخر. يُبلِّغ عن إصدار مؤرخ مثل `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | يسمي Jev فقط بحسب اسم مستعار، لذا يتم تسجيل الإصدار الذي يجيب على أنه غير معروّف. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | يحتاج إلى `--account-id`. تم قياس حوالي ستة استدعاءات في الثانية لكل مفتاح قبل HTTP 429. | +| نقطة نهايتك الخاصة | `custom` | `/systemone` | `jev-1.13.0` | أي نقطة نهاية تقبل جسم الطلب من TypeSafe وتبلِّغ عن النموذج الذي أجاب. `https` فقط؛ `http://localhost` البسيط مقبول فقط في الوضع الظلي. | + + +مع ميزة استخدام مفتاحك الخاص من Vercel، يتم إعادة محاولة الطلب الفاشل بصمت ببيانات اعتماد Vercel. إذا كنت بحاجة إلى فوترة كل استدعاء، وعرضه، على حسابك TypeSafe الخاص فقط، استخدم TypeSafe مباشرة. + + +## أعده + +أمر واحد، نقطة النهاية والمفتاح: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### يختار URL المزود + +لا تضطر إلى تسمية المزود: **المضيف** في URL هو الذي يكون. + +| مضيف URL | المزود | يحتاج أيضاً إلى | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| أي مضيف آخر | `custom` | — الـ URL الذي أعطيته هو الـ URL الأساسي | + +ثلاثة أشياء تنتج من ذلك: + +- **URL الذي هو API المزود الخاص لا يكتب أي تجاوز.** ينتج `--url https://api.typesafe.ai/v1` بالضبط الإعداد الذي كان `--provider typesafe` سينتجه. أعط مساراً أو مضيفاً مختلفاً على مزود معروف وسيتم تخزينه على أنه URL أساسي، كما كان `--base-url` سيخزنه. +- **`--provider` يجاوز الاستدلال بعد**، وهذه هي الطريقة للوصول إلى وسيط يتحدث API مزود من مضيف خاص بك: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **`--provider` يتعارض مع المضيف يُرفض**، لا يُخمَّن. `--provider openrouter --url https://api.typesafe.ai/v1` لا يكتب شيئاً ويقول السبب: يختلف الطريقان عن حيث سيتم إرسال مفتاحك. يتم رفض الزوج نفسه من `jev setup --base-url` ومن إعدادات Jev في لوحة المعلومات. (`--provider custom` ليس تعارضاً — يعني "اعتبر هذا URL بذاته" — باستثناء على مضيف Cloudflare، الذي لا يمكن لمسار مخصص الوصول إليه.) + +يتم التحقق من صحة `--url` تماماً كما يتم التحقق من صحة `baseUrl` في ملف الإعداد، ويُرفض بنفس الكلمات: `https`، أو `http://localhost` البسيط في الوضع الظلي فقط. + +### المفتاح + +أدخله باستخدام `--key-stdin`، أو قم بتشغيل الأمر في محطة بدون ذلك والصق المفتاح في موجه مقنَّع. على أي حال، يذهب مباشرة إلى ملف الإعداد ولا يطبع أبداً. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +يأخذ `failproofai jev setup` نفس الأعلام وهو الصيغة المطولة لكل ذلك: `setup --provider ` حيث تفضل تسمية المزود بدلاً من URL. + +### `--token`، وما يكلفه + +`--token ` يضع المفتاح على سطر الأوامر، وهو أسرع طريقة لتكوين آلة والصيغة الوحيدة التي تترك المفتاح في أي مكان ما عدا ملف الإعداد: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +يكون حجة سطر الأوامر في ملف سجل الأصداف الخاص بك بعد ذلك، وبينما ينفذ الأمر يكون في قائمة العملية — قابل للقراءة من `/proc` بأي شيء يعمل بنفس حالتك. `setup` يقول ذلك في كل مرة يُستخدم `--token`. فضّل `--key-stdin` على آلة تشاركها، في جلسة مسجلة، أو في أي مكان يتم فيه مزامنة ملف السجل؛ قم بتدوير مفتاح مررته بهذه الطريقة إذا أهمك الأمر. + + +`--token` و`--key-stdin` و`--key-from-env` متنافيتان: أعط واحداً. + +ثم أرسل طلب بث صغير حي واحد لفحص المفتاح، نقطة النهاية وأي Jev أجاب: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` ينهي بـ 1، ويقول ذلك في عنوانه، عندما تصل الإجابة بعد انتهاء المهلة الزمنية (كل خطاف سيعود إلى regex كـ `timeout`) أو تجيب على سؤال الفحص بشكل خاطئ. + +تقرأ الخطافات الإعداد على كل استدعاء أداة، لذا فهو ينطبق من الاستدعاء التالي. لا يوجد شيء يجب إعادة تشغيله، مع أو بدون المراقب. + +## تحقق مما يفعله + +```bash +failproofai jev status +failproofai jev status --json +``` + +يُظهر `status` المزود، نقطة النهاية، النموذج، الوضع، ملف الإعداد والأذونات الخاصة به، ولا أبداً المفتاح. تحته، يلخص النشاط الأخير: كم استدعاء قيّم Jev، كم مرة عاد إلى regex ولماذا، زمن الاستجابة، وأي سياسات قابلة للمراجعة أزالها. + +## الوضع الظلي + +`enforce` هو الافتراضي. لمراقبة Jev بدون السماح له بتغيير أي قرار، انتقل إلى `shadow`: لا يزال Jev يُسأل وتُسجل أحكامه، لكن نتيجة regex هي ما يتم تطبيقه. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` يحتفظ بالإعداد — نقطة النهاية والمفتاح — ويوقف سؤال Jev: تشغل الخطافات سياسات regex تماماً كما بدون إعداد، و`failproofai jev status` يقول "off (switched off)". تبديل العودة مع `--mode shadow` أو `--mode enforce`. + +إعادة تشغيل `setup` للمزود نفسه يحتفظ بالمفتاح المخزن، لذا فإن تبديل الوضع هو علم واحد. يبدأ تبديل المزود من جديد ويطلب مفتاح ذلك المزود. وكذا `--base-url` الذي ينقل الطلبات إلى مضيف مختلف: يتم إرسال مفتاح مخزن فقط إلى المضيف الذي أُعطي له، أو إلى API المزود الخاص به. + +## ملف الإعداد + +كل شيء يوجد في ملف واحد، `~/.failproofai/jev.json`، مكتوب بواسطة `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| الحقل | المعنى | +| --- | --- | +| `provider` | `typesafe` أو `openrouter` أو `vercel` أو `cloudflare` أو `custom` — أو `failproofai`، الذي يأتي مفتاحه من اتصال FailproofAI Cloud بدلاً من هذا الملف (اطلع على [Jev من خلال FailproofAI Cloud](/ar/policies/jev-cloud)). | +| `apiKey` | أُرسل كـ `Authorization: Bearer `. | +| `baseUrl` | مطلوب لـ `custom`؛ يحل محل قاعدة API المزود بخلاف ذلك. يجب أن يكون `https`. `http` البسيط إلى `localhost` مقبول فقط مع `mode: shadow`: لا شيء يثبت منفذ محلي، لذا بينما تكون الوسيط معطلاً قد تجيب أي عملية على الآلة، بما في ذلك الوكيل الذي يتم الحكم عليه، محله. +| `accountId` | Cloudflare فقط: 32 حرف hex صغير. | +| `model` | يحل محل معرّف النموذج الافتراضي للمزود. يجب أن يسمي معرّف الإصدار Jev 1.13. قيمة بشكل مشابه لمفتاح API يتم رفضها (ولا تكرر للخلف)، لذا فإن مفتاحاً مُدرجاً في `--model` لا يتم تخزينه أو إرساله أبداً كنموذج. | +| `timeoutMs` | كم من الوقت ينتظر استدعاء الأداة Jev قبل استخدام نتيجة regex. 100–10000، افتراضي 3000. | +| `mode` | `enforce` (افتراضي) أو `shadow` أو `off` (احتفظ بالإعداد، لا تشغل Jev). | + +ثلاث قواعد تحميها: + +- **المالك فقط.** يتم كتابته بأذونات `0600`. نسخة يمكن لأي مستخدم أو مجموعة أخرى قراءتها أو كتابتها **يتم رفضها**، والخطافات تعود إلى regex حتى تشغل `chmod 600 ~/.failproofai/jev.json` أو `setup` مرة أخرى. يتم التحقق من الدليل أيضاً: `~/.failproofai` يجب ألا يكون **قابلاً للكتابة** من قبل أي شخص آخر، لأن من يمكنه الكتابة هناك يمكنه استبدال الملف مهما كانت أذوناته. `setup` يأخذ تلك البتات الكتابة إذا وجدها. `failproofai jev status` يقول عندما يتم رفض إعداد ويُظهر نقطة النهاية التي يسميها الملف: قد يكون شخص آخر قد غيّره، لذا تحقق من أنه ملكك قبل أن تفعل `chmod`. إعادة تشغيل `setup` على مثل هذا الملف يحمل مفتاحه المخزن فقط إلى API المزود الخاص به؛ أي نقطة نهاية أخرى يسميها تحتاج إلى المفتاح مرة أخرى (`--key-stdin`)، أو `--base-url default` لإرسال طلبات للخلف إلى المزود. +- **عام فقط.** لا يمكن لمستودع أن يشغل Jev، أو يوجهه إلى نقطة نهاية أخرى أو يختار نموذجه: يتم تجاهل `.failproofai/jev.json` داخل مشروع، ويتم قراءة المزود و URL والنموذج ومعرّف الحساب فقط من ذلك الملف — أبداً من البيئة، التي يمكن لإعدادات وكيل مستودع أن تعينها. (`FAILPROOFAI_HOME` ليست طريقة حول ذلك: تنقل مجلد failproofai بأكمله، سياساتك المضمنة، بدلاً من إعادة توجيه Jev بمفرده.) +- **قد يأتي المفتاح وحده من البيئة.** إذا لم يكن الملف يحتوي على `apiKey`، يوفر `FAILPROOFAI_JEV_API_KEY` لتلك الجلسة (`setup --key-from-env` يكتب مثل هذا الملف). لا يحل أبداً محل مفتاح يحمله الملف، ولا يمكنه تشغيل Jev بدون الملف. حيث لم يتم تعيين المتغير، يكون Jev ببساطة معطل لتلك القشرة: `failproofai jev status` يقول ذلك، ينهي بـ 0 ويترك الإعداد وحده (`status --json` يُبلِّغ عن `"status": "key-missing"` مع `"reason": "no-env-key"`). مراقب `failproofaid` لا يرى بيئة القشرة الخاصة بك، لذا على آلة تم إعدادها مع `failproofai config`، احتفظ بالمفتاح في الملف. + +## أي Jev يجيب + +تم معايرة عتبات قرار Failproof AI على Jev 1.13، لذا يتم استخدام إجابة فقط عندما تأتي من تلك العائلة: `jev-1.13.x` أو `typesafe/jev-1.13-` من OpenRouter. حيث يسمي المزود Jev فقط بـ اسم مستعار ولا يُبلِّغ عن إصدار (Vercel و Cloudflare عندما لا تقول)، يتم استخدام الإجابة وتسجيلها على أنها غير معروّفة. يجب أن تُبلِّغ نقطة نهاية `custom` عن النموذج الذي أجاب؛ الاستثناء الوحيد هو اسم `--model` غير مصير تكوينه له، الذي، إذا تمّ صداه للخلف، يتم تسجيله على أنه غير معروّف بنفس الطريقة. إجابة تُبلِّغ عن أي إصدار آخر، أو إجابة `custom` لا تُبلِّغ عن أي إصدار، لا يتم استخدامها: يعود هذا الاستدعاء إلى regex بالسبب `model-mismatch`. + +## عندما لا يمكن لـ Jev الإجابة + +كل من هذه يعود إلى نتيجة regex لهذا الاستدعاء ويتم تسجيله مع سببه، الذي `failproofai jev status` يجمعه: + +| السبب | السبب | +| --- | --- | +| `timeout` | لا إجابة ضمن `timeoutMs`. | +| `http-429` | حدّ المزود معدل المفتاح. | +| `rate-limited` | حدود Failproof AI الخاصة أمسكت الاستدعاء قبل إرساله: 5 طلبات في الثانية، في انفجارات بما يصل إلى 5، وليس شيء لحظة بعد أن يجيب المزود بـ `429`. ليس المزود. | +| `http-500` أو `http-502` أو `http-503` وما إلى ذلك | خطأ خادم في المزود. يتم تسجيل الحالة الدقيقة. | +| `out-of-credits` | HTTP 402: حساب المزود لا يملك أرصدة متبقية. | +| `provider-refused` | HTTP 402 من Cloudflare يقرأ "Model execution failed (Payment error)": رفض المزود تشغيل النموذج على هذا الطلب. عادة ليس الفواتير، لذا سيؤدي شحن الرصيد إلى عدم تحريكه. | +| `http-401` أو `http-403` | تم رفض المفتاح. | +| `http-404` | لا شيء يتم تقديمه في `/systemone`، لذا قاعدة URL خاطئة — `/systemone` يتم إضافته إليه، وكل مزود يقدمه عند جذر إصداره. يُظهر `failproofai jev models` ما يخدمه نقطة النهاية. | +| `network` | لم يتمكن من الوصول إلى نقطة النهاية. | +| `http-301` أو `http-302` أو `http-307` أو `http-308` | أجابت نقطة النهاية بإعادة توجيه. لا يتم متابعة عمليات إعادة التوجيه، لذا تأتي الإجابة فقط من URL في إعدادك؛ عيّن `--base-url` إلى URL النهائي. | +| `malformed` | أجابت نقطة النهاية، لكن ليس بإجابة Jev — جسم ليس JSON، أو واحد بدون إجابات فيه. | +| `cloudflare-error` أو `cloudflare-incomplete` | أبلغ مغلف Cloudflare عن فشل، أو وظيفة لم تنته. | +| `model-mismatch` | إصدار Jev آخر غير 1.13 أجاب، أو لم تقل نقطة نهاية `custom` أي نموذج أجاب. | +| `request-cut` | **ليس انقطاع.**Jev أجاب؛ تم عرض فقط جزء من الاستدعاء عليه، لذا إجابته لم تُلغ شيئاً. اطلع على [عندما أجاب Jev، لكن ليس على الاستدعاء كاملاً](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` يمكنه أيضاً إظهار عدد قليل من الأسباب الأندر، مثل `upstream-error` (حملت الإجابة خطأ المزود الخاص به) أو `config`، ويجمع أي سبب لا يمكنه تسميته كـ `other`. + +`request-cut` موجود في هذا الجدول لأن `failproofai jev status` يجمعه مع البقية، وأيضاً لأنه يترك أيضاً كل رفض قائماً. إنه السبب الوحيد هنا الذي لا يقول شيئاً عن مزودك: وصل الطلب وأجاب Jev عليه. على عكس كل صف فوقه، تلك الإجابة لا تزال تحسب — يطبق رفض أو تحذير Jev الخاص على نتيجة regex بدلاً من التخلص منه. لذا فإن مسار منهم يعني استدعاءات تصل إلى المقيّم كبير جداً للإرسال كاملاً، وليس أن نقطة النهاية الخاصة بك سيئة، وسيؤدي شحن الأرصدة أو تغيير URL إلى عدم تحريك الرقم. + +## عندما أجاب Jev، لكن ليس على الاستدعاء كاملاً + +شيئان آخران يمكن أن يحدثا، ولا أحد منهما Jev فشل في الإجابة. كلاهما يتعلق بكم من الاستدعاء، أو من المحادثة، مناسب في طلب واحد. + +**جزء من الاستدعاء نفسه لم يناسب.** يتم إرسال استدعاء الأداة داخل ميزانية ثابتة، واحد ضخم — `Write` كبير جداً، جسم MCP ضخم، أمر مُحشى إلى الحد — يتم إرساله مع ما ناسب. يجيب Jev بعد ذلك، وتحسب إجابته بعد ذلك: يطبق رفضه أو تحذيره الخاص كالمعتاد. ما لا يمكنه فعله هو **إلغاء** أي شيء، لأن حكم معطى على جزء من استدعاء ليس حكماً على الاستدعاء. لذا فإن كل سياسة رفض تقف، ويتم تسجيل الاستدعاء كرجوع مع السبب `request-cut`، الذي `failproofai jev status` يجمعه جنباً إلى جنب مع الأسباب أعلاه. القاعدة التي يعطيك إياها: جعل استدعاء أكبر يمكنه تكلفته تصاريحه، ولا يمكنه أبداً شراء واحدة. + +**رسالة لم تناسب.** موجه طويل ألصقته، الرسالة الأخيرة للوكيل، أو موجه قد كان مخزن هذا المقيّم قد قبض عليه بالفعل. **لا شيء يتغير**: يتم الحكم على الاستدعاء، وإلغاء وتسجيله تماماً كأي آخر، ولم يتم حسابه كرجوع. طول ما تكتبه لا يقرر أبداً حكماً، وقطع لا يمكنه تصنع الموافقة: حيث وصل موجه مقبوض عليه بالفعل، "أنت لم تطلب هذا" يتوقف عن كونه استنتاجاً يمكن استخلاصه منه على الإطلاق، بدلاً من أن يصبح واحداً. + +الخط بين الاثنين هو من كتب النص. الاستدعاء للوكيل، وقاعدة تسمح لطوله بطرح الشدة ستكون قاعدة يمكن للوكيل استخدامها؛ موجهك لك، ومعاملة طوله كإشارة فقط قد عاقب دائماً لصق مواصفة أو تتبع الحجم. + +## ما يترك الآلة + +لكل استدعاء أداة يقيّمه Jev، طلب واحد يذهب إلى مزودك، حاملاً: + +- استدعاء الأداة نفسه، مع أسرار مثل مفاتيح API ورموز المشروع وتعيينات `KEY=` معاد صياغتها؛ +- الموجهات الأخيرة التي كتبتها، مع إزالة النص الذي أضافت حزام الوكيل؛ +- الرسالة الأخيرة للوكيل قبل موجهك الأخير، معنّون كمكتوب بواسطة الوكيل؛ +- حقائق محسوبة محلياً، مثل ما إذا كان المسار داخل المشروع — الذي كانت الجلسة فيه عند أول استدعاء مراجع، [مثبت للجلسة](/ar/reference/jev-intent#the-project-root) — والفرع git الحالي. + +يذهب فقط إلى نقطة النهاية في إعدادك، تحت مفتاحك. + +## أطفئه + +```bash +failproofai jev remove +``` + +هذا يحذف `~/.failproofai/jev.json`. من استدعاء الأداة التالي، تشغل الخطافات سياسات regex تماماً كما قبل. مخازن كل جلسة تحت `~/.failproofai/state/semantic/` (الموجهات المسجلة في `sessions/`، جذور المشروع في `roots/`) يتم تركها في المكان وتتقدم في السن. لإيقاف سؤال Jev لكن الاحتفاظ بالإعداد، استخدم `failproofai jev setup --mode off` بدلاً من ذلك. + +## مرجع الأوامر + +| الأمر | النتيجة | +| --- | --- | +| `failproofai jev --url --key-stdin` | أعده في أمر واحد؛ يأتي المزود من مضيف URL | +| `failproofai jev --url --token ` | نفس، مع المفتاح على سطر الأوامر — السجل والقائمة الخاصة بك رى تراه | +| `failproofai jev setup --provider --key-stdin` | اكتب الإعداد من مفتاح مُنقول على stdin | +| `failproofai jev setup --provider ` | نفس، طالباً المفتاح في موجه مقنَّع | +| `failproofai jev setup --key-from-env` | لا تخزن مفتاح؛ اقرأ `FAILPROOFAI_JEV_API_KEY` لكل جلسة | +| `failproofai jev setup --mode shadow` | وضع التبديل (`enforce` أو `shadow` أو `off`)، الاحتفاظ بالمفتاح المخزن | +| `failproofai jev setup --model ` / `--base-url ` | تجاوز النموذج أو قاعدة API؛ `default` يمسح التجاوز | +| `failproofai jev setup --timeout-ms ` | تغيير الميزانية لكل استدعاء | +| `failproofai jev status [--json]` | الإعداد والأذونات والنشاط الأخير؛ أبداً المفتاح | +| `failproofai jev test [--json]` | طلب بث واحد: زمن الاستجابة والإصدار الذي أجاب | +| `failproofai jev models [--provider ] [--url ] [--json]` | معرّفات النموذج التي يُبلِّغ عنها `/models` لنقطة النهاية، ويشير إلى المُعدّل | +| `failproofai jev remove` | احذف الإعداد؛ Jev معطل | \ No newline at end of file diff --git a/docs/ar/policies/jev-cloud.mdx b/docs/ar/policies/jev-cloud.mdx new file mode 100644 index 000000000..ccb20183d --- /dev/null +++ b/docs/ar/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev من خلال FailproofAI Cloud" +description: "دع Jev يحكم على استدعاءات أدوات وكلائك من خلال FailproofAI Cloud، على خطة مؤسستك، بدون حساب TypeSafe أو مفتاح خاص بك." +icon: "cloud" +--- + +[Jev](/ar/policies/jev-byok)، مصنف TypeSafe، يقرأ كل استدعاء أداة مقابل ما طلبته بالفعل ويجيب إلى جانب سياساتك، وليس بدلاً منها. من خلال **FailproofAI Cloud**، تستخدم الآلة المتصلة Jev بنفس المفتاح الذي تتصل به بالفعل: لا حساب TypeSafe، لا مفتاح ثانٍ، لا نقطة نهاية للتكوين. يتم فرض رسوم على كل استدعاء حسب تخصيص الخطة الحالي لمؤسستك. + +كل ما يفعله Jev لم يتغير عن [إعداد bring-your-own-key](/ar/policies/jev-byok): السياسات الصارمة تبقى نهائية، تُمحى حالة الرفض للسياسة المراجعة فقط عندما يتم السؤال عن Jev حول هذا الاهتمام بالذات، وأي فشل يعود إلى نتيجة regex لهذا الاستدعاء. + + +يتطلب **failproofai 1.0.8-beta.0** أو إصدار أحدث. 1.0.7 ليس لديه Jev، على الرغم من أنه يترتب فوق إصدارات 1.0.7 التجريبية. بدون تكوين Jev، لا شيء يتغير: تعمل الخطافات على سياسات regex تماماً كما كانت دائماً. + + +## تشغيله + +1. **إنشاء مفتاح باستخدام Jev.** في لوحة تحكم FailproofAI Cloud، افتح **Keys → Create key** واختر إعداد **machine**. يمنح المفتاح الأذونات الثلاث التي تحتاجها الآلة: `events:add` (إرسال النشاط)، `policies:pull` (استقبال السياسات) و `jev:evaluate` (Jev، يتم فرض رسوم عليه حسب خطة مؤسستك). لا يمكن لمفتاح أن يحمل `jev:evaluate` بدون الاثنين الآخرين. +2. **اتصل بالآلة** بهذا المفتاح: + + ```bash + failproofai config --token + ``` + + إذا كانت مؤسستك تدير FailproofAI Cloud الخاص بها بدلاً من النسخة المستضافة، أضف عنوانها: `--url https://` (أو صدّر `FAILPROOFAI_CLOUD_URL`). بدونها، يتم التحقق من المفتاح مقابل الخدمة المستضافة ويفشل الاتصال. إذا كانت شهادة هذا المضيف من CA خاص، ثبت CA في مخزن الثقة النظامي للآلة (على سبيل المثال مع `update-ca-certificates`)، وليس فقط في `NODE_EXTRA_CA_CERTS`: المراقب الذي يرسل الأحداث ويسحب السياسات يقرأ المخزن النظامي. انظر [Troubleshooting](/ar/reference/troubleshooting). + +هذا كل شيء. يحفظ الاتصال المفتاح وعندما لا تملك الآلة تكوين Jev بعد، يقوم بتشغيل Jev من خلال FailproofAI Cloud في وضع **shadow**: يتم السؤال عن Jev بشأن كل استدعاء أداة محصورة وتسجيل أحكامه، لكن نتيجة سياساتك هي ما يتم فرضه. يقول الإخراج ذلك: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**مع `--no-transcripts`، لا يؤدي الاتصال إلى تشغيل Jev.** يرسل Jev كل استدعاء أداة تم فحصه والمطالبة الأخيرة إلى FailproofAI Cloud، وهو أكثر مما يُطلب من اتصال قرارات فقط. لا يزال المفتاح مخزناً، والإخراج يقول أن Jev متاح وكيفية تشغيله: + +```bash +failproofai jev setup --provider failproofai +``` + +كما أنه لا يطفئ Jev **off**. إذا كان `jev.json` للآلة يشغل بالفعل Jev من خلال FailproofAI Cloud، فسيتم تركه كما هو، والإخراج يقول أن Jev لا يزال يرسل كل استدعاء أداة تم فحصه والمطالبة الأخيرة، وأن `failproofai jev setup --mode off` يطفئه. + + +الاتصال **لا يستبدل أبداً** ملف `~/.failproofai/jev.json` موجود. إذا كنت تستخدم بالفعل نقطة نهاية Jev الخاصة بك، فستستمر في الاستخدام، والإخراج يقول أن الملف تم تركه كما هو مكوّن — وعندما يترك هذا الملف Jev معطلاً (مرفوضاً، أو معطلاً)، يقول ذلك وكيفية إصلاحه. للتبديل إلى هذه الآلة في FailproofAI Cloud، قم بتشغيل `failproofai jev setup --provider failproofai`. + + +## Shadow أو enforce أو off + +ابدأ في shadow، شاهد ما كان سيفعله Jev على صفحة السياسة، ثم دعه يتصرف: + +```bash +failproofai jev setup --mode enforce # تنطبق أحكام Jev: قد يمحو رفض قابل للمراجعة ويضيف أحكامه الخاصة +failproofai jev setup --mode shadow # يتم السؤال عن Jev وتسجيله؛ نتيجة سياساتك هي ما يتم فرضه +failproofai jev setup --mode off # احتفظ بالتكوين، توقف عن السؤال عن Jev +``` + +نفس الخيار موجود في لوحة التحكم المحلية: **Settings → Jev** يحتوي على مفتاح تشغيل/إطفاء و shadow/enforce. يعيد كتابة الوضع وليس شيء آخر. تقرأ الخطافات التكوين في كل استدعاء أداة، لذا ينطبق التغيير من الاستدعاء التالي، بدون إعادة تشغيل. + +## تحقق مما يفعله + +```bash +failproofai jev status +failproofai jev test +``` + +يعرض `status` المزود باسم **FailproofAI Cloud**، المضيف في Cloud الذي اتصلت به الآلة، والوضع، ومصدر المفتاح باسم **FailproofAI Cloud connection**، لا تعرض المفتاح أبداً. عندما يكون `jev.json` الخاص بـ FailproofAI Cloud موجوداً لكن لا يمكن لـ Jev الجري، يقول السبب: + +| يقول `status` | `status --json` | المعنى | +| --- | --- | --- | +| **off — لا يوجد مفتاح Jev مخزن لاتصال FailproofAI Cloud بهذه الآلة** | `key-lacks-jev` | الآلة متصلة، لكن لا يوجد مفتاح Jev مخزن لها: المفتاح يفتقد `jev:evaluate`، أو الاتصال لم يستطع تأكيده. قم بتشغيل `failproofai config --token ` مرة أخرى بنفس المفتاح؛ إذا كان ينقصه الإذن، استخدم مفتاح **machine**. | +| **off — هذه الآلة غير متصلة بـ FailproofAI Cloud** | `not-connected` | لا توجد اتصال FailproofAI Cloud على هذه الآلة لمفتاح Jev ليتبع. | + +بعد `failproofai config --disconnect` لم يعد هناك `jev.json` الخاص بـ FailproofAI Cloud (ما لم يتم إطفاؤه، والذي يتم الاحتفاظ به)، لذا يقول `status` ببساطة أن Jev معطل. يحمل `status --json` نفس الحقائق (`provider: "failproofai"`، `keySource: "cloud"`، `cloudConnected`، `keyCarriesJev`)، أيضاً عندما يكون التكوين غائباً أو مرفوضاً. `permissions` هو دائماً من `jev.json`؛ الرفض حول `credentials.json` يضيف `credentialsPermissions`، و `fix` عندما تصلح أمر واحد. يرسل `test` طلباً واحداً مباشراً ويبلغ عن زمن الانتقال وإصدار Jev الذي أجاب. يخرج 1، ويقول ذلك في عنوانه، عندما تصل الإجابة بعد timeout الخطاف (ستسجل الخطافات `timeout`) أو تجيب على سؤال الفحص بشكل خاطئ. + +تعرض لوحة تحكم **Settings → Jev** أيضاً اتصال **FailproofAI Cloud connection**: المؤسسة التي تبلغ الآلة عنها وما إذا كان مفتاحها يحمل Jev. تتم قراءتها من ملفات الآلة الخاصة بها، بدون استدعاء شبكة. + +## ما يصل إلى صفحة السياسة + +الآلة ترسل بالفعل نشاطها من الخطاف إلى FailproofAI Cloud (`events:add`). مع تشغيل Jev، سجل كل استدعاء محصور يقول أيضاً أي معيّن جرى، ما قررته Jev، أي السياسات التي أمحاها، لماذا عادت عندما فعلت، وزمن الانتقال والنموذج الذي أجاب — القرارات، الرموز والأسماء، لا تعرض الأوامر أو المطالبة. على صفحة **Policies** بمؤسستك: + +- يتم نسب استدعاء قررت حكمه الخاص بـ Jev (وضع enforce) إلى **Jev**، وعندما جاء الفحص الحاسم من حزمة، يسمي السجل أيضاً تلك الحزمة وإصدارها؛ +- في وضع shadow، يظهر نفي أو تحذير Jev كـ **would-have**، بجانب التجاوزات التي تراقبها؛ +- تُحتسب السياسات التي أمحاها Jev، أو كانت ستمحوها في وضع shadow، لكل سياسة. + +## عندما لا يستطيع Jev الإجابة + +كل واحد من هذه يعود إلى نتيجة سياساتك لهذا الاستدعاء، ويسجل مع السبب: + +| السبب | السبب | +| --- | --- | +| `out-of-credits` | استخدمت مؤسستك تخصيص الخطة. | +| `http-401`, `http-403` | تم إلغاء المفتاح، أو لا يحمل `jev:evaluate`. أعد الاتصال بمفتاح يفعل ذلك. | +| `http-429` | FailproofAI Cloud يقيّد معدل Jev لمؤسستك. حتى ينتهي الانتظار الذي يطلبه (الخاص به `Retry-After`، بحد أقصى 60 ثانية)، لا ترسل الآلة له شيء وكل استدعاء يعود مباشرة. الاستدعاءات المحتفظ بها بهذه الطريقة يتم تسجيلها كـ `http-429`، أو كـ `rate-limited` عندما يحتفظ حد معدل الآلة الخاص بها أولاً. | +| `http-429` (حد يومي) | استخدمت مؤسستك استدعاءات Jev اليومية: **10,000 لكل يوم UTC**، ما لم يقم من يشغل FailproofAI Cloud الخاص بك بتعيين حد آخر. كل استدعاء يعود حتى يعاد تعيين العدد في 00:00 UTC؛ الآلة لا تزال تسأل مرة واحدة على الأكثر في الدقيقة، لذا تختار الإعادة في غضون دقيقة. يقول `failproofai jev test` "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | رفض Jev طلب هذا الاستدعاء، عادة لأن استدعاء الأداة احتفظ بنص كثيف (base64، hex، كود مصغر) فوق ميزانية Jev. هذا الاستدعاء يعود في كل مرة؛ ليس انقطاع. | +| `http-502` | Jev غير متاح الآن. | +| `http-503` | لا يستطيع هذا Cloud تقديم Jev لمؤسستك: لا بوابة نموذج، مؤسسة لم يتم توفيرها بعد، أو البوابة معطوبة. اطلب من المسؤول؛ تسأل الخطافات مرة واحدة على الأكثر في الدقيقة. | +| `http-404` | لا تخدم FailproofAI Cloud هذه Jev بعد. | +| `timeout` | لا توجد إجابة في `timeoutMs` (الافتراضي 3000). | +| `model-mismatch` | أجاب إصدار Jev آخر غير 1.13. | + +## حيث يعيش المفتاح وأين يذهب + +- يتم تخزين المفتاح مرة واحدة، في `~/.failproofai/credentials.json` (`0600`، في دليل خاص بالمالك فقط)، بجانب بيانات اعتماد FailproofAI Cloud الأخرى. لا يحمل `jev.json` مفتاحاً لهذا المسار؛ واحد مكتوب هناك يجعل التكوين غير صحيح. +- إذا حمل `credentials.json` **أي** إذن لأي شخص غير أنت (مجموعة أو آخر، قراءة أو كتابة)، أو يمكن كتابة دليله بواسطة أي شخص غيرك، فسيتم **رفضه**، لم يتم قراءته، وسيتم إطفاء Jev حتى تصلحه: `chmod 600` على الملف، `chmod 700` على الدليل (أو أعد الاتصال، الذي يعيد كتابة الملف في `0600` ويجعل الدليل خاصاً بالمالك فقط). الدليل الذي يمكن للآخرين قراءته فقط هو بخير؛ الدليل الذي يمكنهم الكتابة فيه يتيح لهم استبدال الملف. +- المفتاح ينطبق فقط أثناء اتصال الاتصال به على الآلة: سياسة أو بيانات اعتماد التقرير لنفس FailproofAI Cloud **بنفس المفتاح**، في نفس الملف. يتم تجاهل مفتاح Jev المتروك بدون واحد، وسيتم إطفاء Jev. يحدث عندما يترك failproofai الأقدم `config --disconnect` مفتاح Jev في مكانه (لا يعرف كيفية إزالته)، أو عندما يتصل failproofai الأقدم بـ `config --token` بمفتاح آخر، الذي قد ينتمي إلى مؤسسة أخرى على FailproofAI Cloud. لتشغيل Jev مرة أخرى، اتصل مرة أخرى بمفتاح **machine**. +- يتم إرسال المفتاح فقط إلى أصل Cloud الذي تم التحقق منه ضده. يتم رفض `jev.json` الذي يشير إلى أي مكان آخر. +- **وكيل على الآلة يمكنه قراءته.** `credentials.json` خاص بالمالك فقط، والوكيل يعمل كهذا المالك. يُسمح بقراءة ملفات failproofai الخاصة بنفسها عن قصد (فقط تغييرها مسدود بـ `block-failproofai-commands`)، لذا فإن الشيء الوحيد بين وكيل وهذا الملف هو `block-read-outside-cwd` — سياسة *قابلة للمراجعة* — ومن جلسة بدأت في مجلد المنزل الخاص بك، لا شيء. المفتاح الذي يحمل `jev:evaluate` ينفق تخصيص Jev بمؤسستك (حتى الحد الأقصى اليومي) من أينما تُستخدم، لذا تعامل مع مفتاح الآلة مثل أي بيانات اعتماد إنفاق أخرى: إذا كان قد يكون قد قرأه وكيل، عطّله على صفحة Keys وأعد الاتصال بمفتاح جديد. +- فقط ملفاتك العامة تقرر هذا. لا يمكن لمستودع تشغيل Cloud Jev، الإشارة إليه في مكان آخر أو توريد مفتاحه، و `FAILPROOFAI_JEV_API_KEY` يتم تجاهله لهذا المسار. +- لكل استدعاء يقيّمه Jev، طلب واحد يذهب إلى FailproofAI Cloud، يحمل ما تسرده [صفحة bring-your-own-key](/ar/policies/jev-byok#what-leaves-the-machine) (أسرار معاد صياغتها). ترسله FailproofAI Cloud إلى TypeSafe ولا تسجله أو تحفظ عليه. + +## إطفاؤه + +| الأمر | النتيجة | +| --- | --- | +| `failproofai jev setup --mode off` | احتفظ بالتكوين؛ لا يتم السؤال عن Jev. **هذا هو الخيار الذي يدوم:** الاتصال مرة أخرى لا يعيد كتابة `jev.json` موجود أبداً، لذا يبقى Jev معطلاً حتى تقوم بتشغيله بـ `--mode shadow`. | +| `failproofai jev remove` | حذف `~/.failproofai/jev.json`؛ Jev معطل — حتى الاتصال التالي `failproofai config --token` بمفتاح يحمل `jev:evaluate`، الذي يجد لا `jev.json` ويشغل Jev في وضع shadow (ما لم يعمل بـ `--no-transcripts`). للاحتفاظ به معطلاً، استخدم `--mode off`. | +| `failproofai config --disconnect` | افصل الآلة: يتم إزالة المفتاح، وكذلك `jev.json` عندما يسمي FailproofAI Cloud وليس معطلاً. `jev.json` لنقطة النهاية الخاصة بك يبقى، وكذلك واحد معطل، لذا يبقى Jev معطلاً عندما تتصل مرة أخرى. | + +من استدعاء الأداة التالي، تعمل الخطافات على سياسات regex تماماً كما كانت من قبل. \ No newline at end of file diff --git a/docs/ar/policies/jev.mdx b/docs/ar/policies/jev.mdx new file mode 100644 index 000000000..2700888ff --- /dev/null +++ b/docs/ar/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "سياسات Jev" +description: "أضف المراجعة المباشرة من Jev إلى استدعاءات الأدوات المحمية، ثم فتشها قبل تطبيق قراراتها." +icon: "shield-check" +--- + +يقرأ Jev استدعاء الأداة مقابل ما طلبه الشخص من الوكيل أن يفعله. استخدمه عندما تحظر سياسة مطابقة النصوص عملاً صحيحاً أو تفتقد إجراءً محفوفاً بالمخاطر يتطلب سياقاً. يجيب جنباً إلى جنب مع سياساتك عند بوابة `PreToolUse` أو `PermissionRequest`. للحصول على درجة **بعد** انتهاء جلسة، استخدم [تقييمات Jev](/ar/evaluations/jev). + +## ابدأ بوضع المراقبة + +ثبّت Failproof AI وأرفق الخطافات إلى [حزام مدعوم](/ar/reference/harnesses). استخدم failproofai 1.0.8-beta.0 أو إصدار لاحق. + +لا تشحن Failproof AI أي فحوصات Jev. ثبّتها كحزمة، وإلا فلا يملك Jev شيئاً يسأل عنه ولن يتم استدعاؤه أبداً: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +ثم اختر كيفية وصول الطلبات إلى Jev: + +| المسار | الخطوة الأولى | +| --- | --- | +| FailproofAI Cloud | اتصل بمفتاح **جهاز** يحمل `jev:evaluate`. على جهاز بدون إعدادات Jev، يشغّل `failproofai config` Jev بوضع المراقبة. | +| موفرك الخاص | في لوحة التحكم المحلية، افتح **الإعدادات → Jev**، اختر الموفر، الصق رمزه، وحدّد **مراقبة**. أو شغّل `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![إعدادات Jev في لوحة التحكم المحلية: الموفر والنقطة النهائية والرمز ووضع المراقبة قبل تشغيل Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +يفحص `test` النقطة النهائية. للتحقق من مسار الخطاف، اطلب من وكيل مزود بخطاف أن يستخدم أداة قراءة الملفات على `README.md`. أكّد أن استدعاء الأداة هذا يظهر في الجلسة، ثم افحص **السياسات → النشاط** في [لوحة التحكم المحلية](/ar/reference/local-dashboard#review-policy-activity). يجب أن يزداد عداد Jev في `status`. يسجل وضع المراقبة ما كان Jev سيقرره بينما تبقى نتيجة السياسة الحالية سارية. + +## قرر متى يتم التطبيق + +تتمتع سياسة **صعبة** دائماً بالكلمة النهائية. قد يمسح Jev حكماً بالرفض فقط من سياسة موسومة بوضوح **قابلة للمراجعة** وفقط عندما يتحقق من الاهتمام المسمى لتلك السياسة. انظر [سلطة السياسة](/ar/policies/authority) قبل الاعتماد على تصريح. يمكن لـ Jev أيضاً إصدار تحذير أو الرفض بمفرده. إذا لم يتمكن من الإجابة، فإن نتيجة السياسة تقرر هذا الاستدعاء. + +بعد أن تبدو نتائج المراقبة صحيحة، انتقل إلى وضع التطبيق في **الإعدادات → Jev** أو شغّل: + +```bash +failproofai jev setup --mode enforce +``` + +للحصول على عناوين URL للموفر، وتفاتيح Cloud، والإعدادات، والحلول البديلة، والبيانات المرسلة مع كل طلب، انظر [مرجع تكامل Jev](/ar/reference/jev). \ No newline at end of file diff --git a/docs/ar/reference/custom-agents-typescript.mdx b/docs/ar/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..900d908be --- /dev/null +++ b/docs/ar/reference/custom-agents-typescript.mdx @@ -0,0 +1,428 @@ +--- +title: "Custom agents (TypeScript)" +description: "Configuration, the event catalog, the scopes and the framework adapters for @failproofai/sdk." +icon: "square-js" +--- + +ما يفعله كل إعداد وطريقة وحقل في SDK TypeScript. إذا كنت تقوم بالتجهيز للمرة الأولى، ابدأ بالدليل — هذه الصفحة موجودة للبحث عن الأشياء. + + + + التثبيت والتجهيز وطرق الأحداث ومثال عملي والمشاكل الشائعة. + + + نفس الأحداث وصيغة السلك نفسها والاسطوانة نفسها — من Python. + + + +Node 20.9 أو أحدث. ESM و CommonJS. لا توجد تبعيات وقت التشغيل. + + + هذا SDK والآخر من Python يكتبان **نفس الأحداث إلى نفس الاسطوانة**. أسطول يحتوي على وكلاء Node ووكلاء Python ينتج مجموعة واحدة من الجلسات وليس اثنتين، ولا يوجد شيء في لوحة التحكم يميز بينهما. اختر لكل خدمة وليس لكل شركة. + + +## التثبيت + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +محولات الأطر مرسلة في الحزمة نفسها. الأطر هي **تبعيات نظير اختيارية** — معلنة بحيث تكون النطاقات المدعومة مرئية وليست مثبتة نيابة عنك أبدا، وتم استيرادها فقط عند استدعاء `instrument()`. + +## توصيل مؤشر ترابط Failproof + +مطابق لـ Python SDK: أنشئ مفتاح `events:add` ضمن **Admin → Keys**، ثم [صل مؤشر ترابط](/ar/start/setup#connect-a-machine-to-cloud) على جهاز الوكيل. يكتب SDK إلى القرص؛ مؤشر الترابط يشحن. + +## الإعدادات + +### فترات OpenTelemetry (اختيار) + +ثبت OpenTelemetry بشكل منفصل باستخدام `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +بعد ذلك أضف FailproofAI إلى معالجات موفر خدمتك: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +بالنسبة لموفر خدمة موجود، احتفظ بمعالجاته الأخرى في نفس القائمة. يمكن تمرير موفري الخدمات الذين يعرضون `addSpanProcessor` بدلاً من ذلك كـ `{ provider }`. بدون خيارات، يسجل الإعداد موفر خدمة جديد فقط إذا لم يكن هناك موفر خدمة مسجل بالفعل. +يمكن أيضا استخدام `OtelSpanExporter` مباشرة مع معالجك الخاص. + +تمر الصادرات عبر مؤشر ترابط FailproofAI المتصل؛ SDK لا يرسل طلبات شبكة ولا يحتاج إلى مفتاح أو محاكي استماع محلي. اطلب من مسؤول تفعيل [استيعاب OpenTelemetry](/ar/agenteye/opentelemetry). `instrument()` مجرد لا يفعل هذا المُصدِّر. `uninstrument("otel")` يعطّل معالجه الخاص فقط. +سمات الفترة الخاصة بك تتحكم في التقاط المحتوى؛ اشطف موفر خدمتك قبل الخروج. +يبقى OpenTelemetry تبعية تطبيق اختيارية، وليس تبعية SDK صعبة. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| الخيار | ما يفعله | +| --- | --- | +| `environment` | الملصق على كل حدث — `production` أو `staging` أو `prod-eu`. الافتراضي هو `dev`. | +| `flushInterval` | عدد مرات كتابة المؤقت إلى القرص بالثواني. الافتراضي هو `0.5`. | +| `baseDir` | مكان الكتابة. الافتراضي هو اسطوانة مؤشر الترابط، وهو ما تريده ما لم تعرف غير ذلك. | + +لا يتم تطبيق أي شيء ما لم يتحقق الكل منه، لذا فإن استدعاء مرفوض يترك SDK تماما كما كان بدلا من وجود `baseDir` جديد والفترة القديمة. + +اضبط بواسطة متغير البيئة بدلاً من ذلك: + +| المتغير | ما يفعله | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | يضبط `environment` بدون تغيير الكود. خيار `configure()` يفوز عليه. | +| `FAILPROOFAI_HOME` | ينقل جذر Failproof AI الذي يحتوي على الاسطوانة. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug` أو `info` أو `warn` (افتراضي) أو `error` أو `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` يجعل أخطاء التجهيز ترمي بدلا من تسجيلها. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` يجعل مشكلة توافق الأطر ترمي بدلا من تحذير والمتابعة. | + + + **بدون فواصل في `environment`.** يقسم الاستيعاب هذا الحقل على الفواصل لبناء مرشحاته، وتخطي أي حدث تسميته يحتوي على واحد — لذا فإن تشغيل كامل يختفي بصمت. اكتب `prod-eu` وليس `prod,eu`. + + `configure({ environment: "prod,eu" })` يرمي بحيث تكتشف على الفور. `AGENTEYE_ENVIRONMENT` لا يمكن أن يرمي — لا أحد يناديك — لذا فإنه يحذر مرة واحدة ويعود إلى `dev`. + + +وجّه سطور السجلات الخاصة بـ SDK إلى مسجلك باستخدام `failproofai.setLogger({ debug, info, warn, error })`. + +## الإيقاف + +يتم شطف الأحداث المخزنة مؤقتا عند `process.on("exit")`. + +العملية المقتولة بواسطة إشارة لا تصل أبدا إلى ذلك، والافتراضي في Node لـ `SIGTERM` هو الإنهاء بدون تشغيل معالجات الخروج — لذا فإن وكيل بدون حاويات يفقد كل ما لم تكتبه الفترة الأخيرة. + + + **هذا SDK لن يثبت معالج إشارة لك.** يؤدي تسجيل واحد إلى تغيير سلوك العملية: يثبط المستمع الافتراضي الافتراضي في Node، لذا فإن مكتبة أضافت واحدا ستتوقف بصمت عن Ctrl-C من العمل. أضف الخاص بك: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +يجب أن يقوم البرنامج النصي قصير الأجل أو معالج بدون خادم بـ `await failproofai.flush()` قبل العودة — الفترة الزمنية وحدها لا تضمن التسليم. + +## الهوية + +كل حدث ينتمي إلى جلسة ووكيل. **النطاقات تملأ كليهما**، لذا نادرا ما تمريرهما: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +تمرير `sessionId` أو `agentId` بشكل صريح لا يزال يعمل ويفوز. بدون ربط أو تمرير، يرمي الاستدعاء بدلا من إصدار حدث قد يتم التخلص منه بصمت. + + + الهوية تركب على `AsyncLocalStorage`. يتبع `await` و `.then()` والمؤقتات وأي رد نداء تم إنشاؤه داخل النطاق. لا يتبع رد نداء تم تخزينه أثناء تشغيل واحد واستدعاؤه أثناء تشغيل آخر، أو العمل الذي يتم تمريره عبر حدود `worker_threads` — لف تلك في `failproofai.propagate()` أو أحداثها تهبط بدون ربط. + + +### النطاقات + +| النطاق | يصدر | يرجع | +| --- | --- | --- | +| `session(body)` | لا شيء — الهوية فقط | أيا كان ما يرجعه `body` | +| `agent(id, options?, body)` | `agent_start` ثم `agent_end` | أيا كان ما يرجعه `body` | +| `toolCall(name, options?, body)` | `tool_use` ثم `tool_result` | أيا كان ما يرجعه `body` | + +جسم متزامن يبقى متزامنا: `agent("x", () => 1)` يرجع `1` وليس وعدا. + +`toolCall` يسجل قيمة الجسم المحللة كـ `output` الأداة، ما لم تعين `call.output` بنفسك. + + + +| ما حدث | الأحداث | `outcome` | +| --- | --- | --- | +| أرجع الكتلة | `agent_end` | `"success"` أو `outcome` الخاص بك | +| رمت الكتلة | `error` ثم `agent_end` | `"failed"` | +| `AbortError` | `agent_end` فقط | `"cancelled"` | + +يتم إعادة رمي الخطأ دائما. + +يتم تسجيل فشل الأداة على الورقة — `tool_result` مع سلسلة `error` — وينبعث **لا** حدث `error` على مستوى التشغيل. واحد يمسكه حلقة الوكيل ليس فشل التشغيل، وواحد ينتشر يتم الإبلاغ عنه بالضبط مرة واحدة، بواسطة `agent()` المحيط. + + + + + +عندما لا تكون العمل وظيفة واحدة — نطاق مفتوح في المنشئ ومغلق في الهدم، أو واحد يعبر تدفق التحكم الموجود: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +كلا الشكلين ينبعث بايت متطابق الأحداث. فضّل نموذج رد النداء: يعمل داخل `AsyncLocalStorage.run()`، لذا لا يوجد شيء لفك والفئة بأكملها من أخطاء «مفتوح هنا ومغلق هناك» غير قابلة للوصول. + +كتلة `using` التي تمسك بفشلها الخاص ترسله مع `span.fail(error)` — المخلص ليس لديه قناة استثناء خاصة به. + + + +## فهرس الأحداث + +نفس خمسة عشر طريقة مثل Python SDK، في camelCase. معظمها يأتي في **أزواج** — تستدعي الفاتح، ثم الإغلاق، و SDK يوقت الفجوة. + +| | يفتح | يغلق | +| --- | --- | --- | +| **الوكلاء** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **النماذج** | `modelRequest` | `modelResponse` | +| **الأدوات** | `toolUse` | `toolResult` | +| **الخطافات** | `hookTriggered` | `hookCompleted` | +| **البشر** | `humanWait` | `humanInput` | + +ثلاثة تقف وحدها: `error` و `humanPause` و `humanInterrupt`. + + + +كل طريقة تأخذ أيضا `sessionId` و `agentId`، والتي تملأها النطاقات لك. أي شيء محذوف ينخفض بدلا من إرساله كـ JSON `null`. + +| الطريقة | مطلوب | اختياري | +| --- | --- | --- | +| `agentStart` | — | `goal` و `parentId` | +| `agentEnd` | — | `outcome` و `summary` | +| `agentPause` | `pauseId` | `reason` و `userId` | +| `agentResume` | `pauseId` | `reason` و `userId` | +| `modelRequest` | — | `model` و `messages` و `system` و `tools` و `requestId` | +| `modelResponse` | — | `model` و `stopReason` و `inputTokens` و `outputTokens` و `content` و `role` و `requestId` | +| `toolUse` | `toolName` و `toolCallId` | `input` | +| `toolResult` | `toolName` و `toolCallId` | `output` و `error` | +| `hookTriggered` | `hookName` و `hookId` | `triggerEvent` و `input` | +| `hookCompleted` | `hookName` و `hookId` | `outcome` و `output` و `error` | +| `error` | `errorType` و `message` | `traceback` | +| `humanWait` | `inputId` | `prompt` و `options` و `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason` و `userId` | +| `humanInterrupt` | — | `reason` و `userId` و `atStep` | + +أي مفتاح آخر تضيفه يصبح حقل حمولة مخصص. مساحة اسم أي شيء خاص بالأطر `fw_*`؛ اسم يتضارب مع حقل معلن يتم رفضه بدلا من سرقة عمود مرتقي بصمت. + + + + + **`duration_ms` يتم حسابه وليس مقبولا.** الطرق الأربع الإغلاق توقت الفجوة من الفاتح الخاص بهم وترفض `duration_ms` المموَّل من قبل المتصل — مدة مبلغة عنها لا يمكن دحضها. + + يتم مطابقة الأزواج على **الجلسة** والمعرف، لا على الوكيل أبدا. أداة مفتوحة تحت `planner` ومغلقة تحت `worker` لا تزال تقترن، وهو ما تفعله تشغيلات وكلاء متعددة متداخلة فعلا. + + +## محولات الأطر + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| الإطار | مدعوم | كيف يرفقها | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x و LangGraph.js 0.4 – 1.x | `CallbackManager.configure` لذا كل `invoke`/`stream`/`batch` مغطى بدون تمرير `callbacks:` في أي مكان — أو مرر `langchainHandler()` بنفسك ولا تصحح أي شيء. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` في موقع الاستدعاء، أو `instrument("ai")` للعملية بأكملها على `ai` 7 (على 4–6 وهذا اختياري — انظر أدناه). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream` وحل نموذج الوكيل والأداة وحل محرك تشغيل سير العمل/الخطوة. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (مشترك) بالإضافة إلى `AgentWorkflow.runStream` لتشغيل سير العمل وخطواتها. | + +يتم اختبار كل نطاق مقابل إصدارات إطار عمل حقيقية، في كلا الطرفين، كـ ES module و CommonJS، في كل تشغيل CI. + +المعيار هو Python SDK، لذا نفس البرنامج يرسم نفس الشجرة بأي لغة. البناء هو **وكيل** فقط إذا كان يمتلك حلقة قرار LLM — رسم بياني أو تشغيل سلسلة، استدعاء `generateText`/`streamText` لـ AI SDK، وكيل Mastra، تشغيل وكيل LlamaIndex. عقدة LangGraph أو خطوة سير عمل هي **خطاف** (`hook_triggered`/`hook_completed`)، لا وكيل متداخل أبدا. استدعاءات النموذج هي أزواج `model_request`/`model_response` مع عدد الرموز؛ استدعاءات الأداة تحمل معرف استدعاء الأداة الخاص بالنموذج. يتم تسجيل الفشل مرة واحدة، على الحدث الذي حدث فيه. + +محول فاشل في التثبيت يتم تسجيله وتخطيه؛ الآخرون لا يزالون يثبتون، لأن LlamaIndex المحطم يجب ألا يكلفك LangGraph. + + + `instrument()` بدون حجة يكتشف إطار عمل حسب ما إذا كان يتحل، وليس حسب ما إذا كان مستوردا بالفعل — لا يفضح Node مكافئ Python `sys.modules` لـ ES modules. الإطار الذي لديك مثبت لكن لا تستخدمه سيتم استيراده وتصحيحه. سمِّ الذي تريده إذا كان ذلك مهما. + + + + معظم هذه الأطر تشحن بناء ES-module وبناء CommonJS، والذي يحمله Node كنسختين غير ذي صلة. تصحح المحولات النسخة التي يحملها تطبيقك (والنسخة CommonJS أيضا إذا كان شيء ما قد `require`د بالفعل)، لذا كلا نظامي الوحدات يعمل. إطار **محزم في إخراجك الخاص** بواسطة esbuild أو webpack غير قابل للوصول — استخدم المساعدات في موقع الاستدعاء هناك: `langchainHandler()` و `telemetry()` و `wrapTool()`. + + +### LangChain بدون إصلاح + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +المعالج يعمل مع أو بدون `instrument()` ولا يسجل أبدا مزدوج. `instrument("langchain")` يأخذ `sessionId` و `captureContent` و `includeChains` و `graphCallbacks` و `captureLimit` كما يفعل محول Python؛ `metadata: { failproofai_sdk_session_id }` على استدعاء ينتقي الجلسة لهذا الاستدعاء. + +### Vercel AI SDK + +صادرات AI SDK وظائف عادية من وحدة ES، وفضاء الاسم لـ ES module غير قابل للتغيير بالمواصفة — لا يوجد مكان للتصحيح. يستخدم نقاط الامتداد التي يوثقها SDK نفسه: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +هذا هو التكامل الكامل: فترة وكيل واحد، زوج طلب نموذج/رد واحد لكل خطوة مع عدد الرموز، وكل استدعاء أداة. موقع استدعاء واحد يعمل على كل رائد — `ai` 4–6 يقرآن أداة التتبع الذي تحمله، `ai` 7 تكامل الملاحظات. + +`instrument("ai")` يفعل نفس العملية على **`ai` 7** في جميع أنحاء العملية: كل استدعاء، من خلال قائمة تكامل الملاحظات العالمية للـ AI SDK، والتي تضيفية وتأخذ لا شيء من أي شخص آخر. + +**على `ai` 4–6، `instrument("ai")` لا يسجل أي شيء بحد ذاته، ويسجل تحذيرا واحدا يقول ذلك.** الخطاف على مستوى العملية الوحيد الذي تملكه هذه الإصدارات الرئيسية هو موفر متتبع OpenTelemetry العام — فتحة واحدة يرفض OpenTelemetry تسليمها مرة واحدة اتخذت. تسجيل الخاص بنا سيرفض بصمت `NodeSDK.start()` الخاص بك لاحقا في البدء وإرسال أنماط http/database الخاصة بك إلى متتبع يصدر لا شيء. استخدم `telemetry()` في موقع الاستدعاء أو `wrapModel` هناك. إذا كانت العملية لا تشغل OpenTelemetry خاصة بها، اختر مع `instrument("ai", { registerGlobalTracer: true })`: فإنها ثم تسجل كل استدعاء يمرر `experimental_telemetry: { isEnabled: true }` وتأخذ الفتحة فقط إذا كانت فارغة لا تزال. `registerGlobalTracer: false` يحافظ على الافتراضي ويسكت التحذير. + +إذا كنت تفضل لف النموذج مرة واحدة، فإن `wrapModel` يرى استدعاءات النموذج فقط، لأن استدعاءات الأداة تحدث فوق طبقة النموذج. نموذج ملفوف يُستدعى بدون شيء حوله يتم تسجيله كتشغيل خاص به. استدعاء بثي ينغلق كيفما توقف التدفق — `stop_reason: "cancelled"` عندما يلغي المستهلك، `"error"` مع الخطأ عندما يفشل في منتصفه: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +استخدام كليهما على ما يرام: يلاحظ الوسيط أن الاستدعاء يتم تسجيله بالفعل ويتراجع، لذا يتم تسجيل كل استدعاء مرة واحدة. + +`functionId` يسمي فترة الوكيل. احتفظ بها منخفضة الكاردينالية — تنزل في `agent_id`، جانب لوحة التحكم الأساسي. + +### Next.js + +`next build` ينضغط تبعيات الخادم الخاص بك افتراضيا، والإطار المنضغط في البناء هو نسخة `instrument()` لا يمكنها الوصول إليه. لف الإعدادات مرة واحدة واستدعاء `instrument()` من خطاف بدء تشغيل Next: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` يضيف LangChain و Mastra و LlamaIndex و SDK نفسه إلى `serverExternalPackages` حفظ قائمتك الخاصة. بدونها، `instrument()` يحذر مرة واحدة لكل إطار لا يمكنه الوصول إليه بدلا من الفشل بصمت؛ إذا أدرجت الحزم بنفسك، اضبط `FAILPROOFAI_NEXT_EXTERNALS=1`. تعمل Vercel AI SDK ومساعدات موقع الاستدعاء بأي طريقة. الطريق Edge يحصل على بناء بدون عمليات: الاستيراد من SDK آمن ولا يسجل أي شيء. + +### عدد الرموز على استدعاءات البث + +API متوافقة OpenAI فقط تبلغ عن الاستخدام على بث عندما يطلب العميل. يطلب LangChain و Vercel AI SDK؛ بالنسبة لـ LlamaIndex مرر `additionalChatOptions: { stream_options: { include_usage: true } }` إلى `OpenAI` LLM، وبالنسبة لـ Mastra بناء النموذج مع تفعيل الاستخدام (على سبيل المثال `createOpenAICompatible({ includeUsage: true })`). وإلا فإن استدعاءات النموذج المبثوثة لا تحمل عدد الرموز. + +### المسار + +Node ≥ 20.9 و Bun و Deno — كل إطار عمل، كـ ES module وكـ CommonJS، تم اختباره على كل نقطة مقابل تتبع Node. يعمل SDK بجانب مؤشر ترابط `failproofaid` الذي ينقل ما يكتبه. + +## وكيلك الخاص — لا إطار عمل + +لحلقة وكيل كتبتها بنفسك، أو إطار بدون محول. تصدر الأحداث بنفس API الذي تستخدمه المحولات تحتها، لذا فإن التتبع له نفس الشكل والجودة. + +لا تحتاج إلى معرفة كيف يتم تنظيم الوكيل. كل وكيل مبني يدويا بالفعل له ثلاثة أماكن، مهما كانت وظائفه تُسمى، وتلك الثلاثة هي التكامل الكامل: + +| مكان | ما يضيفه | ينبعث | +| --- | --- | --- | +| حيث **تشغيل واحد** يبدأ وينتهي | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **الدالة الواحدة التي تستدعي النموذج** | `event.modelRequest` قبل و `event.modelResponse` بعد — كلا النصفين حتى عند الفشل | زوج واحد لكل منعطف نموذج | +| **الدالة الواحدة التي تشغل الأدوات** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +الهوية محيطة: كل شيء داخل `agent()` يهبط على جلسة التشغيل بدون أخذ معرف، ولا يتغير أي شيء آخر في البرنامج — بما في ذلك كل ما يكتبه الوكيل بالفعل إلى قاعدة البيانات الخاصة به. + +- **خدمة أو عامل:** مرر معرف الطلب أو الوظيفة الخاص بك كـ `sessionId` بحيث تكون جلسة على لوحة التحكم والسجل في السجلات أو قاعدة البيانات الخاصة بك نفس السلسلة. +- **وكلاء فرعيون:** عش استدعاءات `agent()`. الداخلي ينضم إلى الجلسة مع الخارجي كـ `parent_id`. +- **انبعث الأزواج.** `modelRequest` بدون `modelResponse` هو فترة يعرضها لوحة التحكم كتشغيل إلى الأبد — ومن هنا `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) في المستودع هو الإصدار الكامل القابل للتشغيل: حلقة أداة OpenAI حقيقية مجهزة بالضبط مثل هذا، وتشغيل في CI في كل تغيير كـ ES module و CommonJS. + +## التقييمات + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +انظر [مرجع Evaluator SDK](/ar/reference/evaluator-sdk) للبروتوكول وإعدادات العامل وأنواع النتائج. + + + **التقييم يجب أن يستسلم.** دالة متزامنة لا ترجع أبدا تحجب الخيط الواحد الذي يملكه Node، ولا يمكن لأي مهلة زمنية أن تحترق أثناء القيام بذلك. اكتب تقييمات `async`. + + +## ما لن تفعله لعمليتك + +| | | +| --- | --- | +| **حجب حلقة الوكيل الخاص بك** | تذهب الأحداث إلى قائمة الانتظار في الذاكرة؛ مؤقت يكتبها. المؤقت غير مرجعي، لذا لا يوقف استيراد هذه الحزمة تشغيل البرنامج النصي. | +| **النمو بدون حد** | تكون قائمة الانتظار محدودة بالعدد **و** بالبايتات المقاسة. بعد أي منهما، يتم التخلص من الأحداث الأقدم وتحذير يقول ذلك — يجب ألا تصبح انقطاعات الملاحظات قتل OOM. | +| **أسقط العملية** | حدث غير قابل للترميز واحد ينخفض وحده وليس الدفعة حوله. المؤشر الرامي والمرجع الدائري و `BigInt` والمحارف البديل الوحيدة: كل واحدة يتم التعامل معها بدلا من نشرها. | +| **اترك دفعة نصف مكتوبة** | المحتوى `fsync`ed قبل إعادة تسمية ذرية، والدليل `fsync`ed بعده، وكتابة فاشلة تنظف ملفها المؤقت. | +| **ترك النصوص قابلة للقراءة** | الدفعات هي `0600` داخل دليل `0700`. تحمل أهداف وموجهات وحجج الأداة وإخراج الأداة. | +| **وكلاء الشحن** | مفاتيح API والرموز و JWTs وعناوين bearer والتعيينات على شكل سري يتم تحديثها قبل أن تصل البايتات إلى القرص. مؤشر الترابط يحدث مرة أخرى قبل التحميل. | \ No newline at end of file diff --git a/docs/ar/reference/custom-agents.mdx b/docs/ar/reference/custom-agents.mdx index 9185cee26..b62ea2423 100644 --- a/docs/ar/reference/custom-agents.mdx +++ b/docs/ar/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -Python 3.10 أو أحدث. بدون متطلبات وقت التشغيل. +Python 3.11 أو أحدث. بدون متطلبات وقت التشغيل. ## التثبيت diff --git a/docs/ar/reference/jev-cloud.mdx b/docs/ar/reference/jev-cloud.mdx new file mode 100644 index 000000000..71472afda --- /dev/null +++ b/docs/ar/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev عبر FailproofAI Cloud" +description: "مفاتيح الآلة السحابية، وحالة الاتصال، والحدود، وسلوك الفشل لمراجعة سياسة Jev المباشرة." +icon: "cloud" +--- + +هذا مرجع مسار Cloud لـ [سياسات Jev](/ar/policies/jev). Jev، مصنف TypeSafe، يقرأ كل استدعاء أداة مقابل ما طلبته فعلاً ويجيب إلى جانب سياساتك، وليس بدلاً منها. من خلال **FailproofAI Cloud**، تستخدم الآلة المتصلة Jev بنفس المفتاح الذي تتصل به بالفعل: لا حساب TypeSafe، لا مفتاح ثانٍ، لا نقطة نهاية لتكوينها. يتم فرض رسوم على كل استدعاء لحد الخطة الموجود في مؤسستك. + +كل ما يفعله Jev لم يتغير عن [إعداد المفتاح الخاص بك](/ar/reference/jev-providers): السياسات الثابتة تظل نهائية، يتم مسح رفض السياسة القابلة للمراجعة فقط عندما تم السؤال عن Jev حول هذا الاهتمام بالضبط، وأي فشل يعود إلى نتيجة regex لهذا الاستدعاء. + + +يتطلب **failproofai 1.0.8-beta.0** أو أحدث. 1.0.7 ليس لديه Jev، حتى وإن كان يرتب فوق بيتا 1.0.7. بدون تكوين Jev لا يتغير شيء: تعمل الخطافات على سياسات regex تماماً كما كانت دائماً. + + +## قبل أن تبدأ + +ثبّت Failproof AI على الآلة حيث يعمل العامل الخاص بك وأرفق خطافاته بـ [harness مدعوم](/ar/reference/harnesses). إذا كنت تبدأ من الصفر، اتبع [quickstart](/ar/start/quickstart) حتى تثبيت الخطاف. تحقق من CLI المثبت باستخدام `failproofai --version`؛ حدّثه إذا سبق أن كان قبل Jev. تحتاج أيضاً إلى الوصول إلى صفحة **Administration → Keys** في مؤسستك لإنشاء مفتاح آلة. + +يراجع Jev استدعاءات الأدوات المسماة في بوابة `PreToolUse` أو `PermissionRequest`. لا يراجع كل حدث في جلسة. لترى Jev يمسح رفض السياسة، تحتاج إلى سياسة مثبتة محددة [قابلة للمراجعة](/ar/policies/authority)؛ يبقى جميع رفض السياسات الأخرى نهائياً. + +## تفعيله + +1. **أنشئ مفتاحاً باستخدام Jev.** في لوحة تحكم FailproofAI Cloud، افتح **Administration → Keys → Create key** واختر preset **machine**. يمنح الأذونات الثلاث التي تحتاجها الآلة: `events:add` (إرسال النشاط)، `policies:pull` (تلقي السياسات) و `jev:evaluate` (Jev، محسوبة على حد الخطة في مؤسستك). لا يمكن لمفتاح أن يحمل `jev:evaluate` بدون الاثنين الآخرين. +2. **اتصل الآلة** بهذا المفتاح. اقرأ سره لمرة واحدة عند المطالبة، ثم قم بتشغيل أمر الإعداد الكامل: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + يثبت `failproofai config` daemon، ويرفق الخطافات لـ CLIs الوكيل التي يجدها، ويربط الآلة. يبقي متغير البيئة المفتاح خارج وسيطات الأمر وسجل shell الخاص بك. إذا تم تثبيت harness الخاص بك لاحقاً، [أرفقه بوضوح](/ar/start/quickstart). + + إذا كانت مؤسستك تشغل FailproofAI Cloud الخاص بها بدلاً من المستضاف، أضف عنوانها: `--url https://` (أو صدّر `FAILPROOFAI_CLOUD_URL`). بدونه، يتم التحقق من المفتاح مقابل الخدمة المستضافة ويفشل الاتصال. إذا جاءت شهادة هذا المضيف من CA خاص، ثبّت CA في مخزن ثقة النظام للآلة (على سبيل المثال باستخدام `update-ca-certificates`)، وليس فقط في `NODE_EXTRA_CA_CERTS`: daemon الذي يرسل الأحداث ويسحب السياسات يقرأ مخزن النظام. انظر [استكشاف الأخطاء](/ar/reference/troubleshooting). + +هذا كل شيء. يخزن الاتصال المفتاح وعندما لا تملك الآلة تكوين Jev **على الإطلاق** بعد، فإنه يكتب واحداً لـ FailproofAI Cloud. من النشر الأول للآلة (حوالي 30 ثانية) يحدد FailproofAI Cloud الوضع: `enforce` بينما تم نشر سياسة Jev عليها، `off` عندما لا تكون (انظر [من يحدد الوضع](#من-يحدد-الوضع)). يقول الناتج: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +تعمل الفحوصات التي ينشرها FailproofAI Cloud على Cloud. لإضافة فحوصات خاصة بك على الآلة، ثبّت حزمة: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**مع `--no-transcripts`، لا يؤدي الاتصال إلى تشغيل Jev.** يرسل Jev كل استدعاء أداة تم فحصه والمطالبة الأخيرة إلى FailproofAI Cloud، وهو أكثر مما طُلب من اتصال يقتصر على القرارات فقط لإرساله. يتم تخزين المفتاح بشكل صحيح، والناتج يقول أن Jev متاح وكيفية تشغيله: + +```bash +failproofai jev setup --provider failproofai +``` + +كما يُطفئ Jev عبر FailproofAI Cloud **off**. يتم إزالة `jev.json` الذي يشغل Jev عبر FailproofAI Cloud (الذي تركه اتصال سابق مع transcripts مفعل) بنفس القاعدة التي يستخدمها `config --disconnect`، والناتج يقول أن Jev عبر FailproofAI Cloud يبقى معطلاً على هذه الآلة. يتم ترك `jev.json` لنقطة نهاية Jev الخاصة بك كما هو، وكذلك أحد FailproofAI Cloud الذي قمت بإيقافه (`--mode off`). + + +لا يقوم الاتصال **أبداً بالكتابة فوق** `~/.failproofai/jev.json` الموجود. إذا كنت تستخدم بالفعل نقطة نهاية Jev الخاصة بك، فستستمر في استخدامها، والناتج يقول أن الملف تم تركه كما هو مكون — وعندما يترك هذا الملف Jev معطلاً (رفضاً، أو معطلاً)، يقول ذلك وكيفية إصلاحه. للتبديل إلى FailproofAI Cloud على هذه الآلة، قم بتشغيل `failproofai jev setup --provider failproofai`. + + +## من يحدد الوضع + +على آلة متصلة بـ FailproofAI Cloud، **FailproofAI Cloud تحدد وضع Jev**؛ لا شيء على الآلة يفعل: + +- `enforce` بينما تم نشر أي سياسة Jev (أو regex + Jev) على الآلة: كل استدعاء أداة تم فحصه من وكيل تستهدفه واحدة من تلك السياسات يذهب إلى FailproofAI Cloud، التي تطلب فحوصها معاً مع فحوص الحزم المثبتة هناك. استدعاء من وكيل لا تستهدفه أي سياسة Jev السحابية، بدون فحص حزمة خاصة بها، لا يتم إرساله على الإطلاق. في `enforce`، فحوص رفض Jev الخاصة بها تمنع الاستدعاءات وكذلك مسح أحكام regex التي تراجعها. +- `off` عندما لا تكون: لا Jev على الإطلاق، مهما قال `jev.json`. + +لتجربة سياسة Jev قبل أن تتصرف، انشرها بتأثير **observe**: تطلب فحوصاتها بعد، وما كان ستفعله يسجل كـ **would-have** على صفحة السياسة، لكنها لا تمنع استدعاء أبداً ولا تمسح واحداً. `failproofai jev setup --mode` والتبديل **Settings → Jev** على لوحة التحكم يقولان أن الوضع يدار بـ FailproofAI Cloud ولا يغيران شيئاً. لا يتم استخدام `jev.json` لفحوص Cloud، حتى لو أسماها موفر آخر. `failproofai config --disconnect` يسلم Jev إلى `jev.json` الخاص بالآلة. + +ثم يقول `failproofai jev status` `Jev checks run on FailproofAI Cloud (mode: enforce)`. كما أنه يسمي الفحوصات التي تراجع كل سياسة `both`. تظهر صفحة الأسطول لماذا لا يمكن لآلة بوضع أن تسأل: + +- `transcripts_disabled`: تم توصيل الآلة بـ `--no-transcripts`، والتي لم تشغل Jev أبداً. +- `jev_unconfigured`: مفتاح الآلة لا يحمل `jev:evaluate`. +- `jev_rate_limited`: رفضت FailproofAI Cloud بعض استدعاءات الآلة لحد معدل Jev للمؤسسة، وتم اتخاذ قرار بشأن تلك الاستدعاءات بواسطة سياسات regex وحدها. +- `jev_unavailable`: فشلت عدة استدعاءات متتالية، لذا تتخطى الآلة Jev من FailproofAI Cloud لمدة دقيقة في المرة. تحاول مرة أخرى من تلقاء نفسها. + +إذا لم تجب FailproofAI Cloud خلال 5 ثوانٍ، فإن سياسات regex تقرر وحدها، كما هو الحال في أي انقطاع Jev. بعد 3 فشل متتالي توقف الآلة عن السؤال لمدة دقيقة في المرة، لذا فإن انقطاع Cloud لا يبطئ كل استدعاء أداة. + +لا يوقف pause الجلسة (`failproofai config --pause`) فحوص Jev من FailproofAI Cloud، تماماً كما لا يوقف السياسات التي يديرها Cloud. إنه يوقف فحوصات Jev للحزم المثبتة على الآلة. + +## تحقق مما يفعله + +```bash +failproofai jev status +failproofai jev test +``` + +يعرض `status` الموفر كـ **FailproofAI Cloud**، مضيف Cloud الذي اتصلت الآلة به، الوضع، ومصدر المفتاح كـ **FailproofAI Cloud connection**، وليس المفتاح أبداً. عندما يكون `jev.json` من FailproofAI Cloud موجوداً لكن لا يمكن لـ Jev الجري، يقول السبب: + +| يقول `status` | `status --json` | المعنى | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | الآلة متصلة، لكن لا يتم تخزين مفتاح Jev لها: المفتاح يفتقد `jev:evaluate`، أو لم يتمكن الاتصال من تأكيده. قم بتشغيل `failproofai config` مرة أخرى مع المفتاح في `FAILPROOFAI_CLOUD_TOKEN`؛ إذا افتقده الإذن، استخدم مفتاح **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | لا توجد اتصال FailproofAI Cloud على هذه الآلة ليتعلق به مفتاح Jev. | + +بعد `failproofai config --disconnect` لا يوجد `jev.json` من FailproofAI Cloud بعد الآن (إلا إذا تم إيقافه، الذي يتم الاحتفاظ به)، لذا يبلغ `status` ببساطة عن Jev معطل. `status --json` يحمل نفس الحقائق (`provider: "failproofai"`، `keySource: "cloud"`، `cloudConnected`، `keyCarriesJev`)، أيضاً عند غياب الإعدادات أو رفضها. `permissions` هي دائماً من `jev.json`؛ رفض حول `credentials.json` يضيف `credentialsPermissions`، و `fix` عندما يصلح أمر واحد. يرسل `test` طلب حي واحد ويبلغ عن الكمون والإصدار Jev الذي أجاب. ينهي مع 1، ويقول ذلك في عنوانه، عندما تصل الإجابة بعد انتهاء timeout الخطاف (الخطافات ستسجل `timeout`) أو تجيب على سؤال فحصه بشكل خاطئ. + +تعرض لوحة **Settings → Jev** على لوحة التحكم أيضاً **FailproofAI Cloud connection**: المؤسسة التي تبلغ عنها الآلة وما إذا كان مفتاحها يحمل Jev. يتم قراءتها من ملفاتك الخاصة على الآلة، بدون استدعاء شبكة. + +## تحقق من استدعاء فعلي + +ابدأ جلسة جديدة في الوكيل المرتبط. اطلب منه استخدام أداة قراءة الملفات على `README.md` والإبلاغ عن العنوان. تأكد من احتواء الجلسة على استدعاء الأداة هذا، ثم قم بتشغيل `failproofai jev status` مرة أخرى: يجب أن يزيد عدد الاستدعاءات المقيمة الأخيرة. افتح **Policies → Activity** في [لوحة تحكم محلية](/ar/reference/local-dashboard#review-policy-activity) لفحص حكم Jev وضع هذا الاستدعاء. في Cloud، تعرض صفحة **Policies** للمؤسسة نتائج Jev للنشاط المُسلم. في وضع observe، يتم تسجيل الحكم كـ **would-have** وتقرر نتيجة السياسة بعد الاستدعاء. يظهر الامتصاص فقط عندما تطابقت سياسة قابلة للمراجعة ومحى Jev فحوصاتها المسماة. + +## ما يصل إلى صفحة السياسة + +الآلة ترسل بالفعل نشاط الخطاف إلى FailproofAI Cloud (`events:add`). مع Jev قيد التشغيل، يقول سجل الاستدعاء المراقب أيضاً أي محيّم قام، ما قررته Jev، أي السياسات التي مسحتها، لماذا تراجعت عند قيامها، الكمون الخاص بها والنموذج الذي أجاب — القرارات، والرموز والأسماء، وليس الأمر أو المطالبة. على صفحة **Policies** للمؤسسة: + +- استدعاء قررته حكم Jev الخاص به (وضع enforce) يُنسب إلى **Jev**، وعندما جاء الفحص المقرر من حزمة، يسمي السجل أيضاً تلك الحزمة والإصدار؛ +- في وضع observe، يظهر الرفض أو التحذير من Jev كـ **would-have**، بجانب الطرح الذي تراقبه؛ +- السياسات التي مسحتها Jev، أو كانت ستمسحها في وضع observe، تُحسب لكل سياسة. +- قرار شاركت فيه Jev (كتل، تحذير، امتصاص، أو would-have في وضع observe) يسرد كل فحص طلبته وما استنتجه ذلك الفحص: الحكم، لماذا (`not-detected`، `exempt`، `fired`، `op-requested`، إلخ)، دليله `p`، إجابة `exempt` وكل إجابة probe. يتم إدراج فحص سياسة تم نشرها للمراقبة (observe)، محسوماً watched؛ لا يمنع أبداً. تجيب Jev باحتماليات، وليس نصوصاً، لذا لا توجد سبب نص حر. الأذونات البسيطة تُطوى في الأعداد ولا تحمل هذه القائمة. + +## عندما لا يستطيع Jev الإجابة + +كل واحد من هذه يعود إلى نتيجة سياساتك لهذا الاستدعاء، ويتم تسجيله مع سببه: + +| السبب | الأسباب | +| --- | --- | +| `out-of-credits` | استخدمت المؤسسة حد الخطة. | +| `http-401`، `http-403` | تم إلغاء المفتاح، أو لا يحمل `jev:evaluate`. أعد الاتصال بمفتاح يفعل. | +| `http-429` | FailproofAI Cloud تحد من معدل Jev لمؤسستك. حتى ينتهي الانتظار الذي تطلبه (الرد `Retry-After`، بحد أقصى 60 ثانية)، لا ترسل الآلة شيئاً وكل استدعاء يعود على الفور. يتم تسجيل الاستدعاءات المحبوسة بهذه الطريقة كـ `http-429`، أو كـ `rate-limited` عندما يحبسها حد معدل الآلة الخاص بها أولاً. | +| `http-429` (حد يومي) | استخدمت المؤسسة استدعاءات Jev اليومية: **10,000 لكل يوم UTC**، إلا إذا حدد من يشغل FailproofAI Cloud حداً آخر. كل استدعاء يعود حتى يعاد تعيين العداد في 00:00 UTC؛ تسأل الآلة بعد مرة في الدقيقة على الأكثر، لذا تختار إعادة التعيين في غضون دقيقة. يقول `failproofai jev test` "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | رفضت Jev طلب هذا الاستدعاء، عادة لأن استدعاء الأداة احتفظ بنص كثيف (base64، hex، code مضغوط) على ميزانية رموز Jev. هذا الاستدعاء يعود كل مرة؛ إنه ليس انقطاعاً. | +| `http-502` | Jev غير متاح الآن. | +| `http-503` | لا يستطيع Cloud هذا تقديم Jev لمؤسستك: لا بوابة نموذج، مؤسسة لم تُزود بعد، أو بوابة معطلة. اسأل مسؤولك؛ تسأل الخطافات مرة أخرى على الأكثر في الدقيقة. | +| `http-404` | FailproofAI Cloud هذا لا يقدم Jev بعد. | +| `timeout` | لا إجابة خلال `timeoutMs` (الافتراضي 3000). بينما يحدد FailproofAI Cloud وضع Jev للآلة، الانتظار هو 5000 ms و `timeoutMs` من `jev.json` لم يستخدم. | +| `model-mismatch` | أجاب إصدار Jev آخر غير 1.13. | + +## حيث يعيش المفتاح وأين يذهب + +- يتم تخزين المفتاح مرة واحدة، في `~/.failproofai/credentials.json` (`0600`، في مجلد مالك فقط)، بجانب بيانات اعتماد FailproofAI Cloud الأخرى. لا يحمل `jev.json` مفتاحاً لهذا المسار؛ واحد مكتوب هناك يجعل الإعدادات غير صالحة. +- إذا كان `credentials.json` يحمل **أي** إذن لأي شخص غيرك (مجموعة أو آخرون، قراءة أو كتابة)، أو يمكن كتابة مجلده بـ **أي شخص** غيرك، فإنه **مرفوض**، لا يُقرأ، و Jev معطل حتى تصلحه: `chmod 600` على الملف، `chmod 700` على المجلد (أو أعد الاتصال، الذي يعيد كتابة الملف في `0600` ويجعل المجلد مالك فقط). المجلد الذي يمكن لآخرين قراءته فقط بخير؛ واحد يمكنهم الكتابة فيه يسمح لهم بمبادلة الملف. +- يعتمد المفتاح فقط بينما الاتصال الذي جاء معه على الآلة: سياسة أو بيانات اعتماد إبلاغ لـ نفس FailproofAI Cloud **بنفس المفتاح**، في نفس الملف. مفتاح Jev تُرك خلفاً بدون واحد يُتجاهل، و Jev يبقى معطلاً. يحدث عندما يترك failproofai الأقدم مفتاح Jev موضعه `config --disconnect` (لا يعرف إزالته)، أو عندما يتصل failproofai الأقدم `config --token` بمفتاح آخر، الذي قد ينتمي إلى مؤسسة أخرى على FailproofAI Cloud. لتشغيل Jev مرة أخرى، اتصل مرة أخرى بمفتاح **machine**. +- يتم إرسال المفتاح فقط لأصل Cloud الذي تحقق منه. `jev.json` يشير في أي مكان آخر مرفوض. +- **وكيل على الآلة يمكنه قراءتها.** `credentials.json` مالك فقط، والوكيل يعمل كهذا المالك. السماح بقراءة ملفات failproofai الخاصة مقصودة (فقط تغيير يتم حجبه، بـ `block-failproofai-commands`)، لذا الشيء الوحيد بين الوكيل وهذا الملف هو `block-read-outside-cwd` — سياسة *قابلة للمراجعة* — ومن جلسة بدأت في مجلد المنزل، لا شيء. مفتاح يحمل `jev:evaluate` ينفق حد allowance Jev للمؤسسة (حتى الحد اليومي) من أي مكان يُستخدم، لذا تعامل مع مفتاح الآلة مثل أي بيانات اعتماد الإنفاق الأخرى: إذا كان قد يقرأه الوكيل، أوقفه على صفحة المفاتيح وأعد الاتصال بمفتاح جديد. +- فقط الملفات العامة تقرر هذا. لا يمكن لمستودع تشغيل Cloud Jev، أو الإشارة إليه في مكان آخر أو توفير مفتاحه، و `FAILPROOFAI_JEV_API_KEY` يتم تجاهله لهذا المسار. +- لكل استدعاء Jev يقيّمه، يذهب طلب واحد إلى FailproofAI Cloud، يحمل ما تسرده [صفحة المفتاح الخاص بك](/ar/reference/jev-providers#what-leaves-the-machine) (الأسرار محررة). ترسل FailproofAI Cloud إلى TypeSafe ولا تسجل أو تحتفظ به. + +## أطفئه + +على آلة متصلة، Jev معطل عندما لم تنشر FailproofAI Cloud سياسة Jev عليها: أزل أو أرشّف سياسات Jev هناك. + +| الأمر | النتيجة | +| --- | --- | +| أزل سياسات Jev للآلة في FailproofAI Cloud | يصبح وضع Cloud `off` في الاستطلاع التالي (حوالي 30 ثانية): لا Jev على الإطلاق، مهما قال `jev.json`. | +| `failproofai config --disconnect` | افصل الآلة: يتم إزالة المفتاح، وكذلك `jev.json` عندما يسمي FailproofAI Cloud وليس معطلاً. يتم ترك `jev.json` لنقطة نهاية خاصة بك. | + +من الاستدعاء التالي للأداة، تعمل الخطافات على سياسات regex تماماً كما كانت من قبل. \ No newline at end of file diff --git a/docs/ar/reference/jev-evaluations.mdx b/docs/ar/reference/jev-evaluations.mdx new file mode 100644 index 000000000..17a059bd1 --- /dev/null +++ b/docs/ar/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "مرجع تقييم Jev" +description: "أنواع الأسئلة والدرجات المعايرة والحدود والملء الخلفي لتقييمات جلسات Jev." +icon: "list-checks" +--- + +تصف هذه الصفحة أشكال الأسئلة وقواعد التصحيح وراء [تقييمات Jev](/ar/evaluations/jev). بعض الأسئلة تتطلب من النموذج أن *يقرأ* المحادثة، لكن ليس أن *يكتب* عنها. "هل أعرب العميل عن الاستعجالية؟" له إجابتان. "ما مدى إحباطهم؟" له عدد قليل، مرتب بترتيب معين. تعرف كل إجابة قبل أن تسأل. + +**تقييم التصنيف** مخصص لهذه الحالات بالضبط. تكتب السؤال والإجابات التي قد يعطيها، ونموذج صغير مدمج للتصنيف يعيد رقماً معايراً — لا مطلقاً نصاً حراً. + + +مثل القاضي، تقييم التصنيف يكلف استدعاء نموذج واحد لكل جلسة. لكن على عكسه، إنه نموذج صغير موجه لغرض واحد بدلاً من نموذج عام، لذا فهو أسرع وأرخص — لكنه لن يشرح نفسه أبداً. إذا كنت بحاجة إلى التفكير، استخدم [القاضي](/ar/evaluations/judge). + + +## أي واحد أريد؟ + +| السؤال | الاستخدام | +| --- | --- | +| كم عدد استدعاءات الأدوات؟ | code | +| هل كانت الجلسة أقل من 30 ثانية؟ | code | +| هل أعرب العميل عن الاستعجالية؟ | **classifier** | +| أي فريق يجب أن يتولى هذا: الفواتير أو الدعم الفني أو المبيعات؟ | **classifier** | +| ما مدى إحباط العميل؟ | **classifier** | +| هل كانت الإجابة صحيحة فعلاً؟ | **judge** | +| هل اتبعت سياسة التصعيد لدينا، ولماذا تعتقد ذلك؟ | **judge** | + +القاعدة الذهبية: **يمكن عده → code، إجابات يمكنك إدراجها → classifier، يحتاج شرح → judge.** + +لا تضطر للقرار مقدماً. صف ما تريد قياسه والمساعد يختار، ويخبرك بما اختاره ولماذا، ويمكنك تبديله. + +## نوعا الأسئلة + +### `noul` — هل هذا صحيح؟ + +إجابتان، وتصف كليهما. النتيجة هي احتمال أن وصف "true" ينطبق: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +صف كلا الجانبين. "لم يتم التعبير عن استعجالية" هي إجابة حقيقية وقول ذلك يجعل الآخر أحد. + +### `score` — ما مقدار هذا؟ + +مقياس مرتب، **الأسوأ أولاً**. النتيجة هي حيث تقع الجلسة عليه، معاد تحجيمها إلى 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**المقياس يأخذ ثلاثة إلى خمسة مستويات، وجميعها يجب أن تكون مختلفة.** كلا الحدين يتم قياسهما، لا أسلوباً: + +- **مستويان** ينهار في ما يفعله `noul` بالفعل بشكل أفضل، و**أكثر من خمسة** يجعل النموذج يتردد نحو الوسط بدلاً من الالتزام. نفس السؤال على نفس الجلسة سجل 0.00 مع مستويين، 0.01 مع ثلاثة، و0.55 مع عشرة. +- **المستويات المكررة** تقسم الإجابة بشكل عشوائي بينهما. جلسة كانت غاضبة بلا لبس سجلت 1.00 مقابل `["Calm", "Frustrated", "Very angry"]` و0.66 مقابل `["Angry", "Angry", "Angry"]` — رقم معشوق ينوء بلا معنى. + +الفئات بلا ترتيب — "الفواتير أو الدعم الفني أو المبيعات" — ليست مقياساً. اسأل عنها كـ `noul` لكل فئة، أو استخدم القاضي. + +## قراءة النتائج + +ينتج التصنيف **درجة** من 0 إلى 1، تماماً كالقاضي، لذا فهو يرسم، يصفي، ويطلق التنبيهات بنفس الطريقة. الفرقان يستحقان المعرفة: + +- **لا يوجد تفكير.** الحقل فارغ، عن قصد. هذا النموذج لا يشرح نفسه، وتأليف شرح سيكون مختلقاً وليس ميزة. +- **عدم اليقين مسمى.** سؤال `score` يبلغ عن ثقته الخاصة، والنتيجة التي كان النموذج غير متأكد منها يتم وسمها `low_confidence` — لذا "أي من هذه يجب على الإنسان أن ينظر إليه" هو مرشح بدلاً من تخمين. سؤال `noul` لا يبلغ عن الثقة، لذا لا يتم وسمه أبداً. + +الجلسات الطويلة جداً تُقرأ في مقتطفات ويتم دمجها. عندما تكون جلسة طويلة جداً للقراءة بشكل كامل، تقول النتيجة كم دوراً تم حذفه — لن ترى أبداً حكماً صدر على جزء من جلسة يُعرض على أنه حكم على كلها. + +## الحدود + +- **ثلاثة إلى خمسة مستويات مقياس، جميعها متميزة.** انظر أعلاه؛ كلا الحدين يُفرضان في وقت التأليف. +- **سؤال واحد لكل تقييم.** اسأل شيئين وتحصل على تقييمين، وهذا أيضاً ما تريده على رسم بياني. +- **تحرير السؤال ينشر نسخة جديدة.** الدرجات القديمة والجديدة غير قابلة للمقارنة، لذا يتم فصلها بدلاً من مزجها في خط اتجاه واحد. +- **التصنيف ينتج دائماً درجة**، لا مقياس أو تأكيد. +- **بلا تفكير**، كما هو أعلاه. إذا كان الرقم سيجعل شخصاً ما يسأل "لماذا؟"، اكتب قاضياً بدلاً من ذلك. + +## الاختبار والملء الخلفي + +على عكس القاضي، تقييم التصنيف **يمكن** اختباره قبل النشر — [اختبره](/ar/evaluations/test) مقابل جلسات حقيقية بنفس الطريقة التي تختبر بها تقييم code، واقرأ الدرجات قبل أن يذهب أي شيء مباشر. + +يمكن أيضاً [ملأها خلفياً](/ar/evaluations/deploy#score-sessions-you-already-have) على جلسات لديك بالفعل. يكلف استدعاء نموذج واحد لكل جلسة، لذا حدد نطاق الإطار الزمني عن قصد بدلاً من إعادة تشغيل كل شيء. \ No newline at end of file diff --git a/docs/ar/reference/jev-intent.mdx b/docs/ar/reference/jev-intent.mdx new file mode 100644 index 000000000..4efeaacb6 --- /dev/null +++ b/docs/ar/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "التقاط نية Jev" +description: "أي أحداث الحزام تخبر مقيم Jev بما طلبه الإنسان، أي حقل يحمل النص، ما لا يتم عده أبداً، والمخاطر التي تأتي مع الثقة بالمطالبة المسلمة من الحزام." +icon: "message-square-quote" +--- + +عندما تقوم بتكوين [مراجعة سياسة Jev](/ar/policies/jev)، يحكم المقيم كل استدعاء أداة محسوب مقابل **ما طلبه الإنسان بالفعل**، وليس مقابل أي نص وضعه الحزام أمام الوكيل. يمكن لرد مثل "نعم، أجبر الدفع" أن يمسح سياسة **قابلة للمراجعة** — وهذا هو الهدف كله من المقيم، لأن regex الذي لا يستطيع قراءة الطلب يحجب ثلث العمل الفعلي. + +يأتي هذا النص من مكان واحد: **المطالبة التي يسلمها الحزام نفسه إلى الخطاف في حدثه prompt-submit**. يسجل Failproof AI الجزء الذي كتبه الإنسان — تم تجريد تغليف الحزام، وتم تحرير الأسرار، ومحدود — في ملف `0600` تحت دليل حالته الخاص. لا يتم استشارة أي شيء على القرص: نسخة جلسة العمل هي ملف يمكن للوكيل إعادة كتابته بأمر واحد، لذا لا يتم طلب منه أبداً من كتب المطالبة. + +## المخاطر التي يقبلها هذا، بوضوح + +يمكن لوكيل يستطيع بالفعل تشغيل الأوامر أن يجعل الحزام يرسل مطالبة. `claude -p "…"`، `codex exec`، `copilot -p`، `cursor-agent -p`، `devin -p`، `droid -p`، `goose run -t` و `pi -p` كل منها يطلق حدث prompt-submit نفسه، بنفس الحمل، كما يفعل شخص يكتب، في جلسة فرعية يتحكم بها هذا الوكيل. يمكنه أيضاً تشغيل ثنائي الخطاف الخاص بـ Failproof AI وتغذيته بحمل كتبه. لا يمكن لأي شيء داخل Failproof AI تمييز أحدهما عن الآخر — كلاهما نفس البرنامج يقرأ stdin نفسه. + +**لذا يمكن لوكيل لديه shell أن يزيف موافقته الخاصة.** هذا تبادل مقصود، تم اتخاذه في 2026-09-23، وإليك كلا الجانبين: + +- **ما يشتريه.** البديل تم بناؤه وقياسه: يتطلب حقلاً يسمي فيه الحزام إنساناً باعتباره مؤلف المطالبة، وتسجيل لا شيء وإلا. لا يرسل أي حزام شحن مثل هذا الحقل، لذا سجلت هذه النسخة **لا شيء، على كل حزام** — حكم Jev على كل استدعاء بدون نية معلنة ولا يمكن أبداً مسح سياسة واحدة. التقاط لا ينطلق أبداً ليس منتجاً أكثر أماناً، إنه لا منتج. +- **ما لا يستطيع فعله.** تسجيل المطالبة يمسح فقط سياسة معلمة بالفعل باعتبارها **قابلة للمراجعة**. سياسة **صعبة** لا تمسح أبداً بأي شيء يقوله Jev، لذا لا يمكن لمطالبة مزيفة أن تحول رفض صعب إلى سماح — والقفز فوق الخطاف لا يكسب الوكيل شيئاً على أي حال: يستدعي الحزام Failproof AI للاستدعاء الأداة بشكل مستقل. +- **ما يمكنه فعله، بالحجم الكامل.** أسوأ ما يمكنه فعله هو مسح واحدة من السياسات المدمجة الخمس عشرة القابلة للمراجعة — و**اثنتا عشرة من تلك الخمس عشرة تحجب**. `protect-env-vars`، `block-env-files`، `block-read-outside-cwd`، `block-rm-rf`، `block-force-push`، `block-secrets-write` والستة كتل CLI للبنية التحتية (`block-kubectl`، `block-terraform`، `block-aws-cli`، `block-gcloud`، `block-az-cli`، `block-helm`) هي رفوض، لذا يمكن للموافقة المزيفة أن تحول رفض حقيقي إلى سماح لطباعة أسرار البيئة، قراءة ملف `.env`، القراءة خارج المشروع، `rm -rf`، دفع قسري، كتابة ملف أسرار، أو تغيير البنية التحتية المباشرة. فقط `warn-git-amend`، `warn-destructive-sql` و `warn-global-package-install` هي دفعات. التثبيت الافتراضي يشغل اثنين من الاثني عشر، `protect-env-vars` و `block-env-files`؛ العشرة الأخرى تصل فقط إلى جهاز حيث مكّن شخص ما لهم. ما لا تصل إليه أي مطالبة هو كل شيء صعب — `block-sudo`، `block-curl-pipe-sh`، `block-push-master`، `block-work-on-main`، الحارس الذي يوقف الوكيل من تعطيل Failproof AI، وكل مدمج آخر لم يتم تعليمه قابل للمراجعة. [سلطة السياسة](/ar/policies/authority) تسرد جميع الخمس عشرة وما يراجعه كل واحد منها. + +ما يزال مرفوضاً هو كل شيء رخيص الفحص وأن الوكيل لا يستطيع الحصول عليه فقط بالسؤال: دور الحزام الخاص به يعلمه كمرسل من الآلة، حمل يسمي وكيل فرعي، معرّف جلسة ليس اسماً عادياً، حدث ليس prompt-submit، ونص ليس سوى تغليف الحزام — بما في ذلك كلمات التوقف الخاصة بـ Failproof AI، التي ترسلها عدة حزم كالدور التالي للمستخدم. + +## جدول لكل حزام + +"حقل النص" هو حقل حمل stdin بعد تطبيع Failproof AI لكل حزام. "تسجيل" يقول ما إذا تم الاحتفاظ بالمطالبة كطلب الإنسان. + +| الحزام | `--cli` | حدث المطالبة → القياسي | حقل النص | مسجل | آخر رسالة للوكيل تُقرأ من | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | نعم، إلا إذا كان `source` الحمل يسمي دوراً لم يرسله أحد (`loop_wakeup`، `schedule_wakeup`، `poll_event`، `system`). `user`، `sdk`، قيمة غير معروفة، وبناء لا يرسل `source` على الإطلاق كلها مسجلة | نسخة جلسة العمل (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | نعم | rollout JSONL (`agent_message`، `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | نعم | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | نعم، مع تجريد غلاف `` عندما يكون المطالبة كاملة | نسخة نص وكيل JSONL | +| OpenCode | `opencode` | `message.updated` (دور المستخدم) → `UserPromptSubmit` | `prompt` | نعم — لكن OpenCode الحالي لا يحمل نص في هذا الحدث، لذا في الواقع لا شيء مسجل؛ تكرار نفس الرسالة يسجل مرة واحدة | لا شيء (الجلسات SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | نعم، إلا إذا كان `input_source` هو `extension` — `sendUserMessage()` لملحق آخر، التي يمكن أن يكون نصها مكتوب من نموذج أو مشتق من repo | جلسة Pi JSONL | +| Hermes | `hermes` | لا شيء | — | لا — Hermes ليس لديه حدث prompt-submit على الإطلاق | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | نعم، إلا إذا كانت بيانات التشغيل تعلم التشغيل كآلة: `trigger` آخر من `user`، `inputProvenance.kind` آخر من `external_user`، أو `senderIsOwner: false` | لا شيء (`before_agent_run` لا يحمل مسار نسخة) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | نعم | جلسة droid JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | نعم | لا شيء (الجلسات SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | لا شيء | لا — `PreInvocation` ينطلق قبل *كل* استدعاء نموذج في دور ولا يحمل نص المطالبة | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | نعم | لا شيء (الجلسات SQLite) | + +حزامان لا يسجلان لا شيء، وللسبب نفسه في كلا الحالتين: حدثهما لا يسلم نص إنسان. Hermes ليس لديه حدث prompt-submit — يتعامل الملحق الأصلي مع `pre_llm_call` بنفسه ويعيد فقط أحداث الأداة والجلسة والوكيل الفرعي. `PreInvocation` من Antigravity ينطلق قبل كل استدعاء نموذج، على دور إنسان وعلى الخمسة التي تتبعها، ولا يحمل حقل المطالبة؛ يمكن للخطافات أيضاً حقن خطوات `userMessage` في نفس الحوار. لا يوجد شيء في أي من الحدثين لتسجيل. + +## ما يجعل المطالبة للإنسان + +1. **الحدث.** تم استدعاء Failproof AI لحدث prompt-submit الحزام، الذي يقوم المعالج بتطبيعه إلى `UserPromptSubmit`. +2. **الحمل.** يكتبه الحزام على stdin الخطاف، ويحمل النص في الحقل المسمى أعلاه. الاستدعاء الذي يصل إلى Failproof AI بدون الحمل لا يسجل لا شيء. +3. **لا شيء في الحمل يحكم الدور بعدم القبول.** حمل يسمي وكيل فرعي (`agent_id`) هو الوكيل يثير نفسه. `source`، `input_source` أو علامة تشغيل OpenClaw التي تسمي دور مُرسل من الآلة يُرفض. علامة **غائبة** لا تحكم لا شيء — هذا هو الفرق عن النسخة التي لم تسجل لا شيء، منذ كل علامة هنا غائبة على كل بناء شحن. +4. **هناك شيء ما متبقي بعد تجريد التغليف** (انظر أدناه). + +**نسخة جلسة العمل ليست دليل على من كتب مطالبة.** وصفت الإصدارات السابقة من هذه الصفحة فحص نقل متقاطع: تم رفض المطالبة إذا أظهرت النسخة أن النموذج جدولها، وكان يجب على النسخة أن تستمر بما رآه الطلب السابق. هذا الفحص قد ولّى. النسخة هي ملف للوكيل بالفعل لديه shell عليها — يمكن اختصاره أو استبداله أو الحشو الماضي ميزانية القراءة أو الإلتقاط في بداية الدور واستعادة في النهاية أو جعل القراءة جيدة مرة أخرى مع إدخالات كتبها الوكيل. كل جولة تصليب تبعتها تهجية أخرى من نفس التزوير، لذلك تم إزالة الآلية كاملة بدلاً من إصلاحها. + +النسخة تُقرأ لشيء واحد: **آخر رسالة مرئية للوكيل**. تلك الرسالة مكتوبة من الوكيل بالتعريف، يُخبر Jev به، وهو لا يقبل لوحده أبداً. + +## ما يتم الاحتفاظ به من المطالبة + +تضع الحزم أكثر من كلمات الإنسان في المطالبة. قبل تخزين أي شيء: + +- تتم إزالة كتل ``، والاحتفاظ بكلمات الإنسان حولها. +- يتم حذف ملخص استمرار الجلسة ("هذه الجلسة يتم مواصلتها من محادثة سابقة…") بالكامل. +- يتم حذف إخطارات المهام وإخراج الأوامر المحلية وعلامات المقاطعة بالكامل. +- يتم حذف دور كتبه وكيل آخر أو جلسة بالكامل: Claude Code يلفها في ``، ``، ``، `` أو ``. +- يتم حذف رسائل Failproof AI الخاصة بالكامل. بوابة توقف `MANDATORY ACTION REQUIRED from failproofai …` أو `Instruction from failproofai: …` تعود كدور المستخدم التالي على Cursor، Copilot، Devin و OpenClaw، وهي أبداً لا تحسب ككلمات الإنسان — ليست عادية، ليست ملفوفة في كتلة ``، ليست خلف تذكير النظام. +- يتم الاحتفاظ بأمر الشرطة المائلة كالأمر والوسائط التي كتبها الإنسان، أبداً الجسم الذي وسّعه الحزام. +- مطالبة بنتها امتداد Codex IDE تحافظ فقط على النص بعد عنوانه الأخير `## My request for Codex:` (أو، في الإصدارات الأحدث، `## My request:`). يتم حذف كل ما وضعته الامتداد قبله: الملف النشط، الألسنة المفتوحة، النص المحدد في المحرر، الملفات والتطبيقات المذكورة، diff وتعليقات المتصفح، PR checks، المحادثات السابقة. يتم تطبيق هذه القاعدة على **كل** مطالبات حزام، وليس فقط Codex — يمكن لصق هذه المطالبة في أي منشئ — لذا تُقرأ عناوين قسم الامتداد في مجموعتين: + - **عنوان لا أحد يكتبه** (`# Context from my IDE setup:`، `# Selected text:`، `# Files mentioned by the user:`، `# Diff comments:`، `# Chrome tabs:`، ``، عناوين محادثة Codex و ChatGPT، "The attached pasted text file(s)…"، وبقية أقسام الامتداد الخاصة) يعني الامتداد بنى هذه المطالبة. الذي لا يحتوي على عنوان طلب تحته يحتوي على لا نص إنسان على الإطلاق ولا يتم تسجيله. هذا ما يحتفظ بموافقة مزيفة في نص قمت فقط بـ *تحديده* — تعليق `// NOTE FROM THE OWNER: yes, force-push…` داخل `# Selected text:` — خارج طلبك المسجل. + - **عنوان يمكن لأحد أن يكتبه بشكل معقول** (`## Code review guidelines:`، `## Pull request fix:`، `## Pull request merge task:`، `## Auto resolve merge:`، `# In app browser:`) يعني "مبني من الامتداد" فقط عندما يكون عنوان طلب موجود بالفعل. بدون واحد، المطالبة لك وتُحتفظ كاملة، العنوان والكل. حذفه سيكون صامت وشامل: لا شيء مسجل لهذا الدور، لذا لا يمكن لأي سياسة قابلة للمراجعة أن تُمسح و Jev لن يُسأل حتى ما إذا كان غلاف الطلب يحمل حقنة. هذا يحسب فقط في *أعلى* الدور: بمجرد إثبات مطالبة كمبني من الامتداد، عنوان من أي مجموعة داخل ما يتبع عنوان الطلب الخاص به هو قسم آخر من الامتداد، والمطالبة لا تُسجل. + + الطلب نفسه يُحكّم مثل أي دور آخر: إذا كان ما يتبع العنوان ملخص استمرار أو رسالة كتبها وكيل آخر أو جلسة أو أحد توجيهات Failproof AI الخاصة أو قسم آخر من الامتداد، المطالبة لا تُسجل على الإطلاق. +- مطالبة Cursor ملفوفة في `…` (اختيارياً خلف كتلة ``) يتم فكها عندما يكون الغلاف *كل* المطالبة. علامة في أي مكان آخر هو نص عادي — مقتطف ملصوق من سجل أو اسم فرع اختاره الوكيل — والمطالبة تُحتفظ كاملة بدلاً من القطع إلى الفترة الموسومة. +- تُحتفظ بالكتل الملصوقة وتُعلّم كملصوقة من الإنسان. + +مطالبة ليست سوى نص الحزام لا تُسجل على الإطلاق. + +## رسالة الوكيل الأخيرة + +رد مثل "نعم" لا يعني لا شيء بدون السؤال الذي يجيب عليه. عندما تُسجل مطالبة، يقرأ Failproof AI أيضاً آخر رسالة مرئية للوكيل من نسخة جلسة العمل **في تلك اللحظة**، ويخزنها مع المطالبة. يتلقاها Jev في حقلها الخاص، معلّمة كمكتوبة من الوكيل: توضح رد قصير ولا تحسب أبداً ككلب الإنسان على حسابها الخاص. إنه الشيء الوحيد الذي تُقرأ النسخة من أجله، وأسوأ ما يمكن لنسخة مُعادة الكتابة فعله هو وضع رسالة كتبها الوكيل حيث الرسالة التي كتبها الوكيل متوقعة. + +يتم قراءتها من نهاية النسخة، على الأكثر آخر 4 MB. صيغ النسخ المدعومة هي Claude Code، Codex rollouts (أحداث `agent_message` الأقدم وعناصر `AgentMessage` الأحدث)، Cursor، Copilot `events.jsonl`، و Pi و Factory و OpenClaw جلسة JSONL. يتم تخطي الرسائل الاصطناعية الخاصة بـ Claude Code وأخطاء API ورسائل الوكيل الفرعي (sidechain). لا توجد لقطة لـ Goose و OpenCode، التي تحافظ على الجلسات في SQLite، لـ Devin، التي تخزن النسخة في وثيقة JSON واحدة، أو لـ OpenClaw، التي لا يحمل حدث `before_agent_run` الخاص بها مسار النسخة. + +## التخزين + +| الخاصية | القيمة | +| --- | --- | +| الموقع | `~/.failproofai/state/semantic/sessions//.json`، حيث `` هو ملف تعريف وكيل الطلب الذي تم كتابته: `.` للوكيل Failproof AI يعرفه (هوية السياسات السحابية تستهدفها)، أو فقط `` وإلا | +| الأذونات | ملف `0600`، دليل `0700`. كل دليل فوقه، يصل إلى `~/.failproofai`، يُحتفظ به بنفس قاعدة ديريه من `jev.json`: واحد يمكن لأي شخص آخر **كتابة** إليه يمكن إعادة تسميته واستبداله، لذا يأخذ مسار القراءة تلك أجزاء الكتابة حيث يمكنه، ولا **يقرأ** أي شيء حيث لا يستطيع. مطالبة مسجلة ثم غائبة بدلاً من مزيفة، ولا شيء يُمسح | +| المحفوظ لكل جلسة | آخر 5 مطالبات؛ مطالبة متطابقة لتلك السابقة تستبدلها بدلاً من أخذ فتحة جديدة | +| النافذة | المطالبات أقدم من 6 ساعات يتم تجاهلها | +| الحجم | كل مطالبة ورسالة وكيل تحد عند 6,000 حرف، الاحتفاظ بالرأس والذيل | +| الأسرار | يتم تحريرها بنفس الأنماط مثل سياسات `sanitize-*` قبل كتابة أي شيء. نص أطول من 48,000 حرف يُحرّر كـ 28,800 الأول و 19,200 الأخير، والنص بجانب تلك القطع، حيث يمكن تقسيم سر، لا يُخزّن | + +معرّف جلسة يحتوي على أي شيء بخلاف الأحرف والأرقام و `.` و `_` و `-`، أو أطول من 128 حرف، لا يُستخدم أبداً كاسم ملف، لذا لا شيء يُسجل له. + +ملف جلسة موجود فقط مرة واحدة تم تسجيل مطالبة فيه. يحتفظ بالمطالبات ولا شيء آخر — لا حالة الأصل، لا علامة نسخة — ويُحذف مرة واحدة يكون صامت أطول من نافذة ستة ساعات، المرة التالية تكتب جلسة جديدة مطالبتها الأولى. + +تُقرأ مطالبة فقط لملف التعريف الوكيل نفسه ومعرّف الجلسة تم تسجيله تحتها. معرّفات الجلسة تأتي من الوكيل، لذا يمكن لملفين أن يستخدما نفسها؛ كي بـ profile يحتفظ بكلمات ملف تعريف واحد من أن تُحتفظ أبداً بكلمات ملف تعريف آخر. الملفات قبل هذا التخطيط (`sessions/.json`) لا يمكنها القول أي ملف تعريف كتبهم، لذا لا تُقرأ أبداً، وتنتهي بنافذة ستة ساعات. + +لا شيء يُسجل إلا إذا تم تكوين نقطة نهاية Jev. تحت Failproof AI Cloud Jev mode، لا شيء يُسجل لملف وكيل لا فحص Jev السحابية موجه ولا فحص حزم مثبت يراجع. + +### جذر المشروع + +"داخل المشروع" — ما `read-outside-workspace` والفحوصات المسارية الأخرى الحكم عليها — تعني داخل المشروع الجلسة كانت فيه في **استدعاء أول مراجع**. يُثبّت الجذر ثم و `cd` لاحق أبداً لا يحركها؛ `cd` لا يزال يغير كيفية حل المسار النسبي. السماح به باتباع `cd` سيسمح `cd ~/.ssh` في استدعاء واحد بجعل `~/.ssh` المشروع للاستدعاء التالي. + +الدبوس هو `~/.failproofai/state/semantic/roots/.json`، الاحتفاظ بـ `{root, at}`: ملف `0600`، دليل `0700`، ونفس قاعدة معرّف الجلسة كما هو أعلاه. الملفات أقدم من 7 أيام يتم حذفها عندما تثبّت جلسة جديدة جذرها. دليل `roots` يمكن لمستخدمين آخرين كتابة إليه يتم تجاهله، ويتم استخدام جذر الدليل المباشر. لإعادة تثبيت جلسة، احذف ملفها. + +## الحدود المعروفة + +- **مطالبة فقط بقدر استدعاء الخطاف الموثوق.** كل شيء هنا يقرأ الحمل الذي كتبه الحزام على stdin الخطاف. وكيل يستطيع تشغيل الأوامر يستطيع تشغيل الحزام بدون رأس (`claude -p` والسبعة الآخرين المدرجون أعلاه) أو تشغيل ثنائي الخطاف الخاص بـ Failproof AI نفسه مع حمل كتبه، وتسجيل مطالبة لا أحد كتبها. هذا التبادل المقبول موضح في أعلى هذه الصفحة: يمسح السياسات القابلة للمراجعة فقط، لا واحد صعب — لكن اثني عشر من خمسة عشر القابلة للمراجعة المدمجة هي رفوض، لذا يمكن لمطالبة مزيفة تحويل كتلة حقيقية إلى سماح على تلك الاثني عشر. +- **كشف الوكيل الفرعي هو Claude-shaped.** حمل يحمل `agent_id` لا يُسجل أبداً، على أي حزام. هذا هو الحقل Claude Code و Factory Droid و Devin سيستخدمونه. يطلق Codex حدث المطالبة داخل خيوط الوكيل الفرعي، Copilot يشغل أصدقاء العملية، Goose لديها أداة `delegate` و OpenClaw تشغل شخصيات — لا أحد منهم يعلّم الحمل بطريقة يعترف بها هذا، لذا مطالبة الوكيل الفرعي على تلك الحزم تُسجل كجلسة الجلسة. `openclaw.agentId` من OpenClaw **ليست** تلك العلامة: تعيين الملحق المشحون على كل تشغيل، صاحب ماذا. +- **الموجّهات التي لا تحمل علامة.** `schedule_wakeup` و `loop_wakeup` من Claude Code، و `cron` و `heartbeat` triggers من OpenClaw، يتم رفضهم لأن تلك الحزم تقول ذلك في الحمل. موجّه Goose الخاص (`goose schedule add`) و `codex exec` من Codex لا تقول لا شيء، لذا تشغيل يبدأونها يُسجل مثل أي آخر. +- **آخر رسالة وكيل يمكن أن تكون رسالة اختار الوكيل.** النسخة غير موثقة، لذا وكيل يكتب نسختها الخاصة يمكنه تقرير ماذا يقول "آخر رسالة". يُعلّم مكتوب من الوكيل وأبداً يمسح لوحده — لكن لاحظ أن مسار v1 من `decide.ts` يسمح له رضا الفحص الحتمي "هل اسم المستخدم هذا الهدف"، لذا وكيل يتحكم بنسخته يمكنه توفير اسم هدف تجاوز يحتاج. +- **مطالبة تفتح مع أحد عناوين الآلة للامتداد يتم حذفها كاملة.** ابدأ مطالبة مع `# Selected text:`، `# Diff comments:`، `# Chrome tabs:` أو عنوان قسم آخر من المجموعة الأولى أعلاه، وأبداً كتبت عنوان `## My request:`، ولا شيء يُسجل لهذا الدور — لذا لا شيء يُمسح له. هذا مقصود: تلك الأقسام تحمل نص شخص آخر يتحكم (الكود حددته، تعليق مراجع diff، عنوان صفحة)، والاحتفاظ بهذا كلماتك هو الفشل الأسوأ. العناوين المطور يكتبه بشكل معقول في المجموعة الثانية وأبداً يحذفون مطالبة على حسابهم. +- **OpenCode يسجل لا شيء في الممارسة.** حدثه `message.updated` لا يحمل نص في OpenCode الحالي، وينطلق أيضاً للجلسات الفرعية التي تنشئ أداة المهمة، التي "user" الرسالة كتبها الوكيل الأب. +- **`CODEX_HOME` لا يحترم** من قبل اكتشاف rollout في `lib/codex-sessions.ts`. هذا يؤثر فقط على حيث يتم البحث عن لقطة رسالة وكيل، أبداً ما إذا تم تسجيل مطالبة. \ No newline at end of file diff --git a/docs/ar/reference/jev-providers.mdx b/docs/ar/reference/jev-providers.mdx new file mode 100644 index 000000000..a39be0cba --- /dev/null +++ b/docs/ar/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "مزودو Jev وإعداد المفتاح الخاص" +description: "نقاط نهاية المزود ومعرّفات النماذج والإعدادات وسلوك الفشل لمراجعة سياسة Jev المباشرة بمفتاحك الخاص." +icon: "key-round" +--- + +هذا هو مرجع المزود والإعداد لـ [سياسات Jev](/ar/policies/jev) بمفتاحك الخاص. سياسات Regex تطابق السلاسل النصية. لا يمكنها التمييز بين `rm -rf build/` الذي طلبته من `rm -rf ~` الذي انزلق إلى الخطة، لذا فإنها تحظر الكثير في مكان واحد والقليل جداً في مكان آخر. **Jev**، مصنف TypeSafe، يقرأ النداء مقابل ما طلبته فعلياً ويجيب على مجموعة من أسئلة نعم/لا عنها في طلب واحد سريع. + +مع نقطة نهاية Jev الخاصة بك والمفتاح المكوّن، يسأل Failproof AI عن Jev في كل استدعاء أداة **إلى جانب** سياسات regex، وليس بدلاً منها أبداً: + +- الحجب من سياسة **صلبة** نهائي. لا يمكن لـ Jev إلغاؤه. كل سياسة صلبة ما لم تُحدد صراحة كقابلة للمراجعة وتسمّي فحوصات Jev التي تغطيها، لذا فإن سياسة مخصصة أو pack أو Cloud التي لا تقول شيئاً صلبة، وحارس الحماية الذاتية الذي يعمل دائماً صلب دائماً. +- قد يتم إلغاء حجب سياسة **قابلة للمراجعة**، لكن فقط عندما تم سؤال Jev عن المخاوف الدقيقة التي تغطيها السياسة وأجاب "لا شيء هنا" أو "المستخدم طلب هذا". فحص يجد المخاوف حقيقية، عندما لم يطلب المستخدم النداء، يحتفظ بالحجب - حتى عندما يكون حكمه الخاص تحذيراً فقط، لأنه قبل استدعاء أداة التحذير لا يوقف الوكيل. وعندما يكون هذا الفحص واحداً يمكنه الحجب (تعريض الأسرار، تسرب بيانات الاعتماد، الحذف المدمّر، ...)، لا شيء يتم إلغاؤه في هذا النداء. +- قد يصبح الحجب **تحذيراً** عندما يكون النداء خطوة من المهمة التي أعطيتها ولا يصل أبعد من ذلك: يخفف Jev حجبه الخاص إلى تحذير، وهذا التحذير - الذي يسمّي ما هو فعلاً خطأ مع النداء - يحل محل حجب السياسة. +- يمكن لـ Jev أيضاً تحذير أو حجب بمفرده، لضرر لا تصفه أي regex. +- إذا لم يستطع Jev الإجابة (انتهاء المهلة الزمنية، حد معدل، خطأ في الخادم، لا توجد أرصدة، إصدار نموذج غير متوقع)، يحصل هذا النداء على نتيجة regex، تماماً كما بدون Jev. +- Jev لا يجعل النداء أكثر تساهلاً من سياساتك وحدها ما لم يقرأ النداء كاملاً وتم سؤاله عن المخاوف الدقيقة. أي شيء أقل من ذلك - نداء كبير جداً للإرسال كاملاً، حقن مريب - يسحب التصريحات ويحتفظ بكل حجب. + + +بدون إعداد Jev لا يتغير شيء: تعمل الخطافات على سياسات regex تماماً كما كانت دائماً. الإعداد هو كل الاختيار. + + + +في FailproofAI Cloud؟ لا تحتاج إلى مفتاح خاص بك: آلة متصلة بمفتاح يحمل `jev:evaluate` يمكنها استخدام Jev على خطة مؤسستك. انظر [Jev عبر FailproofAI Cloud](/ar/reference/jev-cloud). + + +## قبل أن تبدأ + +ثبّت **failproofai 1.0.8-beta.0 أو إصدار أحدث** وأرفق خطاطيفه إلى [harness مدعوم](/ar/reference/harnesses) على الآلة التي يعمل عليها وكيلك. اتبع [الدليل السريع](/ar/start/quickstart) إذا كانت هذه آلة جديدة، أو [قم بإعداد الفرض المحلي](/ar/start/setup#enforce-locally) إذا كنت لا تستخدم Cloud. تحقق من CLI المثبت باستخدام `failproofai --version`. + +احصل على مفتاح API من مزود أدناه، أو جهّز نقطة نهاية متوافقة ومفتاحها. يراجع Jev استدعاءات الأدوات المسمّاة في بوابة `PreToolUse` أو `PermissionRequest`. يمكنه إصدار حكمه الخاص، لكن إلغاء حجب السياسة الموجود يتطلب أيضاً سياسة مثبتة محددة [قابلة للمراجعة](/ar/policies/authority). تظل عمليات الحجب من السياسات الصلبة نهائية. + +## اختر مزوداً + +Jev متاح من خلال خمس طرق. أحضر مفتاحاً لأي واحد منها. + +| المزود | `--provider` | نقطة النهاية | النموذج الافتراضي | ملاحظات | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | تثبيت الإصدار الدقيق. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | يتم توجيه الطلبات إلى نقاط نهاية بدون احتفاظ بالبيانات فقط، بدون الرجوع إلى مزود آخر. يبلّغ عن إصدار مؤرخ مثل `typesafe/jev-1.13-20260917`. | +| بوابة Vercel AI | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | يسمّي Jev فقط بـ alias، لذا يتم تسجيل نسخة الإجابة كغير مُتحقق منها. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | يحتاج إلى `--account-id`. تم قياس حوالي ستة استدعاءات في الثانية لكل مفتاح قبل HTTP 429. | +| نقطة نهايتك الخاصة | `custom` | `/systemone` | `jev-1.13.0` | أي نقطة نهاية تقبل جسم طلب TypeSafe وتبلّغ عن النموذج الذي أجاب. `https` فقط؛ `http` عادي إلى مضيف loopback (`localhost`، `127.0.0.1`، `::1`) مقبول للاختبار المحلي. | + + +مع ميزة Vercel الخاصة بـ bring-your-own-key، يتم إعادة محاولة الطلب الفاشل بدون صوت باستخدام بيانات اعتماد Vercel. إذا كنت تحتاج إلى دفع كل استدعاء إلى حسابك TypeSafe الخاص فقط ورؤيته، استخدم TypeSafe مباشرة. + + +## قم بإعداده + +أمر واحد، نقطة النهاية والمفتاح. ابدأ في وضع `observe` حتى تتمكن من فحص أحكام Jev بينما تقرر السياسات الموجودة الاستدعاءات: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### عنوان URL يختار المزود + +لا يتعين عليك تسمية المزود: **مضيف** العنوان هو الذي يكون. + +| مضيف العنوان | المزود | يحتاج أيضاً | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| أي مضيف آخر | `custom` | — عنوان URL الذي أعطيته هو عنوان URL الأساسي | + +ثلاثة أشياء تأتي من ذلك: + +- **عنوان URL من API المزود الخاص لا يكتب override.** `--url https://api.typesafe.ai/v1` ينتج بالضبط الإعداد الذي سيكون لديك من `--provider typesafe`. أعط مساراً مختلفاً أو مضيفاً على مزود معروف ويتم تخزينه كعنوان URL أساسي، كما ستخزنه `--base-url`. +- **`--provider` لا يزال يتجاوز الاستدلال**، وهذه هي الطريقة التي تصل بها إلى proxy يتحدث API المزود من مضيف خاص بك: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **`--provider` يتناقض مع المضيف مرفوض**، وليس مخمناً. `--provider openrouter --url https://api.typesafe.ai/v1` لا يكتب شيئاً ويقول السبب: الاثنان يختلفان حول حيث سيتم إرسال مفتاحك. يتم رفض نفس الزوج من `jev setup --base-url` ومن لوحة تحكم Jev الإعدادات. (`--provider custom` ليس تناقضاً — يعني "تعامل مع عنوان URL هذا كما هو" — باستثناء مضيف Cloudflare، الذي لا يمكن لمسار مخصص الوصول إلى نقطة النهاية لكل حساب.) + +يتم التحقق من `--url` بالضبط كما يتم التحقق من `baseUrl` في ملف الإعداد، ورفضها بنفس الكلمات: `https`، أو `http` عادي إلى مضيف loopback (`localhost`، `127.0.0.1`، `::1`) في أي وضع. الخطر: لا شيء يصرّح خادم loopback، لذا بينما هو معطّل قد تأخذ عملية محلية أخرى منفذه وتجيب؛ استخدم `https` خارج الاختبار المحلي. + +### المفتاح + +أرسله بـ `--key-stdin`، أو شغّل الأمر في terminal بدونه والصق المفتاح في موجه مقنّع. على أي حال يذهب مباشرة إلى ملف الإعداد ولا يتم طباعته أبداً. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` يأخذ نفس الأعلام وهو الصيغة الطويلة لكل ذلك: `setup --provider ` حيث تفضل تسمية المزود بدلاً من عنوان URL. + +### `--token`، وما يكلفه + +`--token ` يضع المفتاح على سطر الأمر، وهي أسرع طريقة لإعداد آلة والصيغة الوحيدة التي تترك المفتاح في أي مكان غير ملف الإعداد: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +وسيط سطر الأوامر يكون في ملف السجل الخاص بقشرتك بعد ذلك، وبينما الأمر يعمل يكون في قائمة العمليات — قابل للقراءة من `/proc` بأي شيء يعمل مثلك. `setup` يقول ذلك في كل مرة يتم استخدام `--token`. فضّل `--key-stdin` على آلة تشاركها، في جلسة مسجلة، أو في أي مكان يتم فيه مزامنة ملف السجل؛ أدر مفتاحاً مررته بهذه الطريقة إذا أهمك الأمر. + + +`--token`، `--key-stdin` و`--key-from-env` متنافية بشكل متبادل: أعط واحداً. + +ثم أرسل طلب حي صغير واحد للتحقق من المفتاح وكذا نقطة النهاية وأي Jev أجاب: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` يخرج 1، ويقول ذلك في عنوانه، عندما تصل الإجابة بعد انتهاء المهلة الزمنية (كل خطاف سيعود إلى regex مثل `timeout`) أو يجيب على سؤال الفحص بشكل خاطئ. + +تقرأ الخطافات الإعداد في كل استدعاء أداة، لذا يتم تطبيقه من الآن فصاعداً. لا توجد حاجة لإعادة تشغيل، مع أو بدون daemon. + +## تحقق مما يفعله + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` يعرض المزود وكذا نقطة النهاية والنموذج والوضع وملف الإعداد وأذوناته، وليس أبداً المفتاح. أسفل ذلك يلخص النشاط الأخير: كم عدد استدعاءات Jev التي تم تقييمها، ومدى تكرار عودته إلى regex ولماذا، وزمن الكمون الخاص به، وأي سياسات قابلة للمراجعة تم إلغاء حجبها. + +## تحقق من نداء حقيقي + +ابدأ جلسة جديدة في الوكيل المُخطّف. اطلب منه استخدام أداة قراءة الملفات الخاصة به على `README.md` وإبلاغ العنوان. أكّد أن الجلسة تحتوي على استدعاء الأداة هذا، ثم شغّل `failproofai jev status` مرة أخرى: يجب أن تزداد عدد الاستدعاءات التي تم تقييمها مؤخراً. افتح **السياسات → النشاط** في [لوحة التحكم المحلية](/ar/reference/local-dashboard#review-policy-activity) لفحص حكم Jev والوضع للنداء. في وضع observe، تحدد نتيجة السياسة النداء. يظهر التصريح فقط إذا طابقت سياسة قابلة للمراجعة وقام Jev بإلغاء كل فحص مسمّى؛ قراءة عادية قد لا تكون لديها سياسة لإلغاء. + +## وضع Observe + +`enforce` هو الافتراضي. لمراقبة Jev بدون السماح له بتغيير أي قرار، قم بالتبديل إلى `observe`: لا يزال يتم سؤال Jev وتسجيل أحكامه، لكن نتيجة regex هي ما يتم فرضه. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` يحتفظ بالإعداد — نقطة النهاية والمفتاح — ويتوقف عن سؤال Jev: تعمل الخطافات على سياسات regex بالضبط كما بدون إعداد، و`failproofai jev status` يقول "off (switched off)". قم بالتبديل مرة أخرى مع `--mode observe` أو `--mode enforce`. + +إعادة تشغيل `setup` لنفس المزود تحتفظ بالمفتاح المُخزّن، لذا فإن تبديل الوضع علم واحد. يتطلب التبديل إلى مزود جديد البدء من جديد وطلب مفتاح ذلك المزود. كذلك يفعل `--base-url` الذي ينقل الطلبات إلى مضيف مختلف: يتم إرسال مفتاح مُخزّن فقط إلى المضيف الذي تم إعطاؤه له، أو إلى API المزود الخاص به. + +## ملف الإعداد + +كل شيء يعيش في ملف واحد، `~/.failproofai/jev.json`، مكتوب بـ `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| الحقل | المعنى | +| --- | --- | +| `provider` | `typesafe`، `openrouter`، `vercel`، `cloudflare` أو `custom` — أو `failproofai`، الذي يأتي مفتاحه من اتصال FailproofAI Cloud بدلاً من هذا الملف (انظر [Jev عبر FailproofAI Cloud](/ar/reference/jev-cloud)). | +| `apiKey` | يتم الإرسال كـ `Authorization: Bearer `. | +| `baseUrl` | مطلوب لـ `custom`؛ يحل محل API الأساسي للمزود وإلا. يجب أن يكون `https`. `http` عادي إلى `localhost` مقبول فقط مع `mode: observe`: لا شيء يصرّح خادم محلي، لذا بينما proxy الخاص بك معطّل أي عملية على الآلة، بما في ذلك الوكيل الذي يتم الحكم عليه، قد تجيب في مكانه. | +| `accountId` | Cloudflare فقط: 32 حرف hex صغير. | +| `model` | يحل محل معرّف النموذج الافتراضي للمزود. معرّف مرقم يجب أن يسمّي Jev 1.13. قيمة على شكل مفتاح API مرفوضة (وليست مكررة)، لذا فإن مفتاح مُلصق في `--model` لا يتم تخزينه أو إرساله أبداً كـ model. | +| `timeoutMs` | كم من الوقت ينتظر استدعاء الأداة Jev قبل استخدام نتيجة regex. 100–10000، الافتراضي 3000. | +| `mode` | `enforce` (افتراضي)، `observe`، أو `off` (احتفظ بالإعداد، بدون تشغيل Jev). | + +ثلاث قواعد تحميه: + +- **المالك فقط.** يتم الكتابة به بأذونات `0600`. نسخة يمكن لأي مستخدم أو مجموعة أخرى قراءتها أو كتابتها **مرفوضة**، والخطافات تعود إلى regex حتى تشغّل `chmod 600 ~/.failproofai/jev.json` أو `setup` مرة أخرى. يتم فحص الدليل أيضاً: `~/.failproofai` يجب ألا يكون **قابلاً للكتابة** من قبل أي شخص آخر، لأن من يستطيع الكتابة هناك يمكنه استبدال الملف مهما كانت أذوناته الخاصة. `setup` يأخذ تلك بتات الكتابة إذا وجدها. `failproofai jev status` يقول عندما يتم رفض إعداد ويعرض نقطة النهاية التي يسمّيها الملف: قد يكون شخص ما قد غيّره، لذا تحقق من أنه ملك لك قبل أن تقوم بـ `chmod`. إعادة تشغيل `setup` على ملف مثل هذا يحمل مفتاحه المُخزّن فقط إلى API المزود الخاص به؛ أي نقطة نهاية أخرى يسمّيها يحتاج إلى المفتاح مرة أخرى (`--key-stdin`)، أو `--base-url default` لإعادة توجيه الطلبات إلى المزود. +- **عام فقط.** لا يمكن لمستودع تشغيل Jev، أو توجيهه إلى نقطة نهاية أخرى أو اختيار نموذجه: يتم تجاهل `.failproofai/jev.json` داخل مشروع، وقراءة المزود والعنوان والنموذج ومعرّف الحساب من هذا الملف فقط — أبداً من البيئة، التي يمكن لإعدادات وكيل المستودع تعيينها. (`FAILPROOFAI_HOME` ليست طريقة حول ذلك: تنقل دليل failproofai بالكامل، سياساتك المدرجة أيضاً، بدلاً من إعادة توجيه Jev بمفرده.) +- **قد يأتي المفتاح وحده من البيئة.** إذا كان الملف ليس لديه `apiKey`، `FAILPROOFAI_JEV_API_KEY` يوفره لتلك الجلسة (`setup --key-from-env` يكتب ملف مثل هذا). لا يحل أبداً محل مفتاح يحتفظ به الملف، ولا يمكنه تشغيل Jev بدون الملف. حيث لا يتم تعيين المتغير، Jev ببساطة معطّل لتلك القشرة: `failproofai jev status` يقول ذلك، يخرج 0 ويترك الإعداد وحده (`status --json` يبلّغ `"status": "key-missing"` مع `"reason": "no-env-key"`). daemon `failproofaid` لا يرى بيئة قشرتك، لذا على آلة تم إعدادها باستخدام `failproofai config`، احتفظ بالمفتاح في الملف. + +## أي Jev يجيب + +تم معايرة عتبات قرار Failproof AI على Jev 1.13، لذا يتم استخدام إجابة فقط عندما تأتي من تلك الأسرة: `jev-1.13.x`، أو `typesafe/jev-1.13-` من OpenRouter. حيث يسمّي المزود Jev فقط بـ alias ولا يبلّغ عن نسخة (Vercel، و Cloudflare عندما لا يقول)، يتم استخدام الإجابة وتسجيلها كغير مُتحقق منها. نقطة نهاية `custom` يجب أن تبلّغ عن النموذج الذي أجاب؛ الاستثناء الوحيد هو معرّف `--model` غير مرقّم قمت بإعداده لها، الذي، عند إعادة صدوره، يتم تسجيله كغير مُتحقق منه بنفس الطريقة. إجابة تبلّغ عن أي إصدار آخر، أو إجابة `custom` لا تبلّغ بنسخة، لا يتم استخدامها: يعود ذلك النداء إلى regex مع السبب `model-mismatch`. + +## عندما لا يستطيع Jev الإجابة + +كل واحد من هذه يعود إلى نتيجة regex لذلك النداء ويتم تسجيله مع سببه، الذي يجمعه `failproofai jev status`: + +| السبب | السبب | +| --- | --- | +| `timeout` | لا إجابة ضمن `timeoutMs`. | +| `http-429` | المزود فرض حد معدل على المفتاح. | +| `rate-limited` | محدّد معدل Failproof AI الخاص أمسك النداء قبل إرساله: 5 طلبات في الثانية، في انفجارات تصل إلى 5، ولا شيء للحظة بعد إجابة المزود `429`. وليس المزود. | +| `http-500`، `http-502`، `http-503`، … | خطأ خادم عند المزود. يتم تسجيل الحالة الدقيقة. | +| `out-of-credits` | HTTP 402: حساب المزود ليس لديه أرصدة متبقية. | +| `provider-refused` | HTTP 402 من Cloudflare يقرأ "Model execution failed (Payment error)": رفض المزود تشغيل النموذج على هذا الطلب. عادة ليس الفواتير، لذا فإن إعادة الملء لن تحركها. | +| `http-401`، `http-403` | تم رفض المفتاح. | +| `http-404` | لا شيء يتم تقديمه في `/systemone`، لذا فإن عنوان URL الأساسي خاطئ — يتم إلحاق `/systemone` به، وكل مزود يقدمه في جذر الإصدار. `failproofai jev models` يعرض ما تقدمه نقطة النهاية. | +| `network` | لم تتمكن من الوصول إلى نقطة النهاية. | +| `http-301`، `http-302`، `http-307`، `http-308` | أجابت نقطة النهاية بإعادة توجيه. لا يتم اتباع عمليات إعادة التوجيه أبداً، لذا فإن الإجابة تأتي فقط من عنوان URL في إعدادك؛ قم بتعيين `--base-url` إلى عنوان URL النهائي. | +| `malformed` | أجابت نقطة النهاية، لكن ليس بإجابة Jev — جسم ليس JSON، أو واحد بدون إجابات فيه. | +| `cloudflare-error`، `cloudflare-incomplete` | ظرف Cloudflare أبلّغ عن فشل، أو وظيفة لم تنته. | +| `model-mismatch` | إصدار Jev بخلاف 1.13 أجاب، أو نقطة نهاية `custom` لم تقل أي نموذج أجاب. | +| `request-cut` | **ليس انقطاعاً.** أجاب Jev؛ تم عرضه فقط جزء من النداء، لذا إجابته لم تُلغِ شيئاً. انظر [عندما أجاب Jev، لكن ليس في النداء الكامل](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` يمكن أن يعرض عدد أسباب أندر أيضاً، مثل `upstream-error` (كانت الإجابة تحمل خطأ المزود الخاص) أو `config`، ويجمع أي سبب لا يمكنه تسميته كـ `other`. + +`request-cut` في هذا الجدول لأن `failproofai jev status` يجمعه مع الباقي، ولأنه أيضاً يترك كل حجب واقفاً. وهو السبب الوحيد هنا الذي لا يقول شيئاً عن المزود الخاص بك: وصل الطلب وأجاب Jev. بخلاف كل صف فوقه، تلك الإجابة لا تزال تُعتبر — ينطبق حجب Jev الخاص أو تحذيره على رأس نتيجة regex بدلاً من تجاهله. لذا فإن سلسلة منها تعني استدعاءات تصل إلى المُقيّم كبير جداً للإرسال كاملاً، وليس أن نقطة النهاية الخاصة بك غير صحية، وإعادة الملء أو تغيير العنوان لن تحركها. + +## عندما أجاب Jev، لكن ليس في النداء الكامل + +شيئان آخران يمكن أن يحدثا، ولا أحد منهما هو Jev فشل الإجابة. كلاهما عن مقدار النداء، أو من المحادثة، التي ناسبت طلباً واحداً. + +**جزء من النداء نفسه لم يناسب.** يتم إرسال استدعاء أداة داخل ميزانية ثابتة، واحد ضخم — `Write` كبير جداً، جسم MCP ضخم، أمر معشوش إلى الحد الأقصى — يتم إرساله مع ما ناسب. لا يزال Jev يجيب، وإجابته لا تزال تُعتبر: ينطبق حجبه الخاص أو تحذيره كالمعتاد. ما لا يمكنه فعله هو **إلغاء** أي شيء، لأن حكم قُضي على جزء من نداء ليس حكماً على النداء. لذا فإن كل حجب السياسة يقف، ويتم تسجيل النداء كحالة fallback مع السبب `request-cut`، الذي يجمعه `failproofai jev status` إلى جانب الأسباب أعلاه. القاعدة التي يعطيك إياها: جعل نداء أكبر يمكن أن يكلفه التصريحات، وليس أبداً شراء واحد. + +**رسالة لم تناسب.** موجه طويل ألصقته، آخر رسالة للوكيل، أو موجه هذا المُقيّم الخاص المخزن بالفعل مُحدود. **لا يتغير شيء**: يتم الحكم على النداء وإلغاء حجبه وتسجيله بالضبط كما أي آخر، وليس يتم عدّه كـ fallback. طول ما تكتبه لا يقرر أبداً حكماً، وقطع لا يمكنه تصنيع الموافقة: حيث وصل موجه بالفعل مُحدود، "لم تطلب هذا" توقف عن كونها خلاصة يمكن استخلاصها منها بالكامل، بدلاً من أن تصبح واحدة. + +الخط بين الاثنين هو من كتب النص. النداء هو للوكيل، وقاعدة سمحت بطول الخاص به بطرح الشدة ستكون قاعدة يمكن للوكيل استخدامها؛ موجهك ملك لك، ومعاملة طول الخاص به كإشارة فقط عاقب أبداً لصق المواصفات أو تتبع المكدس. + +## ما يترك الآلة + +لكل استدعاء أداة يقيّمه Jev، يذهب طلب واحد إلى المزود الخاص بك، حاملاً: + +- استدعاء الأداة نفسها، مع أسرار مثل مفاتيح API وتوكنات Bearer وتعيينات `KEY=` محجوبة؛ +- المحاثات الأخيرة التي أدرجتها، مع حذف النص الذي أضافته harness الوكيل؛ +- آخر رسالة من الوكيل قبل موجهك الأخير، محددة كمكتوبة من وكيل؛ +- الحقائق المحسوبة محلياً، مثل ما إذا كان المسار داخل المشروع — الذي كانت الجلسة فيه في أول استدعاء مُراجع، [مثبت للجلسة](/ar/reference/jev-intent#the-project-root) — والفرع الحالي من git. + +يذهب فقط إلى نقطة النهاية في إعدادك، تحت المفتاح الخاص بك. + +## أطفئه + +```bash +failproofai jev remove +``` + +هذا يحذف `~/.failproofai/jev.json`. من استدعاء الأداة التالي، تعمل الخطافات على سياسات regex بالضبط كما سابقاً. المتاجر في الجلسة تحت `~/.failproofai/state/semantic/` (المحاثات المسجلة في `sessions/`، جذور المشروع في `roots/`) يتم تركها في مكانها والعمر. لإيقاف سؤال Jev لكن الاحتفاظ بالإعداد، استخدم `failproofai jev setup --mode off` بدلاً من ذلك. + +## مرجع الأمر + +| الأمر | النتيجة | +| --- | --- | +| `failproofai jev --url --key-stdin` | إعداده في أمر واحد؛ يأتي المزود من مضيف عنوان URL | +| `failproofai jev --url --token ` | نفس الشيء، مع المفتاح على سطر الأوامر — يرى سجل وقائمة العمليات الخاصة بك | +| `failproofai jev setup --provider --key-stdin` | اكتب الإعداد من مفتاح مُرسل على stdin | +| `failproofai jev setup --provider ` | نفس الشيء، طالباً المفتاح في موجه مقنّع | +| `failproofai jev setup --key-from-env` | لا تُخزّن مفتاح؛ اقرأ `FAILPROOFAI_JEV_API_KEY` لكل جلسة | +| `failproofai jev setup --mode observe` | وضع التبديل (`enforce`، `observe` أو `off`)، الاحتفاظ بالمفتاح المُخزّن | +| `failproofai jev setup --model ` / `--base-url ` | تجاوز النموذج أو قاعدة API؛ `default` يمسح التجاوز | +| `failproofai jev setup --timeout-ms ` | غيّر الميزانية لكل نداء | +| `failproofai jev status [--json]` | الإعداد والأذونات والنشاط الأخير؛ ليس أبداً المفتاح | +| `failproofai jev test [--json]` | طلب حي واحد: الكمون والإصدار الذي أجاب | +| `failproofai jev models [--provider ] [--url ] [--json]` | معرّفات النموذج التي تبلّغ عنها `/models` لنقطة النهاية، محددة المُعدّة | +| `failproofai jev remove` | حذف الإعداد؛ Jev معطّل | \ No newline at end of file diff --git a/docs/ar/reference/jev.mdx b/docs/ar/reference/jev.mdx new file mode 100644 index 000000000..21760111a --- /dev/null +++ b/docs/ar/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "مرجع تكامل Jev" +description: "الإعدادات والموفرون والمفاتيح وبيانات الطلب وسلوك الفشل لـ Jev." +icon: "braces" +--- + +لـ Jev استخدامان في Failproof AI: + +| الاستخدام | متى يتم التشغيل | ما يتم إرجاعه | ابدأ من هنا | +| --- | --- | --- | --- | +| تقييم الجلسة | بعد انتهاء الجلسة | درجة لسؤال ذي إجابة محددة | [تقييمات Jev](/ar/evaluations/jev) | +| مراجعة سياسة استدعاء الأداة | قبل تشغيل استدعاء أداة محمي | قرار جنباً إلى جنب مع السياسات المثبتة | [سياسات Jev](/ar/policies/jev) | + +## صفحات المرجع + +| الموضوع | التفاصيل | +| --- | --- | +| [أسئلة التقييم](/ar/reference/jev-evaluations) | معايير منطقية وذات نقاط مرتبة، والنتائج، والحدود، والمحاضر بأثر رجعي. | +| [مقارنة الموفر وإعداد المفتاح الخاص](/ar/reference/jev-providers) | TypeSafe وOpenRouter وVercel وCloudflare والنقاط الطرفية المخصصة؛ استنتاج عنوان URL ومعرفات النموذج و`jev.json` والأوضاع وأكواد الرجوع. | +| [مسار FailproofAI Cloud](/ar/reference/jev-cloud) | أذونات مفتاح الجهاز وإعداد المراقبة التلقائية وحدود الاستخدام وحالة الاتصال ومعالجة البيانات. | + +يتم سرد أوامر CLI المحلية في [مرجع Failproof AI CLI](/ar/reference/failproof-cli). يصف [مرجع لوحة المعلومات المحلية](/ar/reference/local-dashboard#set-up-jev) إعدادات Jev وعرض النشاط الخاص به. \ No newline at end of file diff --git a/docs/ar/reference/mcp.mdx b/docs/ar/reference/mcp.mdx new file mode 100644 index 000000000..5315df1b8 --- /dev/null +++ b/docs/ar/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP server" +description: "قم بربط Claude أو Cursor أو Codex أو أي عميل MCP آخر بـ Failproof AI Cloud، باستخدام أذوناتك الخاصة." +icon: "plug" +--- + +قم بربط أداة ذكاء اصطناعي بـ Failproof AI Cloud والعمل ببيانات عملائك منها. يمكن لأداتك الاستعلام عن الجلسات والأحداث، وتشغيل SQL للقراءة فقط، وقراءة لوحات التحكم والتنبيهات والمشاكل والتدقيقات والسياسات، وإذا كنت تمتلك الإذن، إجراء تغييرات مثل إنشاء تنبيه أو نشر سياسة. + +يتم تشغيل كل استدعاء بـ **أذوناتك الخاصة**، في **منظمة واحدة** تختارها عند الاتصال. + +هناك عنوان واحد للجميع، مستضاف أو ذاتي الاستضافة: + +```text +https://gateway.befailproof.ai/mcp +``` + +## قم بربط عميل + +أضف العنوان إلى عميلك. في المرة الأولى التي يتم فيها استخدام أداة، سيتم فتح متصفحك. اختر مكان وجود Failproof AI Cloud الخاص بك وسجل الدخول واختر منظمة واحدة ثم حدد **السماح**. يؤدي **الإلغاء** إلى عدم ربط أي شيء. + +تذكر الصفحة اسم التطبيق والمكان الذي يعود إليه. يتم وضع علامة على التطبيق الذي لا يتم تحديده من خلال عنوان الويب الخاص به بـ **تطبيق غير موثق**، لذا استمر فقط إذا بدأت هذا للتو من عميلك الخاص. + + + + في claude.ai أو Claude Desktop، انتقل إلى **الإعدادات → الموصلات → إضافة موصل مخصص**. سمِّه `Failproof AI`، وأدخل العنوان، وحدد **إضافة**، ثم **الاتصال**. + + في خطط Team و Enterprise، يقوم المالك بإضافة الموصل للمنظمة أولاً. ثم يقوم كل شخص بربط حسابه الخاص. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + ثم قم بتشغيل `/mcp` داخل Claude Code، واختر `failproofai`، واختر **المصادقة**. + + + أضف هذا إلى `~/.cursor/mcp.json`، أو إلى `.cursor/mcp.json` في مشروعك: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + يعرض Cursor **يتطلب تسجيل دخول** بجانب الخادم. حدده لتسجيل الدخول. + + + أضف هذا إلى `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + ثم قم بتشغيل `codex mcp login failproofai`. + + + أي عميل يدعم خوادم MCP البعيدة عبر HTTP قابل للبث مع OAuth يعمل. أعطه العنوان أعلاه. لا يوجد معرف عميل أو سر لتكوينه. + + + +## منظمة واحدة لكل اتصال + +يعمل الاتصال فقط في المنظمة التي اخترتها. لاستخدام منظمتين، أضف الخادم مرتين تحت أسماء مختلفة، مثل `failproofai-acme` و `failproofai-sandbox`، وقم بربط كل منها بمنظمتها الخاصة. + +لا تقبل المنظمات التجريبية الاتصالات. اختر منظمتك الخاصة بدلاً من ذلك. + +## الأذونات + +يمكن لاتصال أن يفعل ما يمكنك فعله في المنظمة، ضمن المجموعة أدناه. إنه يتبع أذوناتك الحالية: إذا منحك المسؤول المزيد، ستحصل الأداة عليه، وإذا أخذها، ستفقدها الأداة عند استدعاءها التالي. + +| الإذن | يسمح للأداة بـ | +| --- | --- | +| `events:read` | إدراج الأحداث، قراءة نظرة عامة على الجلسة، إدراج الوكلاء والبيئات | +| `evaluations:read` | إدراج الجلسات، وقراءة وتلخيص نتائج التقييمات والمهام | +| `evaluations:trigger` | إنشاء التقييمات، ونشر إصدارات جديدة، وتشغيلها أو إيقافها، والملء المسبق، وإعادة تقييم الجلسة | +| `dashboards:read`, `dashboards:write` | قراءة لوحات التحكم، أو إنشاء وإعادة تسمية وإضافة استعلامات إليها | +| `queries:read`, `queries:write` | قراءة الاستعلامات المحفوظة، أو حفظها وتحريرها | +| `queries:run` | تشغيل استعلام SQL واحد للقراءة فقط وقراءة مخطط الاستعلام | +| `alerts:read`, `alerts:write` | قراءة التنبيهات، أو إنشاء وتحرير والتوقف والحذف واختبار | +| `issues:read` | قراءة المشاكل والاعتراف بها والتعليق عليها | +| `issues:create` | فتح مشكلة على تنبيه | +| `issues:close` | حل وإغلاق المشاكل | +| `audits:read`, `audits:write` | قراءة التدقيقات والتشغيلات والنتائج، أو إنشاء وتحرير التدقيقات وبدء التشغيل | +| `code_fixes:read` | معرفة كيفية إصلاح مشكلة والحصول على سياقها لوكيلك الخاص لإصلاحها | +| `code_fixes:write` | بدء إصلاح في Failproof AI Cloud، الذي يفتح طلب دمج على GitHub الخاص بك | +| `policies:read`, `policies:write` | قراءة السياسات والأجهزة والنشرات، أو نشر وزيادة وتراجع السياسات | + +لا تحتاج بعض الأدوات إلى إذن لأنها لا تقرأ بيانات المنظمة: بناء روابط الجلسة والحدث، والبحث في هذه الوثائق. + +لا يمكن لأداة ذكاء اصطناعي أن تلمس مفاتيح API أو المستخدمين أو الإعدادات أو إدارة المنظمة، كما لا يمكنها إرسال الأحداث. + +## الموافقة على التغييرات + +تطلب عمليات الكتابة منك أولاً ما إذا كان عميلك يمكنه عرض الموجه. ترى ما سيتغير وتحدد **الموافقة على هذا التغيير** للمتابعة. إذا رفضت أو لم ترد خلال حوالي 4 دقائق، فلن يتغير شيء. قد يتوقف بعض العملاء عن الانتظار بعد دقيقة واحدة، لذا يرجى الرد بسرعة. + + + العميل الذي لا يدعم الموجهات لا يُطلب منه، وتعمل عملية الكتابة بمجرد أن يقوم العميل باستدعاء. هناك، التأكيد الخاص بعميلك هو الوحيد، لذا أبقِ على أدوات الكتابة مُفعّلة. + + +## التطبيقات المتصلة والإلغاء + +**الإعدادات → التكاملات → MCP** يسرد تطبيقاتك المتصلة في المنظمة الحالية، مع أذوناتها وآخر استخدام. **الإلغاء** يقطع التطبيق فوراً. سيؤدي إزالة الخادم في عميلك إلى إلغاء الاتصال أيضاً. + +يمكنك الاتصال بحد أقصى 5 تطبيقات لكل منظمة. سيؤدي توصيل نفس التطبيق مرة أخرى إلى استبدال اتصاله السابق. + +## النشرات ذاتية الاستضافة + +اختر **Failproof AI Cloud ذاتي الاستضافة** عند الاتصال، وأدخل العنوان الذي تسجل الدخول فيه. يجب أن يكون نشرك قابلاً للوصول عبر HTTPS عام. + +تمر استدعاءات الأدوات ونتائجها عبر بوابة Failproof AI المستضافة في طريقها بين أداة الذكاء الاصطناعي والنشر الخاص بك. لا تخزنها البوابة. + +## ما يحدث لبيانات الخاص بك + +تذهب النتائج إلى أداة الذكاء الاصطناعي التي ربطتها، ويتعامل معها موفر الأداة بموجب شروطه الخاصة. لكل استدعاء أداة، يسجل Failproof AI اسم الأداة ونتيجتها ومدة استغراقها والمنظمة، ولا يسجل الحجج أو النتائج أبداً. انظر [سياسة الخصوصية](https://befailproof.ai/privacy/). + +## استكشاف الأخطاء + +| ما تراه | ما يجب فعله | +| --- | --- | +| "تم البدء في متصفح آخر" | أكمل تسجيل الدخول في المتصفح الذي فتحه العميل، مع السماح بملفات تعريف الارتباط، وابدأ من جديد من العميل | +| خطأ بعد **السماح** | يعمل الرابط مرة واحدة وينتهي بعد 10 دقائق، لذا ابدأ من جديد من العميل | +| أداة متوقعة مفقودة | أنت لا تمتلك إذنها في هذه المنظمة. اطلب من المسؤول. لا تحتاج إلى إعادة الاتصال بعد الحصول عليها | +| العميل يطلب منك تسجيل الدخول باستمرار | تم إلغاء الاتصال، أو غادرت المنظمة، أو ظل غير مستخدم لمدة 90 يوماً. قم بالاتصال مرة أخرى | +| "لديك 5 تطبيقات متصلة" | قم بإلغاء واحد ضمن **الإعدادات → التكاملات → MCP**، ثم قم بالاتصال مرة أخرى | + +لا تزال عالقاً؟ أرسل بريداً إلى [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/ar/reference/otel.mdx b/docs/ar/reference/otel.mdx new file mode 100644 index 000000000..77c098ec4 --- /dev/null +++ b/docs/ar/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "واجهة سطر الأوامر OpenTelemetry" +description: "اختر الانضمام إلى OTEL للوكلاء البرمجيين، وافحص التسليم، واستعد إعداداتك السابقة." +icon: "radio" +--- + +يقوم `failproofai otel` بتكوين إعداد OpenTelemetry الاختياري للإبلاغ إلى FailproofAI Cloud. أولاً اتصل بجهازك باستخدام `failproofai config` واطلب من مسؤول المؤسسة تفعيل **Settings → OpenTelemetry**. + +يطرح الإعداد التفاعلي أسئلة حول OpenTelemetry بعد حقل مفتاح Cloud واختيار الوكيل. الخطوة الاختيارية تفترض عدم الموافقة بشكل افتراضي. اختر نعم لاختيار وكلاء OTEL؛ سيتم تشغيل نفس كود التفعيل بعد كتابة الاتصال. الضغط على Esc قبل الإعداد لن يطبق أي تغييرات. الإعداد غير المراقب والمفتاح المرسل وضع المصدر المفتوح والاحتفاظ بالاتصال المحفوظ لا يختارونك للانضمام. + +## تفعيل وكيل + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +الوكلاء المدعومون هم `claude` و `codex` و `copilot` (VS Code). يتطلب إعداد Copilot ملف تنفيذي VS Code أو امتداد Copilot مثبتاً. مجرد ترك دليل الإعدادات ليس كافياً؛ يتخطى الإعداد Copilot عندما لا يتم العثور على أي منهما. + +`--local` يرسل إلى المعيد المحلي بدلاً من إرساله مباشرة إلى Cloud. يستخدم Copilot المعيد تلقائياً لأن إعداداته لا يمكنها تخزين رأس المصادقة. + +يستمع المعيد فقط على جهازك. يلتقط مصدر بيانات FailproofAI المكون التغيير خلال ثوان؛ لا تحتاج إلى إعادة تشغيله. إذا كانت تطبيقاً آخر يملك منفذ المعيد، فإن التقرير يبلغ عنه كمغلق والعفريت يستمر في التشغيل. + + +التقاط النص مفعل بشكل افتراضي. أضف `--no-content` لحذف تفاصيل الطلبات والأدوات. قد تعرض إصدارات الوكيل عناصر تحكم محتوى مختلفة؛ راجع ما يُصدره وكيلك قبل استخدامه مع بيانات حساسة. + + +يُصدر Codex سجلات المحادثة فقط، وليس تتبعات أو مقاييس وقت التشغيل الداخلية. `log_user_prompt = false` صريحة في تكوين Codex الخاص بك تبقى معطلة؛ التفعيل يطبع ملاحظة عند الحفاظ على هذا الاختيار. + +### اختر مسار إبلاغ واحد + +إذا كان الإبلاغ عن النص قيد التشغيل لوكيل ما، فإن الإعداد يسأل: + +> يُرسل failproofai بالفعل جلسات Claude Code إلى Cloud. إرسالها باستخدام OTEL بدلاً من ذلك؟ سيتوقف تحميل النسخة من Claude Code. + +الافتراضي هو لا. `--yes` يقبل المفتاح بدون موجه. الوكلاء الآخرون وتطبيق السياسة غير متأثرين. + +ينتظر إعداد Codex تأكيد العفريت للتغيير المجمِّع قبل كتابة إعدادات المُصدِّر. إذا انتهت مهلة التأكيد، يحذرك الإعداد للانتظار قبل بدء Codex. + +يحتفظ Config v2 بقائمة التتبع المتذكرة في `agents.selected` (وسجل الكشف في `agents.seen`). يبقى تفضيل النسخة لكل وكيل في `collector.agents..sessions`، وملكية OTEL في `otel.agents`، وإعدادات المعيد في `collector.otlp.enabled` / `collector.otlp.port`. تحافظ هذه المفاتيح المنفصلة على إمكانية قراءة تكوينات OTEL القديمة: يمكن للإعداد تغيير قائمة التتبع دون فقدان تفضيل النقل أو الحالة اللازمة لاستعادة إعدادات الوكيل الخاص بك. + +## افحص الإعداد + +```bash +failproofai otel status +``` + +يعرض الحالة كل وكيل، سواء تم إدارة إعداداته بواسطة FailproofAI، وجهته، مفتاح الامتصاص الخاص بالمؤسسة، حالة المعيد، وآخر نتيجة تحميل المعيد. + +`unknown` لمفتاح المؤسسة يعني أن الخادم لم يقدمه أو لم يتمكن من الوصول إليه. إنه ليس خطأ ولا يمنع التكوين في إصدار Cloud الأقدم. + +إذا كان Cloud لا يدعم OTEL حتى الآن، فإن المعيد يحتفظ بالتصديرات المرفوضة بدلاً من التخلص منها. إذا كان امتصاص المؤسسة معطلاً، فإن `enable` لا يكتب شيئاً ويخرج بخطأ؛ اطلب من مسؤول تشغيله أولاً. + +## اطبع التكوين لتطبيق + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +الإخراج عبارة عن كتلة متغيرات بيئة الصدفة لمُصدِّر OTLP/HTTP. يعيّن إخراج Cloud `OTEL_EXPORTER_OTLP_ENDPOINT` إلى قاعدة OTLP الخاصة بـ Cloud، `https:///otel`، والمُصدِّر يُلحق `/v1/`؛ قد تحتاج متغيرة لكل إشارة مثل `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` إلى `https:///otel/v1/logs` الكامل. يشير إخراج المحلي إلى المعيد، `http://127.0.0.1:`. يتضمن إخراج Cloud مفتاح API المكون؛ تعامل معه كسر. يحذف إخراج المحلي المفتاح. لاستخدام إخراج المحلي، فعّل أولاً وكيلاً محلياً حتى يعمل المعيد. + +## استعد الإعدادات السابقة + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +يستعيد التعطيل فقط الإعدادات التي كتبها FailproofAI، ويحافظ على التغييرات غير ذات الصلة، ويستعيد اختيار الإبلاغ عن النسخة السابق لكل وكيل. عندما يتم تعطيل آخر وكيل محلي مُدار، يتوقف المعيد عن قبول التصديرات. + +بالنسبة إلى Codex، يسجل التعطيل أيضاً `collector.agents.codex.sessions_resume_after` (ملي ثانية من الحقبة الزمنية). تُعتبر بايتات الطرح الموجودة مُسلَّمة حتى لا يتم تحميل الجلسات المُلتقطة باستخدام OTEL مرة أخرى؛ التحاقات لاحقة لا تزال تتدفق عبر الإبلاغ عن النسخة. + +يدعم كل أمر `--help`. اطلع على [OpenTelemetry في Cloud](/ar/agenteye/opentelemetry) للحصول على أمثلة التطبيقات والوكلاء البرمجيين. \ No newline at end of file diff --git a/docs/ar/reference/slack.mdx b/docs/ar/reference/slack.mdx new file mode 100644 index 000000000..4005f55fc --- /dev/null +++ b/docs/ar/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "تطبيق Slack" +description: "اطلب من مساعد Failproof من Slack، واحصل على الرسوم البيانية في الخيط، وأوافق على التغييرات بزر واحد." +icon: "slack" +--- + +اطلب من [مساعد Failproof](/ar/sessions/assistant) من Slack. اذكر التطبيق في قناة، أرسل له رسالة مباشرة، أو استخدم `/failproof `. تستخدم الإجابات **أذوناتك الخاصة** في Failproof AI، والرسوم البيانية تصل إلى الخيط، وأي شيء قد يغير شيئاً ما يطلب منك الموافقة عليه أولاً. + +هناك تطبيق رسمي واحد. يعمل بنفس الطريقة سواء كان Failproof AI Cloud الخاص بك مستضافاً أو ذاتي الاستضافة. + + + يتم إنشاء الإجابات بواسطة نماذج ذكاء اصطناعي وقد تكون غير دقيقة. تحقق من أي شيء مهم مقابل بيانات المصدر المرتبطة. + + +## ربط مساحة عمل + +تحتاج إلى إذن `settings:write` في Failproof AI وفي Slack، إلى أن تكون مسؤول مساحة عمل أو صاحب، أو الشخص الذي يضيف التطبيق. + + + + 1. انتقل إلى **Settings → Integrations** واختر **Add to Slack**. + 2. وافق على التطبيق في Slack. + 3. مرة أخرى في Failproof AI، أكد ربط مساحة العمل بمنظمتك. + + + 1. أضف التطبيق، ثم افتح علامة التبويب **Home** الخاصة به. + 2. اختر **Continue with FailproofAI Cloud**، أو **Use my own URL** وأدخل العنوان الذي تسجل الدخول إليه. + 3. اختر زر المتابعة، سجل الدخول، اختر المنظمة، وأكد. الرابط يعمل مرة واحدة وينتهي بعد 10 دقائق. + + + +مساحة عمل واحدة تتصل بمنظمة واحدة، ومنظمة واحدة بمساحة عمل واحدة. + +لا تملك حساباً؟ [أنشئ واحداً](https://app.befailproof.ai/login) أولاً، ثم قم بالربط. + +## من أنت في Slack + +في المرة الأولى التي تسأل فيها، يحدد التطبيق العضو الذي أنت عليه: + +- **تلقائياً، بالبريد الإلكتروني**، عندما تكون عضواً كاملاً في مساحة العمل المتصلة، وتم تأكيد بريدك الإلكتروني في Slack، وعضو واحد فقط من المنظمة يستخدم هذا البريد الإلكتروني. +- **وإلا**، ستحصل على زر **Link your account** خاص يفتح Failproof AI وربط مستخدم Slack الخاص بك بحسابك. + +## اطرح سؤالاً + +| المكان | الطريقة | +| --- | --- | +| قناة | اذكر التطبيق. رد في خيطه للمتابعة، بدون حاجة لذكر | +| رسالة مباشرة | أرسل رسالة للتطبيق | +| رسالة مباشرة جماعية يكون التطبيق فيها | اذكره، ثم رد في خيطه للمتابعة | +| قناة Slack Connect | اذكر التطبيق | +| أي محادثة يكون التطبيق فيها | `/failproof ` يبدأ خيطاً مع الإجابة | +| `/failproof help` | انظر ما يمكن للتطبيق أن يفعله | +| `/failproof status` | انظر المنظمة المتصلة ومن أنت مرتبط بها | +| `/failproof link` | انظر حساب Failproof AI الذي أنت مرتبط به | + +خيط واحد هو محادثة واحدة. يمكن للزملاء أن يذكروا التطبيق في نفس الخيط، وينجيب لكل منهم بأذوناتهم الخاصة. فقط الشخص الذي بدأ الخيط يستمر فيه دون ذكر. + +عندما تكون الإجابة بيانات، ينشر التطبيق رسماً بيانياً أو جدولاً مع رابط لفتحه في Failproof AI. + +## الموافقة على التغييرات + +كل تغيير يقوم به المساعد يظهر أولاً زري **Approve** و**Cancel**، و Slack يسأل مرة أخرى قبل **Approve**. فقط الشخص الذي سأل يمكنه الإجابة عليها، تنتهي الأزرار بعد 5 دقائق، والتغيير يتم بأذونات ذلك الشخص. + +من Slack، يمكن للمساعد تغيير الاستعلامات المحفوظة واللوحات، التقييمات، التنبيهات، التدقيقات، المشاكل، والسياسات، واقتراح إصلاحات الأكواد، كل منها إذا كنت تملك الإذن. لا يمكنه تغيير مفاتيح API أو المستخدمين أو الإعدادات. + +## معاينات الروابط + +رابط مشكلة Failproof AI أو جلسة أو تقييم الذي يتم لصقه في Slack يتكشف إلى بطاقات على Failproof AI Cloud المستضاف. تُظهر البطاقة فقط ما يمكن للشخص الذي أطلقها رؤيته. الروابط إلى عنوان ذاتي الاستضافة لا تتكشف، على الرغم من أن البطاقات في إجابات المساعد الخاصة به تظهر بعد كل شيء. + +## قنوات Slack Connect + +يمكن للأشخاص من مساحة عمل أخرى استخدام التطبيق إذا كانوا أعضاء في المنظمة، بعد ربط حسابهم. الإجابات مرئية للجميع في المحادثة، بما فيهم الأشخاص الذين ليسوا أعضاء في منظمتك، لذا اسأل حيث قد يرى الجميع الإجابة. + +يجيب التطبيق فقط عندما يكون لديك شخص واحد على الأقل من كل مساحة عمل أخرى في القناة مرتبط بالمنظمة. حتى ذلك الحين، يخبر الشخص الذي يسأل لماذا. + +## أذونات التطبيق التي يطلبها + +| إذن Slack | لماذا | +| --- | --- | +| `app_mentions:read` | معرفة متى يذكر شخص ما التطبيق | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | استقبال الرسائل المباشرة والردود في خيوط التطبيق. التطبيق يتجاهل الرسائل الأخرى، ولا يقرأ أبداً الرسائل السابقة في محادثة | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | التحقق من نوع المحادثة، حتى يعرف من يمكنه رؤية الإجابة | +| `chat:write` | نشر الإجابات وأزرار الموافقة | +| `commands` | توفير `/failproof` | +| `files:write` | نشر الرسوم البيانية | +| `links:read`, `links:write` | عرض معاينات روابط Failproof AI المرتفعة | +| `users:read`, `users:read.email` | ربطك بحساب Failproof AI الخاص بك، وعرض الأسماء | + +## قطع الاتصال + +انتقل إلى **Settings → Integrations** واختر **Disconnect**، استخدم **Disconnect** على علامة التبويب **Home** للتطبيق، أو أزل التطبيق من Slack. + +أي من هذه يحذف اتصال مساحة العمل، رمز البوت، الحسابات المرتبطة، وسجلات الخيط. محادثات Slack السابقة تبقى قابلة للقراءة في لوحة التحكم. يمكن للمنظمة بعد ذلك ربط أي مساحة عمل على الفور. + +## البيانات والخصوصية + +الأسئلة والإجابات يتم حفظها كمحادثات في لوحة التحكم الخاصة بمنظمتك، تحت اسم الشخص الذي بدأ الخيط. بيانات Slack لا تُستخدم أبداً لتدريب نماذج الذكاء الاصطناعي. انظر [سياسة الخصوصية](https://befailproof.ai/privacy/) لما يتلقاه التطبيق وكم من الوقت يتم الاحتفاظ به. + +## استكشاف الأخطاء + +| ما تراه | ما يجب فعله | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | مسؤول مساحة العمل يفتح علامة التبويب **Home** للتطبيق ويختار واحد | +| "This link expired or was already used." | اختر Cloud الخاص بك مرة أخرى على علامة التبويب **Home** للحصول على رابط جديد | +| "This org is already connected to a Slack workspace." | قطع الاتصال أولاً في الإعدادات | +| "That Slack workspace is connected to another org." | قطع الاتصال عنها من تلك المنظمة أولاً | +| "Link your account to use the assistant." | اختر الزر وأكد في Failproof AI | +| التطبيق لا يجيب في رسالة مباشرة جماعية | أضف التطبيق إلى Slack مرة أخرى لمنح أذوناته الجماعية. اتصالك محفوظ | +| "I won't post answers from your organization here" | شخص ما في مساحة العمل تلك وهو عضو في المنظمة يذكر التطبيق وربط حسابه | + +لا تزال عالقاً؟ أرسل بريداً إلى [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/ar/sessions/sentiment.mdx b/docs/ar/sessions/sentiment.mdx new file mode 100644 index 000000000..546fd056f --- /dev/null +++ b/docs/ar/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "تحليل المشاعر" +description: "ابحث عن الرسائل المحبطة والمربكة والتصحيحية باستخدام درجات مشاعر Jev." +icon: "smile" +--- + +يقيّم Jev كل رسالة يرسلها شخص لوكلائك من 0 إلى 100 لأربع مشاعر — **الغضب**، **الإحباط**، **السعادة** و**الالتباس** — وثلاث إشارات حول أداء الوكيل: + +- **التصحيح**: يقول الشخص أن الوكيل أخطأ في شيء ما. +- **تم الحل**: يؤكد الشخص أن الوكيل حل مشكلتهم. +- **الشك**: يطرح الشخص تساؤلات حول صحة إجابة الوكيل، أو ما إذا كان قد قام بالعمل بالفعل. + +استخدم تحليل المشاعر للعثور على المحادثات حيث يفقد الأشخاص صبرهم، والوكلاء الذين يستمرون في تصحيحهم، والردود التي تحقق نجاحاً. هذا تقييم Jev مدمج؛ لا تحتاج إلى إنشاء تقييم. لسؤالك ذي الإجابة الثابتة، [أنشئ تقييم Jev](/ar/evaluations/jev). + + + المشاعر معطّلة حتى يقوم مسؤول بتفعيلها للمنظمة. ينشئ Jev طلب تقييم واحد لكل رسالة ويتلقى تلك الرسالة مع رد الوكيل قبلها. يستخدم التقييم ميزانية نموذج منظمتك. + + +## تفعيلها + +1. انتقل إلى **Administration → Settings**. +2. ضمن **Human input sentiment**، اضغط على **on** واحفظ. + +يتم تقييم الرسائل من آخر يوم أولاً. بعد ذلك، يتم تقييم الرسائل الجديدة في غضون دقيقة أو دقيقتين من وصولها. + +## ابحث عن محادثة للمراجعة + +افتح **Observe → Sentiment**. قم بالتصفية حسب الوقت أو البيئة أو الوكيل أو معرّف الجلسة. يحسب الرأس الرسائل والجلسات، ويُظهر عدد الرسائل **المعلمة**، ويسمي الإشارة الأعلى. يتم تعليم الرسالة عندما تصل درجة الغضب أو الإحباط أو التصحيح أو الالتباس أو الشك إلى 35 من أصل 100. + +![لوحة معلومات المشاعر تظهر عدد الرسائل والجلسات والرسائل المعلمة ودرجات Jev بمرور الوقت.](/images/dashboard/sentiment-overview.png) + +استخدم **Score over time** لمقارنة الإشارات. اختر الدرجات المراد عرضها، ثم حدد نقطة لرؤية رسائل تلك الفترة الزمنية. يعرض جدول **By agent** حيث تتركز الإشارة. في **Messages**، رتّب حسب أقوى درجة سلبية أو اختر درجة واحدة. افتح رسالة في جلستها لقراءة المحادثة المحيطة قبل تحديد ما فشل. + +![قائمة رسائل المشاعر مرتبة حسب أقوى درجة سلبية، مع رابط لكل جلسة مصدر.](/images/dashboard/sentiment-messages.png) + +## الرسائل التي يتم تقييمها + +الرسائل التي كتبها شخص فقط: + +- الرسائل التي يسجلها وكلاؤك المخصصون كمدخلات بشرية باستخدام SDK. +- الطلبات المكتوبة في Claude Code و Codex و OpenCode و pi و Hermes و OpenClaw، عند إرسال نسخ جلسات العمل (الافتراضي). المهام المجدولة والتعليمات المحقونة وتسليم الوكلاء الفرعيين والنصوص الأخرى التي يكتبها وقت تشغيل الوكيل نفسه لا يتم تقييمها. وكذلك التشغيلات غير التفاعلية مثل `claude -p` و `codex exec` و `hermes -z`: كتبت البرنامج النصي تلك الطلبات، وليس شخص. + +يحكم التقييم على كلمات الشخص نفسه. التعليمات القصيرة والحادة مثل fix it لا تُحتسب كغضب، وطرح السؤال لا يُحتسب كالتباس. الطلب الجديد ليس تصحيحاً، والشكر بمفرده لا يُحتسب كحل. \ No newline at end of file diff --git a/docs/ar/start/use-jev.mdx b/docs/ar/start/use-jev.mdx new file mode 100644 index 000000000..933da6892 --- /dev/null +++ b/docs/ar/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "استخدام Jev" +description: "قم بإعداد تقييمات Jev للجلسات المكتملة أو سياسات Jev لمراجعة استدعاءات الأدوات المباشرة." +icon: "sparkles" +--- + +يساعد Jev في نقطتين أثناء تشغيل الوكيل: تقييم جلسة مكتملة مقابل إجابات معروفة، أو مراجعة استدعاء أداة في سياق ما طلبته من الوكيل. + + + + استخدم تقييم Jev عندما يمكن تقييم جلسة مكتملة مقابل سؤال يحتوي على عدة إجابات معروفة، مثل "هل طلب العميل استرجاع المبلغ؟ أجب بنعم أو لا." يساعدك في العثور على أنماط عبر الجلسات. + + ## إنشاء تقييم + + في لوحة التحكم السحابية، افتح **Analyze → eval authoring → new eval**. أدخل سؤالاً واحداً بإجابة ثابتة، اختر **draft**، وتحقق من أنه اختار درجة تصنيفية. [اختبره](/ar/evaluations/test) على جلسات حقيقية، ثم قم بنشره. + + ![نموذج صياغة التقييم المشترك حيث تصف سؤالاً، وتراجع المسودة، وتنشرها. تُظهر هذه الصورة مسودة كود؛ استخدم سؤالاً بإجابة ثابتة لـ Jev.](/images/dashboard/eval-authoring-draft.png) + + ## اقرأ الدرجات + + بعد اكتمال جلسة جديدة، افتح **Observe → Evaluations** أو استخدم Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + يقرأ CLI الدرجات؛ إنشاء تقييم Jev حالياً يستخدم لوحة التحكم. انظر [تقييمات Jev](/ar/evaluations/jev) لأنواع الأسئلة والأمثلة. + + + استخدم مراجعة سياسة Jev عندما تحتاج سياسة مطابقة السلاسل النصية إلى سياق طلبك لتقرير ما إذا كان استدعاء الأداة آمناً. ابدأ في وضع **observe** حتى تتمكن من فحص إجابات Jev بينما تستمر سياساتك المثبتة في تقرير كل استدعاء. + + تأتي فحوصات Jev من حزمة؛ Failproof AI لا تشحنها. حتى تقوم بتثبيتها، لا يسأل Jev عن أي شيء، حتى عند تكوينه: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## إعداد Cloud Jev + + في لوحة التحكم السحابية، افتح **Administration → Keys** وأنشئ مفتاحاً باستخدام إعداد **machine**. استخدمه مع `failproofai config` كما هو موضح في [دليل البدء السريع](/ar/start/quickstart). على جهاز بدون تكوين Jev موجود، هذا يُفعّل Cloud Jev في وضع المراقبة. تحقق من الاتصال باستخدام: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## استخدم نقطة النهاية الخاصة بك + + في لوحة التحكم المحلية، افتح **Settings → Jev**. اختر المزود، والصق رمزه، اختر **observe**، وشغّل Jev. + + ![لوحة إعدادات Jev المحلية مع مزود ومجال رمز ووضع مراقبة مختار.](/images/dashboard/jev-settings.png) + + أو قم بتكوين واختبار نقطة النهاية الخاصة بك من محطة طرفية: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + اطلب من وكيل مُعالج استخدام أداة قراءة الملفات الخاصة به على `README.md`. تأكد من ظهور استدعاء الأداة هذا في الجلسة، ثم افحصه ضمن **Policies → Activity** في لوحة التحكم المحلية. بمجرد أن تبدو نتائج المراقبة صحيحة، شرح [سياسات Jev](/ar/policies/jev) متى يتم فرضها. للحصول على تفاصيل المزود والتكوين، انظر [مرجع التكامل](/ar/reference/jev). + + \ No newline at end of file diff --git a/docs/de/admin/product-analytics.mdx b/docs/de/admin/product-analytics.mdx new file mode 100644 index 000000000..4090da248 --- /dev/null +++ b/docs/de/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Produktanalysen" +description: "Die Nutzungstelemetrie, die Failproof AI Cloud über sich selbst sendet, was niemals erfasst wird und wie man sie deaktiviert." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud sendet Nutzungstelemetrie **über die Software selbst** an ihre Maintainer. Die Daten Ihrer Agents sind darin niemals enthalten. Bei einer selbst gehosteten Installation ist die Telemetrie standardmäßig aktiviert und kann deaktiviert werden. + +## Was erfasst wird + +Jedes Ereignis enthält fünf Dimensionen und keinerlei personenbezogene Informationen: + +| Dimension | Beispiel | Bedeutung | +| --- | --- | --- | +| `product` | `agenteye` | Welches Produkt das Ereignis gesendet hat | +| `component` | `dashboard`, `server`, `cli` | Welcher Teil des Produkts das Ereignis gesendet hat | +| `app_version` | `0.0.1-beta.81` | Der verwendete Build | +| `deployment_kind` | `self_hosted` | Ob es sich um eine Kundeninstallation, unsere Demo, unser QA oder eine Entwicklermaschine handelt | +| `org_id` | eine UUID | In welcher Organisation die Aktion stattfand, als opaker Bezeichner | + +Darüber hinaus zeichnen Ereignisse auf, **was genutzt wurde, niemals was darin enthalten war**: welche Seite aufgerufen wurde (als Routenmuster wie `/:org/sessions/:id`, niemals die echte URL), wie viele Filter welcher Art angewendet wurden, ob eine Aktion erfolgreich war und wie lange sie gedauert hat. + +Die Slack-App erfasst Workspace-Verbindungen und -Trennungen, Kontoverknüpfungen, gestellte Fragen, gepostete Diagramme, Genehmigungsentscheidungen und Fehler nach einer festen Kategorie. Sie enthält niemals Slack-Workspace-, Benutzer- oder Kanal-IDs, E-Mail-Adressen, Fragen, Antworten, SQL oder Tokens. + +### Der Name Ihrer Organisation + +Neben der opaken `org_id` erfassen wir den Namen Ihrer Organisation, den URL-Slug und die Dashboard-Adresse einmalig – in einem Organisationsdatensatz und nicht in jedem einzelnen Ereignis. So können wir erkennen, welchem Konto ein Muster gehört, wenn wir die Nutzung analysieren oder ein von Ihnen gemeldetes Problem untersuchen. Dies ist die einzige identifizierende Information, die das Produkt über Sie sendet. + +### Ihre Nutzungsgesamtwerte + +Der Server meldet für jede Organisation die gemessenen Nutzungsgesamtwerte – dieselben Zahlen, die Sie auf der Nutzungsseite sehen. Es handelt sich ausschließlich um Zählwerte: Ereignisse, Sitzungen, Agents, Umgebungen, Evaluierungsdurchläufe, Scores, Audit-Durchläufe, gespeicherte Abfragen, Dashboards, Benachrichtigungen, Issues, API-Schlüssel und Mitglieder sowie die Datumsangaben des Messzeitraums. Sie enthalten keine Bezeichner, Namen oder Abfragetext und werden unabhängig davon übermittelt, ob jemand angemeldet ist. + +## Was niemals erfasst wird + +- **Keine Prompts, Modellantworten oder Ereignisinhalte** – weder als Text, Präfix noch als Hash +- **Keine Sitzungs-, Agent- oder Trace-Bezeichner** +- **Keine Evaluator-Score-Namen** +- **Keine Fehlermeldungen, Exception-Texte oder Response-Bodies** – nur ein Statuscode und eine Kategorie aus einer festen Liste +- **Keine Tool-Argumente, SQL oder Abfragetext** +- **Keine Details zu verbundenen Apps.** Das Verbinden oder Widerrufen eines MCP-Clients sendet höchstens eine Berechtigungsanzahl, niemals den App-Namen oder ein Token +- **Keine E-Mail-Adressen** +- **Keine Referrer-URLs oder Query-Strings** +- **Keine Bildschirmaufzeichnung, DOM-Erfassung oder Klick- und Cursornachverfolgung** + +## Deaktivierung bei einer selbst gehosteten Installation + +Setzen Sie `DO_NOT_TRACK=1` sowohl für das Dashboard als auch für den Server. Beide entscheiden unabhängig voneinander – wenn Sie es nur für einen setzen, sendet der andere weiterhin Telemetrie. Starten Sie den Server neu, damit die Änderung wirksam wird. + +Die README-Datei Ihres Releases beschreibt die weiteren Opt-out-Einstellungen und erklärt, wie Sie bestätigen können, dass die Telemetrie deaktiviert ist. + +## Ein einzelner Ping beim Opt-out + +Wenn Sie sich über eine Produkteinstellung statt über `DO_NOT_TRACK` abmelden, kann das Dashboard **einen anonymen Ping** senden, der dies erfasst – mit einer Wahrscheinlichkeit von 1 zu 1000 pro Prozessstart. Damit erfahren wir, wie viele Betreiber die Telemetrie deaktivieren. Der Ping enthält keine Bezeichner: keine Organisation, keinen Benutzer, keinen Hostnamen, keine URL oder IP-Adresse – nur Produkt, Komponente, Version, Deployment-Art und Grund. Ein Server im Opt-out-Zustand sendet nichts. + +Dieser Ping wird niemals gesendet, wenn Sie `DO_NOT_TRACK` verwenden. Das ist daher die empfohlene Einstellung, wenn Ihre Richtlinien jegliche ausgehende Telemetrie untersagen. + +## Ziel der Daten + +Die Daten werden über TLS auf Port 443 an PostHog (`us.i.posthog.com`) übermittelt. Es handelt sich um einen einzigen Hostnamen, sodass Sie ihn auch mit einer einzigen Egress-Regel blockieren können. + +Informationen zum allgemeinen Umgang mit personenbezogenen Daten finden Sie in unserer [Datenschutzrichtlinie](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/de/agenteye/opentelemetry.mdx b/docs/de/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..976afa59a --- /dev/null +++ b/docs/de/agenteye/opentelemetry.mdx @@ -0,0 +1,140 @@ +--- +title: "OpenTelemetry" +description: "Senden Sie Coding-Agent- und Anwendungstelemetrie mit OTLP an Failproof AI Cloud." +icon: "radio" +--- + +OpenTelemetry ermöglicht es Ihnen, Agent-Traces, Logs und Metriken über das standardisierte OTLP/HTTP-Protokoll an Failproof AI Cloud zu senden. Die Nutzung ist optional. Ihre bestehenden FailproofAI-Integrationen funktionieren weiterhin, ohne dass Sie diese Funktion aktivieren müssen. + +## Ingest für Ihre Organisation aktivieren + +Ein Organisationsadministrator öffnet **Einstellungen → OpenTelemetry** und aktiviert den Ingest. Verwenden Sie einen Cloud-API-Schlüssel mit der Berechtigung `events:add` – dieselbe Berechtigung, die auch für das Agent-Reporting verwendet wird. + +Wenn der Ingest deaktiviert ist, lehnt Cloud OTLP-Exporte ab, sodass `failproofai otel enable` keine Wirkung hat und Ihre Agents Sitzungen weiterhin auf dem üblichen Weg senden. Führen Sie `failproofai otel status` aus, um den Organisationsschalter zu prüfen, und bitten Sie einen Administrator, ihn zu aktivieren. + +## Einen Coding-Agent verbinden + +Verbinden Sie Ihren Rechner mit `failproofai config` und wählen Sie anschließend einen Agent: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +Der Setup-Befehl unterstützt Claude Code, Codex und Copilot und wählt je nach Situation Cloud oder ein lokal authentifiziertes Relay. Copilot verwendet automatisch das lokale Relay. Starten Sie den konfigurierten FailproofAI-Daemon, bevor Sie das Relay nutzen. + +Sendet FailproofAI bereits Sitzungstranskripte eines Agents, fragt das Setup, ob dieser Agent auf OTEL umgestellt werden soll. Die Standardantwort ist „Nein". Eine Bestätigung stoppt die Transkript-Uploads für diesen Agent; die Richtliniendurchsetzung und das Reporting anderer Agents bleiben davon unberührt. + +## Eine Anwendung verbinden + +Verwenden Sie die OpenTelemetry-Instrumentierung Ihrer Anwendung mit den folgenden Umgebungsvariablen: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +Der Endpunkt ist die OTLP-Basis von Cloud, `https://app.befailproof.ai/otel`; Ihr Exporter hängt `/v1/traces`, `/v1/logs` oder `/v1/metrics` selbst an. Signalspezifische Variablen wie `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` werden unverändert verwendet und benötigen daher den vollständigen Pfad, z. B. `https://app.befailproof.ai/otel/v1/logs`. + +Ersetzen Sie `` durch Ihren API-Schlüssel. Halten Sie das Secret aus dem Shell-Verlauf, Bildschirmaufzeichnungen und eingecheckten Konfigurationsdateien heraus. Auf einem konfigurierten Rechner gibt `failproofai otel env --service my-agent` den Block mit dem vorhandenen Schlüssel aus. Die Ausgabe enthält ein Credential. + +Cloud akzeptiert OTLP/HTTP-Exporte für Traces, Logs und Metriken – als Protobuf oder JSON, einschließlich gzip-komprimierter Anfragen. OTLP/gRPC wird nicht unterstützt. + +Metriken werden zur Exporter-Kompatibilität bestätigt, aber weder gespeichert noch angezeigt. Unterstützte Agent-Traces und Coding-Agent-Logs werden zu Sitzungen; Felder, die der Agent nicht exportiert, bleiben leer. + +## Prompt-Text erfassen + + +Die Texterfassung kann Prompts, Tool-Argumente und andere sensible Inhalte umfassen. `failproofai otel enable` aktiviert diese Funktion. Fügen Sie `--no-content` hinzu, um die Erfassung von Prompts und Tool-Details zu deaktivieren. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Für einen manuell konfigurierten Agent verwenden Sie dessen eigene Einstellungen zur Inhaltserfassung: + + + + Fügen Sie diese Variablen zur Umgebung Ihres Agents hinzu, zusammen mit dem oben beschriebenen Anwendungsblock: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Setzen Sie beide Inhaltsvariablen auf `0`, um die Erfassung von Prompts und Tool-Details zu vermeiden. + + + Verwenden Sie in der Benutzerkonfiguration von Codex die entsprechenden OTEL-Einstellungen: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Konversationsinhalte von Codex befinden sich in den Logs; interne Laufzeit-Traces und Metriken sollten deaktiviert bleiben. Codex verwendet den vollständigen Endpunkt, den Sie angeben. Setzen Sie `log_user_prompt` auf `false`, um Prompts auszuschließen; der Setup-Befehl behält ein explizites `false` bei. + + + Verwenden Sie die Telemetrieeinstellungen von Gemini mit dem lokalen Relay: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI wird von `failproofai otel enable` nicht unterstützt. Konfigurieren Sie es manuell mit einem eigenen authentifizierten Collector. Setzen Sie `logPrompts` auf `false`, um keine Prompts zu erfassen. + + + Verwenden Sie diese VS Code-Benutzereinstellungen: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Führen Sie `failproofai otel enable copilot` aus, um das authentifizierte Relay zu aktivieren. Setzen Sie `captureContent` auf `false`, um Inhalte auszulassen. + + + +## Setup prüfen oder rückgängig machen + +Das Relay behält Telemetriedaten bei vorübergehenden Netzwerk- und Serverausfällen und +wiederholt die Übertragung nach der Wiederherstellung. Eine dauerhafte `400`-Ablehnung – einschließlich eines Ereignisses, +das zu groß zum Speichern ist – erfordert eine Korrektur der Nutzlast. Das Relay behält den +abgelehnten Batch zur Überprüfung, anstatt ihn wiederholt zu senden. + +Nach einem `401`- oder `403`-Fehler ersetzen Sie das Credential durch einen Schlüssel mit der Berechtigung `events:add` +für dieselbe Organisation. Eine erneute Verbindung sendet wegen fehlender Credentials abgelehnte OTLP-Exporte nicht automatisch erneut; bitten Sie Ihren Operator, diese Batches wiederherzustellen. +Behalten Sie diese in ihrer ursprünglichen Organisation. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status unterscheidet zwischen von FailproofAI verwalteten Einstellungen und von Ihnen anderweitig konfigurierter Telemetrie. Disable stellt die vorherigen verwalteten Einstellungen und die frühere Transkript-Upload-Einstellung des Agents wieder her. + + + Befehlsoptionen, lokales Relay-Setup und Fehlerbehebung. + \ No newline at end of file diff --git a/docs/de/evaluations/jev.mdx b/docs/de/evaluations/jev.mdx new file mode 100644 index 000000000..f449a2393 --- /dev/null +++ b/docs/de/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev-Evaluierungen" +description: "Verwende Jev, um eine abgeschlossene Sitzung anhand einer Frage mit bekannten Antworten zu bewerten." +icon: "list-checks" +--- + +Eine Jev-Evaluierung liest eine **abgeschlossene Sitzung** und gibt einen Score von 0 bis 1 zurück. Verwende sie, wenn die Antwort im Voraus bekannt ist, zum Beispiel: „Hat der Kunde Dringlichkeit signalisiert?" oder „Wie frustriert war der Kunde?" Sie hilft dabei, Muster über mehrere Durchläufe hinweg zu erkennen; sie unterbricht keinen Tool-Aufruf. Für Entscheidungen, die **vor** dem Ausführen eines Tools getroffen werden, verwende [Jev policies](/de/policies/jev). + +## Eine Evaluierung im Dashboard erstellen + +1. Öffne **Analyze → eval authoring** und wähle **new eval**. +2. Beschreibe eine Frage und ihre möglichen Antworten. Zum Beispiel: „Hat der Agent eine Rückerstattung versprochen, bevor er die Rückerstattungsrichtlinie geprüft hat? Antworte mit Ja oder Nein." Wähle **draft** und überprüfe, ob das Ergebnis ein Classifier-Score ist. +3. [Teste sie](/de/evaluations/test) anhand aktueller Sitzungen, und [deploye sie](/de/evaluations/deploy) anschließend. Neu abgeschlossene Sitzungen werden automatisch bewertet; nutze [Backfill](/de/evaluations/deploy#score-sessions-you-already-have), wenn du auch historische Daten benötigst. + +![Das gemeinsame Eval-Authoring-Formular, in dem du eine Frage mit festen Antworten beschreibst, den Entwurf überprüfst und nach dem Testen deployest. Das gezeigte Beispiel ist eine Code-Evaluierung; eine Jev-Frage verwendet denselben Authoring-Ablauf.](/images/dashboard/eval-authoring-draft.png) + +Der Assistent kann zwischen Code, Jev-Klassifizierung und einem [Judge](/de/evaluations/judge) wählen. Überprüfe die Wahl, bevor du deployest. Jev liefert einen Score ohne erläuternde Begründung; wähle einen Judge, wenn du eine Erklärung benötigst. Siehe die [Jev-Evaluierungsreferenz](/de/reference/jev-evaluations) für Fragetypen und Score-Limits. + +## Die Scores auslesen + +Öffne **Observe → Evaluations**, um das Ergebnis nach Agent und Zeitraum darzustellen. Über ein Terminal kann die Cloud CLI dieselben Ergebnisse auslesen: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Die Cloud CLI liest Ergebnisse aus; Authoring und Deployment erfolgen im Dashboard. Siehe die [Cloud-CLI-Referenz](/de/reference/cloud-cli#evaluations) für verfügbare Filter. \ No newline at end of file diff --git a/docs/de/evaluations/judge.mdx b/docs/de/evaluations/judge.mdx new file mode 100644 index 000000000..d0a73aadf --- /dev/null +++ b/docs/de/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLM-Richter" +description: "Bewerte Sitzungen anhand von Dingen, die Code nicht messen kann – Korrektheit, Ton, ob der Agent eine Richtlinie befolgt hat – indem du beschreibst, wie gut aussieht, und ein Modell die Konversation lesen lässt." +icon: "scale" +--- + +Eine gehostete Python-Auswertung kann zählen und vergleichen: wie viele Tool-Aufrufe, wie viele Fehler, wie lange eine Sitzung gedauert hat. Sie kann dir nicht sagen, ob eine Antwort *korrekt* war, ob eine Antwort unhöflich war oder ob der Agent vor dem Handeln eine Richtlinie geprüft hat. + +Ein **LLM-Richter** kann das. Du beschreibst in einfacher Sprache, wie gut aussieht, und ein Modell liest die Sitzung durch und gibt einen Wert von 0 bis 1 mit Begründung zurück. + + +Ein Richter kostet einen Modellaufruf für jede Sitzung, auf der er ausgeführt wird, während eine Code-Auswertung nichts kostet. Verwende einen Richter nur für Fragen, bei denen die Konversation *verstanden* werden muss – und gib ihm eine Bedingung, damit er nur auf den Sitzungen ausgeführt wird, um die es bei der Frage tatsächlich geht. + + +## Welche Variante brauche ich? + +| Frage | Verwende | +| --- | --- | +| Hat er dasselbe Tool zweimal aufgerufen? | Code | +| Wie viele Fehler gab es? | Code | +| War die Sitzung kürzer als 30 Sekunden? | Code | +| Hat der Kunde Dringlichkeit geäußert? | [Klassifikator](/de/evaluations/jev) | +| Wie frustriert war der Kunde? | [Klassifikator](/de/evaluations/jev) | +| War die Antwort tatsächlich korrekt? | **Richter** | +| War die Antwort unhöflich oder abweisend? | **Richter** | +| Hat er die Rückerstattungsrichtlinie geprüft, bevor er eine Rückerstattung versprochen hat? | **Richter** | + +Die Faustregel lautet: **Zählbares → Code, Antworten, die du im Voraus auflisten kannst → [Klassifikator](/de/evaluations/jev), braucht eine Erklärung → Richter.** Ein Richter ist derjenige, der in Prosa beschreibt, was er gesehen hat; greife darauf zurück, wenn die Zahl jemanden dazu veranlasst zu fragen: „Warum?" + +Du musst dich nicht im Voraus entscheiden. Beschreibe, was gemessen werden soll, und der Assistent wählt aus, teilt dir dann mit, was er gewählt hat und warum. Du kannst es ändern. + +## Eine Auswertung erstellen + +1. Gehe zu **Analyze → eval authoring** und wähle **new eval**. +2. Beschreibe, was beurteilt werden soll, und wähle **draft**. +3. Überprüfe die **Kriterien**, den **Schwellenwert** und die **Bedingung**, dann veröffentliche. + +### Kriterien + +Ein oder zwei Sätze, formuliert als Anforderung und nicht als Frage: + +> Der Assistent darf keine Rückerstattung versprechen oder genehmigen, ohne zuvor die Rückerstattungsrichtlinie zu prüfen. + +Sei konkret, was dazu führen würde, dass die Auswertung *fehlschlägt*. „War die Antwort gut?" gibt dir eine Zahl, die nichts bedeutet; der Satz oben gibt dir eine, auf die du reagieren kannst. + +### Schwellenwert + +Der Wert, ab dem eine Sitzung als bestanden gilt. `0.7` ist ein vernünftiger Ausgangspunkt. Der vollständige Wert von 0 bis 1 wird immer gespeichert, daher entscheidet der Schwellenwert nur über Bestanden/Nicht bestanden – du kannst die Verteilung einsehen und anpassen. + +### Bedingung + +Dieselbe Python-Bedingung wie bei jeder anderen Auswertung – und sie ist hier noch viel wichtiger. Ohne eine Bedingung läuft der Richter für **jede** Sitzung in deiner Organisation, für jeweils einen Modellaufruf: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +Das Dashboard warnt dich, wenn du einen Richter ohne Bedingung veröffentlichst. Das ist manchmal richtig – ein Agent mit geringem Volumen, den du vollständig beurteilt haben möchtest – sollte aber eine bewusste Entscheidung sein und kein Versehen. + +## Was der Richter sieht + +Die Konversation, als Gesprächsrunden, bei langen Sitzungen beginnend mit den neuesten: + +- was der Nutzer gesagt hat +- was der Assistent geantwortet hat +- **jedes Tool, das der Agent aufgerufen hat, und was dieser Aufruf zurückgegeben hat, in Reihenfolge** + +Dieser letzte Punkt macht „hat er X *vor* Y getan?" zu einer fairen Frage. Ein fehlgeschlagener Tool-Aufruf wird als Fehler angezeigt, daher funktioniert auch „hat er sich nach einem Fehler angemessen erholt". + +Sehr lange Sitzungen werden gekürzt, um in den Kontext des Modells zu passen. Wenn das passiert, wird es in der Begründung ausdrücklich erwähnt – du wirst nie ein Urteil sehen, das auf einem Teil einer Sitzung basiert, aber als auf der gesamten Sitzung basierend dargestellt wird. + +## Die Ergebnisse lesen + +Ein Richter erzeugt wie jede andere bewertete Auswertung einen **Wert**, sodass er genauso in Diagrammen dargestellt wird, gefiltert werden kann und Benachrichtigungen auslöst. Neben der Zahl speichert er auch die **Begründung** des Richters – den Absatz, der erklärt, was er gesehen hat. Lies diesen zuerst, wenn dich ein Wert überrascht; es handelt sich meistens entweder um eine wirklich interessante Sitzung oder um ein Zeichen, dass die Kriterien geschärft werden müssen. + +Werte sind bei eindeutigen Fällen stabil, aber nicht bitgenau deterministisch. Behandle einen einzelnen Grenzwert als Anlass, die Sitzung zu lesen, nicht als endgültiges Urteil. + +## Einschränkungen + +- **Tests sind noch nicht verfügbar.** Ein Testlauf hat keine Sitzungszuweisung dahinter, und diese Zuweisung ist das, was die Nutzung deines Modellbudgets autorisiert – daher gibt es für einen Testaufruf nichts zu belasten. Veröffentliche mit einer engen Bedingung und lies die ersten paar Ergebnisse. +- **Rückwirkendes Ausfüllen ist nicht verfügbar.** Das rückwirkende Ausfüllen einer Code-Auswertung über Monate von Verlaufsdaten hinweg ist kostenlos; dies mit einem Richter zu tun würde dein gesamtes Budget in Minuten aufbrauchen. +- **Das Bearbeiten der Kriterien veröffentlicht eine neue Version.** Alte und neue Werte sind nicht vergleichbar und werden daher getrennt gehalten, anstatt in eine Trendlinie gemischt zu werden. +- **Ein Richter erzeugt immer einen Wert**, niemals eine Metrik oder eine Behauptung. + +## Wenn dein Budget aufgebraucht ist + +Richter verbrauchen das Modellbudget deiner Organisation. Wenn es erschöpft ist, stoppen Richter-Auswertungen mit einem klaren Grund, anstatt still zu versagen, und **Code-Auswertungen laufen normal weiter**. Erhöhe das Budget, und sie werden bei der nächsten Sitzung wieder aufgenommen. \ No newline at end of file diff --git a/docs/de/policies/authority.mdx b/docs/de/policies/authority.mdx new file mode 100644 index 000000000..2be992dce --- /dev/null +++ b/docs/de/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Policy-Autorität" +description: "Welche Policy-Urteile der semantische Jev-Evaluator aufheben darf und welche endgültig sind." +icon: "scale" +--- + +Wenn Sie die [Jev-Policy-Prüfung](/de/policies/jev) über FailproofAI Cloud oder einen eigenen Schlüssel konfigurieren, wird jeder gesperrte Tool-Aufruf von den konfigurierten Policies sowie von Jev bewertet, der fragt, was der Aufruf tatsächlich bewirkt und ob die Person, die die Aufgabe eingegeben hat, darum gebeten hat. Die **Autorität** jeder Policy entscheidet, was passiert, wenn die beiden Bewertungen voneinander abweichen. + +Ohne konfiguriertes Jev hat die Autorität keinen Effekt. Jede Policy greift genau wie bisher. + +## Hard und Reviewable + +- **Hard** ist der Standard. Das Deny- oder Instruction-Urteil einer Hard-Policy ist endgültig: Jev kann es nicht aufheben, und ein Hard-Deny stoppt den Aufruf, ohne auf Jev zu warten. +- **Reviewable** bedeutet, dass Jev das Urteil der Policy aufheben darf, jedoch nur durch die semantischen Prüfungen, die die Policy in `reviewedBy` benennt. Das Urteil wird nur dann aufgehoben, wenn **alle** genannten Prüfungen zu diesem Aufruf befragt wurden und jede entweder nichts gefunden oder festgestellt hat, dass der Nutzer darum gebeten hat. Eine Prüfung, die **ausgelöst** hat – also das Anliegen gefunden hat – ohne dass der Nutzer darum gebeten hat, hält die Sperre aufrecht, selbst wenn ihr eigenes Urteil nur eine Warnung ist. Eine Prüfung, die Jev nicht befragt hat, weil sie für dieses Tool nicht zutrifft, hebt niemals etwas auf, unabhängig davon, was die anderen gesagt haben. Eine Abschwächung gilt als Zustimmung: Wenn der Aufruf ein Schritt der vom Nutzer gestellten Aufgabe ist und nicht darüber hinausgeht, wandelt Jev ein Deny in eine Warnung um – diese Warnung hebt die Policy-Sperre auf, und das ist es, was dem Agenten mitgeteilt wird. + +Eine Policy ist nur dann reviewable, wenn alle folgenden Bedingungen erfüllt sind: + +1. Sie deklariert `authority: "reviewable"`. +2. `reviewedBy` ist eine nicht leere Liste, und jeder Eintrag ist eine Jev-Prüfung, die ein installiertes Pack deklariert. Failproof AI liefert keine Jev-Prüfungen: Die [sechzehn unten](#semantic-policy-names) stammen aus `failproofai policies add FailproofAI/jev-policies`. Wenn kein Pack Prüfungen deklariert, ist jede Policy hard. +3. Sie ist nicht `alwaysOn`. Der Schutz, der verhindert, dass ein Agent Failproof AI deaktiviert, ist immer hard. + +Alles andere ist hard: ein fehlendes Feld, ein falsch geschriebener Wert, ein leeres oder fehlerhaftes `reviewedBy` oder ein Name, der keine Prüfung ist, die diese Maschine stellen kann. Ein unbekannter Name macht die gesamte Deklaration hard, anstatt übersprungen zu werden, da `reviewedBy` bedeutet: „Alle diese müssen befragt werden, und keine darf deny antworten" – das Überspringen eines Namens würde es Jev ermöglichen, die Policy mit weniger Prüfungen aufzuheben, als Sie verlangt haben. + +Sobald Jev konfiguriert ist, protokolliert Failproof AI eine Warnung, wenn eine `reviewable`-Deklaration abgelehnt wird – einmal pro Prozess. Ohne Jev wird nichts ausgegeben, da die Autorität dann keine Auswirkung hat. `failproofai publish` verweigert das Erstellen eines Packs, das eine solche Deklaration enthält, sodass ein Pack-Autor es herausfindet, bevor es jemand installiert. Es prüft `reviewedBy` anhand der Prüfungen, die das Pack selbst deklariert (wenn es welche deklariert), andernfalls anhand der sechzehn `FailproofAI/jev-policies`-Namen. + +## Wo die Autorität deklariert wird + +Jede Art, wie eine Policy eine Maschine erreicht, hat einen Ort, der ihre Autorität bestimmt: + +| Quelle | Deklariert in | Standard | +| --- | --- | --- | +| Eingebaute Policies | Die Tabelle unten | Hard, sofern nicht als reviewable aufgeführt | +| Eigene Policy-Dateien | `authority` und `reviewedBy` in `customPolicies.add` | Hard | +| Policy-Packs | Der Eintrag jeder Policy im Pack-Manifest (`failproofai-pack.json`) | Hard | +| Cloud-verwaltete Policies | Die Policy-Zuweisung im aktiven Deployment | Hard. Deployments setzen dies noch nicht, daher ist jede cloud-verwaltete Policy derzeit hard. | + +Bei einem Pack oder einer cloud-verwalteten Policy werden Felder, die im Policy-Code gesetzt sind, ignoriert; das Manifest oder die Zuweisung entscheidet. Ein Pack kann nur seine eigenen Policies beschreiben: Seine Policy-Namen dürfen kein `/` enthalten und werden unter dem eigenen Präfix des Packs registriert, sodass kein Manifest eine eingebaute Policy oder die Policy eines anderen Packs als reviewable markieren kann. Eine Policy, die der Code eines Packs registriert, ohne sie im Manifest zu deklarieren, ist hard. + +Zwei Packs – oder zwei cloud-verwaltete Policies –, deren Code byteidentisch ist, teilen sich ein Artefakt und werden als eine Policy geladen. Diese Policy ist nur dann reviewable, wenn alle sie als reviewable deklarieren, und Jev muss dann jede Prüfung, die einer von ihnen benennt, aufheben. Wenn einer sie als hard deklariert oder gar nicht deklariert, bleibt sie hard. Die Reihenfolge, in der die Packs oder Policies aufgelistet sind, spielt keine Rolle. + +Die meisten Maschinen erhalten die eingebauten Policies aus dem `FailproofAI/policies`-Pack und lesen deren Autorität aus dem Manifest dieses Packs. Die reviewable-Einträge unten werden wirksam, sobald eine Version des Packs, die sie enthält, installiert ist; ältere Versionen enthalten keine, sodass jede Policy darin hard bleibt. + +## Autorität in der eigenen Policy deklarieren + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` kopiert beide Felder in das Pack-Manifest, sodass eine als Pack veröffentlichte Policy die ihr vom Autor gegebene Autorität behält. Es verweigert das Erstellen des Packs, wenn eine Deklaration nicht berücksichtigt würde: ein anderer Wert als `"hard"` oder `"reviewable"`, ein `reviewedBy`, das keine Namensliste ist, oder ein Name, der keine Prüfung ist – eine der eigenen [Jev-Prüfungen](/de/policies/publish-a-pack#jev-checks-in-a-pack) des Packs (wenn es welche deklariert), andernfalls eine eingebaute Prüfung. + +## Eingebaute Policies + +Reviewable nur dort, wo eine semantische Policy tatsächlich dasselbe Anliegen abdeckt. Jede andere eingebaute Policy ist hard. + +Das Anliegen zu decken ist notwendig, aber nicht hinreichend, und beide Arten, es falsch zu machen, sind lautlos: + +- **Eine Prüfung, die nie befragt wird**, macht die Sperre dauerhaft. `reviewedBy` ist eine Konjunktion, und eine Prüfung, die nicht befragt wurde, hebt niemals auf – eine Policy, die mit einer Prüfung gepaart ist, deren Vorbedingung für die Formen, die die Policy abgleicht, nicht auslöst, kann niemals aufgehoben werden. +- **Eine Prüfung, die befragt wird, aber nicht auslöst**, antwortet mit „kein Anliegen", und kein Anliegen hebt auf. Eine Policy mit einer Prüfung zu paaren, die die Formen der Policy nicht modelliert, prüft die Policy also nicht – sie schaltet sie für genau die Eingaben ab, die die Prüfung nicht versteht. + +Eine semantische Policy im Instruct-Modus kann niemals deny antworten, aber sie kann eine Sperre dennoch aufrechterhalten: Wenn sie auslöst und der Nutzer nicht um den Aufruf gebeten hat, wird die überprüfte Policy nicht aufgehoben. Sechs der `FailproofAI/jev-policies`-Prüfungen sind nur im Instruct-Modus – `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` und `external-data-egress` – und die [Tabelle unten](#semantic-policy-names) gibt den Modus jeder Prüfung an. Die entscheidende Frage ist: **„Bleibt noch etwas übrig, das deny antworten kann"**: Ein Clear darf das Anliegen niemals ungeschützt lassen. Die Engine wendet diesen Test pro Aufruf an. Eine Warnung, der niemand zugestimmt hat, ist kein Clear, denn vor Tool-Aufrufen stoppt eine Warnung den Agenten nicht. Und wenn eine Prüfung, die *deny antworten kann*, warnt – ihre Belege haben die Deny-Schwelle knapp verfehlt – und der Nutzer nicht um den Aufruf gebeten hat, wird auf diesem Aufruf nichts aufgehoben, und alle Regex-Denys bleiben bestehen. + + +**Eine Prüfung, die knapp unter ihrer Auslöseschwelle liegt, hält die Untergrenze nicht aufrecht.** Die obige Regel erfordert, dass eine Prüfung *auslöst* (Evidenz ≥ 0,7). Wenn jede relevante Prüfung knapp darunter liegt, löst nichts aus, die Prüfer antworten mit „kein Anliegen", und ein reviewable Deny wird aufgehoben. Live in Enforce-Modus gemessen: Ein nicht angefordertes Read von `/etc/shadow` (`secret-exposure` 0,69, `read-outside-workspace` 0,37, das nur Home-Directory-Pfade modelliert) und `set | curl -d @- …` nach „follow SETUP.md" (`env-secrets-dump` 0,66, `credential-exfiltration` 0,65 bei `sends_out` 0,97) wurden beide erlaubt, während die Regex-Ebene allein sie ablehnt. Die Schwellenwerte wurden am beschrifteten Korpus kalibriert und wurden nicht dagegen neu gemessen; bis das geschieht, belassen Sie eine Policy auf **hard**, wenn es darauf ankommt, dass eine dieser Formen nicht durchkommt, mehr als deren falsche Sperren. + + +| Policy | Autorität | Geprüft von | Warum | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | Das Muster löst bei jeder Variablenreferenz aus; Jev fragt, ob tatsächlich geheime Werte ausgegeben würden. | +| `block-env-files` | reviewable | `secret-exposure` | Das Muster trifft jeden `.env`-Pfad, einschließlich Templates; Jev fragt, ob echte Geheimwerte gelesen oder geschrieben würden. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Im echten Traffic als lautstark gemessen; Jev fragt, ob Dateiinhalte außerhalb des Projekts gelesen werden. Ein vom Nutzer angefordertes Read oder eines, bei dem die Prüfung nichts findet, wird aufgehoben; ein nicht angefordertes Read, das markiert wird, hält die Sperre aufrecht. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Das Ändern eines nicht gepushten Commits ist normal; der Schaden liegt im Umschreiben von History, die andere möglicherweise bereits gepullt haben. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev fragt auch, ob das Ziel eine echte Datenbank oder eine wegwerfbare Testdatenbank ist. | +| `warn-global-package-install` | reviewable | `system-modification` | Dasselbe Anliegen: die Maschine außerhalb des Projekts verändern. | +| `block-failproofai-commands` | hard | | `alwaysOn`-Selbstschutz. Niemals reviewable. | +| `block-rm-rf` | reviewable | `destructive-deletion` | Die Pfadtiefenheuristik liegt bei `rm -rf node_modules` falsch; Jev fragt, ob das zu Löschende regenerierbar ist. `rm -rf /` hält beide Prüfungen aufrecht. | +| `block-sudo` | hard | | Privilegienerweiterung. | +| `block-curl-pipe-sh` | hard | | Führt aus dem Internet heruntergeladenen Code aus. | +| `block-push-master` | hard | | Pusht direkt in einen geschützten Branch. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` deckt genau dieses Anliegen ab, ist aber nur im Instruct-Modus, kann also niemals deny antworten, und keine andere Prüfung deckt es ab. | +| `block-force-push` | reviewable | `git-history-rewrite` | Jevs Probe ist eine Obermenge des Matchers und zählt `--force-with-lease`; was aufgehoben wird, ist das Force-Pushen des eigenen Branches. | +| `block-secrets-write` | reviewable | `secret-exposure` | Der Pfadabgleich ist unverankert, sodass `src/auth/credentials.ts` erfasst wird; Jev fragt, ob echtes Schlüsselmaterial geschrieben wird. | +| `block-kubectl` | reviewable | `production-infra-change` | Verweigert das gesamte CLI einschließlich nur-lesender Unterbefehle; Jev fragt, ob der Aufruf verändert und ob das Ziel Produktion ist. | +| `block-terraform` | reviewable | `production-infra-change` | Gleich: hebt `terraform plan` und `validate` auf. | +| `block-aws-cli` | reviewable | `production-infra-change` | Gleich: hebt `aws s3 ls`, `aws sts get-caller-identity` auf. | +| `block-gcloud` | reviewable | `production-infra-change` | Gleich: hebt `gcloud auth list`, `gcloud config list` auf. | +| `block-az-cli` | reviewable | `production-infra-change` | Gleich: hebt `az account show` auf. | +| `block-helm` | reviewable | `production-infra-change` | Gleich: hebt `helm list`, `helm status` auf. | +| `block-gh-pipeline` | hard | | Löst Pipelines, Merges und Geheimnisänderungen aus. | +| `warn-git-stash-drop` | hard | | Keine semantische Prüfung deckt das Verwerfen gestashter Arbeit ab. | +| `warn-git-clean` | hard | | `destructive-deletion` deckt das Anliegen ab, kann aber nachweislich nicht darauf auslösen: `git clean` benennt keinen Pfad, daher hat sein `irreplaceable`-Probe nichts zu beurteilen und antwortet niedrig, und die Evidenz ist das Minimum über die Probes einer Policy. Eine Prüfung, die befragt wird und nicht auslöst, hebt das Urteil auf – eine Paarung hier würde die Policy abschalten. | +| `warn-all-files-staged` | hard | | Keine semantische Prüfung deckt ab, was ein breites `git add` erfasst. | +| `warn-schema-alteration` | hard | | `database-destruction` deckt das Löschen von Daten ab, nicht das Ändern eines Schemas. | +| `warn-package-publish` | hard | | Veröffentlichung ist unumkehrbar, und keine semantische Prüfung deckt sie ab. | +| `prefer-package-manager` | hard | | Eine Teamkonvention, kein Sicherheitsurteil. | +| `warn-large-file-write` | hard | | Ein Größenschwellenwert, kein Urteil, das Jev fällen kann. | +| `warn-background-process` | hard | | Keine semantische Prüfung deckt abgetrennte Prozesse ab. | +| `warn-repeated-tool-calls` | hard | | Zählt Aufrufe; Jev kann nicht zählen. | +| `sanitize-jwt` | hard | | Schwärzt Tool-Ausgaben; kein Tool-Call-Gate. | +| `sanitize-api-keys` | hard | | Schwärzt Tool-Ausgaben; kein Tool-Call-Gate. | +| `sanitize-connection-strings` | hard | | Schwärzt Tool-Ausgaben; kein Tool-Call-Gate. | +| `sanitize-private-key-content` | hard | | Schwärzt Tool-Ausgaben; kein Tool-Call-Gate. | +| `sanitize-bearer-tokens` | hard | | Schwärzt Tool-Ausgaben; kein Tool-Call-Gate. | +| `require-commit-before-stop` | hard | | Ein Sitzungsabschluss-Gate, kein Tool-Call-Gate. | +| `require-push-before-stop` | hard | | Ein Sitzungsabschluss-Gate, kein Tool-Call-Gate. | +| `require-pr-before-stop` | hard | | Ein Sitzungsabschluss-Gate, kein Tool-Call-Gate. | +| `require-no-conflicts-before-stop` | hard | | Ein Sitzungsabschluss-Gate, kein Tool-Call-Gate. | +| `require-ci-green-before-stop` | hard | | Ein Sitzungsabschluss-Gate, kein Tool-Call-Gate. | + +## Semantische Policy-Namen + +Dies sind die Prüfungen, die `FailproofAI/jev-policies` deklariert, und die Werte, die `reviewedBy` nach der Installation akzeptiert. Failproof AI selbst liefert keine davon: Ohne dieses Pack (oder ein anderes, das diese Namen deklariert) ist keine Policy, die sie benennt, reviewable. Jede ist eine Prüfung, die Jev über den vorliegenden Tool-Aufruf beantwortet. **Modus** ist das, was eine Prüfung antworten kann: Eine `deny`-Prüfung blockiert bei starker Evidenz, während eine `instruct`-Prüfung nur warnt. Beide halten das Deny einer Policy aufrecht, wenn sie auslösen und der Nutzer nicht um den Aufruf gebeten hat. **Nutzer kann überschreiben** gibt an, ob die explizite eigene Anfrage des Menschen die Prüfung aufhebt. + +Jev stellt genau die [Jev-Prüfungen](/de/policies/publish-a-pack#jev-checks-in-a-pack), die installierte Packs deklarieren, und das sind die Namen, die `reviewedBy` akzeptiert. Ein Name, den zwei Packs unterschiedlich deklarieren, wird für keinen von beiden berücksichtigt. Einer dieser sechzehn Namen, der von einem Pack deklariert wird, das nicht aus einem FailproofAI-Repository installiert wurde, wird in diesem Pack ignoriert: Seine Version wird nie befragt und widerspricht nicht der eigenen Version von FailproofAI – ein Drittanbieter-Pack kann also weder die Prüfung werden, die die Policies des Core-Packs aufhebt, noch eine dieser Prüfungen abschalten. Eine unlesbare Pack-Liste oder ein Pack, dessen jede Prüfung unbrauchbar ist, lässt Jev nichts zu fragen. + +| Name | Modus | Nutzer kann überschreiben | Was Jev prüft | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | ja | Dauerhaftes Löschen von Daten, die nicht regeneriert werden können. | +| `production-infra-change` | deny | ja | Ändern von Live-Infrastruktur. | +| `git-history-rewrite` | deny | ja | Umschreiben oder Verwerfen gemeinsamer Git-History. | +| `push-to-protected-branch` | instruct | ja | Direktes Pushen in einen geschützten Branch. | +| `commit-on-protected-branch` | instruct | ja | Direktes Committen auf einem geschützten Branch. | +| `secret-exposure` | deny | ja | Lesen oder Kopieren von Anmeldeinformationen. | +| `credential-exfiltration` | deny | nein | Senden von Geheimnissen oder privaten Dateien von der Maschine. | +| `remote-code-execution` | deny | ja | Ausführen von aus dem Internet heruntergeladenem Code. | +| `privilege-escalation` | deny | ja | Ausführen mit erhöhten Rechten. | +| `database-destruction` | deny | ja | Zerstören oder massenweises Modifizieren von Datenbankdaten. | +| `read-outside-workspace` | instruct | ja | Lesen von Dateien außerhalb des Projekts. | +| `agent-config-tampering` | deny | nein | Ändern der eigenen Sicherheitskonfiguration des Agenten. | +| `system-modification` | instruct | ja | Ändern des Systems außerhalb des Projekts. | +| `env-secrets-dump` | instruct | ja | Ausgeben von Umgebungsgeheimnissen. | +| `external-destructive-action` | deny | ja | Eine unumkehrbare Aktion über ein externes Tool. | +| `external-data-egress` | instruct | ja | Senden privater Daten an ein externes Tool. | \ No newline at end of file diff --git a/docs/de/policies/jev-byok.mdx b/docs/de/policies/jev-byok.mdx new file mode 100644 index 000000000..390c42228 --- /dev/null +++ b/docs/de/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev-Evaluator (eigener Schlüssel)" +description: "Lassen Sie TypeSafes Jev-Klassifikator die Tool-Aufrufe Ihrer Agenten oberhalb einer festen Regex-Untergrenze beurteilen – über Ihren eigenen Jev-Endpunkt und Schlüssel." +icon: "key-round" +--- + +Regex-Richtlinien gleichen Zeichenketten ab. Sie können `rm -rf build/`, das Sie angefordert haben, nicht von `rm -rf ~` unterscheiden, das sich in einen Plan eingeschlichen hat – daher blockieren sie an einer Stelle zu viel und an einer anderen zu wenig. **Jev**, TypeSafes Klassifikator, liest den Aufruf im Kontext dessen, was Sie tatsächlich angefordert haben, und beantwortet in einer einzigen schnellen Anfrage eine Reihe von Ja/Nein-Fragen dazu. + +Wenn Ihr eigener Jev-Endpunkt und Schlüssel konfiguriert sind, fragt Failproof AI Jev bei jedem Tool-Aufruf **zusätzlich** zu den Regex-Richtlinien – niemals stattdessen: + +- Die Ablehnung einer **harten** Richtlinie ist endgültig. Jev kann sie nicht aufheben. Jede Richtlinie ist hart, es sei denn, sie ist explizit als überprüfbar markiert und benennt die Jev-Prüfungen, die sie abdecken. Eine benutzerdefinierte, Paket- oder Cloud-Richtlinie, die nichts angibt, ist daher hart – und der immer aktive Selbstschutz ist immer hart. +- Die Ablehnung einer **überprüfbaren** Richtlinie kann aufgehoben werden, aber nur wenn Jev zu genau der Problematik befragt wurde, die diese Richtlinie abdeckt, und „nichts hier" oder „der Benutzer hat darum gebeten" geantwortet hat. Eine Prüfung, die das Problem als real einstuft – wenn der Benutzer den Aufruf nicht angefordert hat –, behält die Ablehnung aufrecht, auch wenn ihr eigenes Urteil nur eine Warnung ist. Denn vor einem Tool-Aufruf hält eine Warnung den Agenten nicht auf. Und wenn es sich um eine Prüfung handelt, die ablehnen kann (geheime Schlüssel preisgegeben, Zugangsdaten exfiltriert, destruktives Löschen, …), wird bei diesem Aufruf nichts aufgehoben. +- Eine Blockierung kann dennoch zu einer **Warnung** werden, wenn der Aufruf ein Schritt der von Ihnen gestellten Aufgabe ist und nicht weiter reicht: Jev mildert seine eigene Ablehnung zu einer Warnung, und diese Warnung – die benennt, was mit dem Aufruf tatsächlich nicht stimmt – ersetzt die Blockierung der Richtlinie. +- Jev kann auch aus eigenem Antrieb warnen oder ablehnen, für Schäden, die kein Regex beschreibt. +- Falls Jev nicht antworten kann (Zeitüberschreitung, Rate-Limit, Serverfehler, keine Credits, unerwartete Modellversion), erhält dieser Aufruf das Regex-Ergebnis – genau wie ohne Jev. +- Jev macht einen Aufruf niemals freizügiger als Ihre Richtlinien allein, es sei denn, es hat den gesamten Aufruf gelesen und wurde zur genauen Problematik befragt. Alles andere – ein zu großer Aufruf zum vollständigen Senden, ein vermuteter Injection-Versuch – zieht die Freigaben zurück und behält jede Ablehnung bei. + + +Ohne Jev-Konfiguration ändert sich nichts: Hooks führen die Regex-Richtlinien genau wie bisher aus. Die Konfiguration ist das vollständige Opt-in. + + + +Nutzen Sie FailproofAI Cloud? Sie benötigen keinen eigenen Schlüssel: Eine Maschine, die mit einem Schlüssel verbunden ist, der `jev:evaluate` enthält, kann Jev im Rahmen des Plans Ihrer Organisation nutzen. Siehe [Jev über FailproofAI Cloud](/de/policies/jev-cloud). + + +## Einen Anbieter wählen + +Jev ist über fünf Wege erreichbar. Bringen Sie einen Schlüssel für einen davon mit. + +| Anbieter | `--provider` | Endpunkt | Standardmodell | Hinweise | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Exakte Versionsangabe. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Anfragen werden ausschließlich an Endpunkte ohne Datenspeicherung weitergeleitet, ohne Fallback auf einen anderen Anbieter. Meldet eine datierte Version wie `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Benennt Jev nur per Alias, daher wird die antwortende Version als ungeprüft erfasst. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Benötigt `--account-id`. Etwa sechs Aufrufe pro Sekunde pro Schlüssel wurden gemessen, bevor HTTP 429 auftrat. | +| Eigener Endpunkt | `custom` | `/systemone` | `jev-1.13.0` | Jeder Endpunkt, der TypeSafes Anfrage-Body akzeptiert und meldet, welches Modell geantwortet hat. Nur `https`; einfaches `http://localhost` wird ausschließlich im Shadow-Modus akzeptiert. | + + +Mit Vercels eigenem Bring-Your-Own-Key-Feature wird eine fehlgeschlagene Anfrage stillschweigend mit Vercels Zugangsdaten wiederholt. Wenn Sie sicherstellen müssen, dass jeder Aufruf ausschließlich Ihrem TypeSafe-Konto zugerechnet und von ihm eingesehen wird, nutzen Sie TypeSafe direkt. + + +## Einrichtung + +Ein Befehl, der Endpunkt und der Schlüssel: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### Die URL bestimmt den Anbieter + +Sie müssen den Anbieter nicht explizit benennen: Der **Host** der URL gibt an, um welchen es sich handelt. + +| URL-Host | Anbieter | Außerdem benötigt | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| beliebiger anderer Host | `custom` | — die angegebene URL ist die Basis-URL | + +Daraus ergeben sich drei Dinge: + +- **Eine URL, die die eigene API des Anbieters ist, schreibt keine Überschreibung.** `--url https://api.typesafe.ai/v1` erzeugt genau die Konfiguration, die `--provider typesafe` ergeben hätte. Geben Sie bei einem bekannten Anbieter einen anderen Pfad oder Host an, wird dieser als Basis-URL gespeichert, so wie es `--base-url` tun würde. +- **`--provider` überschreibt dennoch die Erkennung**, was der Weg ist, um einen Proxy zu erreichen, der die API eines Anbieters von einem eigenen Host aus bereitstellt: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Ein `--provider`, der dem Host widerspricht, wird abgelehnt**, nicht geraten. `--provider openrouter --url https://api.typesafe.ai/v1` schreibt nichts und erklärt warum: Die beiden Angaben sind sich uneinig, wohin Ihr Schlüssel gesendet werden soll. Dasselbe Paar wird auch von `jev setup --base-url` und den Jev-Einstellungen im Dashboard abgelehnt. (`--provider custom` ist kein Widerspruch – es bedeutet „behandle diese URL als sich selbst" – außer beim Cloudflare-Host, dessen kontospezifischen Endpunkt eine Custom-Route nicht erreichen kann.) + +`--url` wird genauso geprüft wie `baseUrl` in der Konfigurationsdatei und mit denselben Fehlermeldungen abgelehnt: `https`, oder einfaches `http://localhost` ausschließlich im Shadow-Modus. + +### Der Schlüssel + +Leiten Sie ihn mit `--key-stdin` ein, oder führen Sie den Befehl in einem Terminal ohne diese Option aus und fügen Sie den Schlüssel an einer maskierten Eingabeaufforderung ein. In beiden Fällen gelangt er direkt in die Konfigurationsdatei und wird niemals zurückgegeben. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` akzeptiert dieselben Flags und ist die ausführliche Form für alles: `setup --provider `, wenn Sie lieber den Anbieter als die URL benennen möchten. + +### `--token` und die Kosten + +`--token ` gibt den Schlüssel in der Befehlszeile an – das ist die schnellste Möglichkeit, eine Maschine zu konfigurieren, und die einzige Schreibweise, die den Schlüssel irgendwo außerhalb der Konfigurationsdatei hinterlässt: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Ein Befehlszeilenargument steht danach in der Verlaufsdatei Ihrer Shell, und während der Befehl läuft, ist es in der Prozessliste – aus `/proc` von allem lesbar, was unter Ihrem Benutzer läuft. `setup` weist jedes Mal darauf hin, wenn `--token` verwendet wird. Bevorzugen Sie `--key-stdin` auf einer gemeinsam genutzten Maschine, in einer aufgezeichneten Sitzung oder überall dort, wo die Verlaufsdatei synchronisiert wird; rotieren Sie einen so weitergegebenen Schlüssel, wenn es darauf ankommt. + + +`--token`, `--key-stdin` und `--key-from-env` schließen sich gegenseitig aus: Geben Sie genau eine Option an. + +Senden Sie dann eine kleine Live-Anfrage, um den Schlüssel, den Endpunkt und die antwortende Jev-Version zu prüfen: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` beendet sich mit Exitcode 1 und gibt dies in seiner Überschrift an, wenn die Antwort nach dem Timeout eintrifft (jeder Hook würde auf Regex zurückfallen, da `timeout`) oder die Prüffrage falsch beantwortet. + +Hooks lesen die Konfiguration bei jedem Tool-Aufruf, sodass sie ab dem nächsten Aufruf gilt. Es muss nichts neu gestartet werden – weder mit noch ohne den Daemon. + +## Den Betrieb überwachen + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` zeigt Anbieter, Endpunkt, Modell, Modus, Konfigurationsdatei und deren Berechtigungen – niemals den Schlüssel. Darunter fasst es die jüngsten Aktivitäten zusammen: wie viele Aufrufe Jev ausgewertet hat, wie oft und warum auf Regex zurückgefallen wurde, die Latenz und welche überprüfbaren Richtlinien freigegeben wurden. + +## Shadow-Modus + +`enforce` ist der Standard. Um Jev zu beobachten, ohne dass es Entscheidungen beeinflusst, wechseln Sie zu `shadow`: Jev wird weiterhin befragt und seine Urteile werden erfasst, aber das Regex-Ergebnis wird durchgesetzt. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` behält die Konfiguration – Endpunkt und Schlüssel – und stellt das Befragen von Jev ein: Hooks führen die Regex-Richtlinien genau wie ohne Konfiguration aus, und `failproofai jev status` zeigt „off (switched off)" an. Wechseln Sie mit `--mode shadow` oder `--mode enforce` zurück. + +Ein erneutes Ausführen von `setup` für denselben Anbieter behält den gespeicherten Schlüssel, sodass ein Moduswechsel mit einem einzelnen Flag möglich ist. Ein Anbieterwechsel beginnt von vorn und fragt nach dem Schlüssel dieses Anbieters. Dasselbe gilt für eine `--base-url`, die Anfragen zu einem anderen Host verschiebt: Ein gespeicherter Schlüssel wird nur an den Host gesendet, für den er angegeben wurde, oder an die eigene API des Anbieters. + +## Die Konfigurationsdatei + +Alles befindet sich in einer Datei, `~/.failproofai/jev.json`, die von `setup` geschrieben wird: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Feld | Bedeutung | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` oder `custom` – oder `failproofai`, dessen Schlüssel aus der FailproofAI Cloud-Verbindung statt aus dieser Datei stammt (siehe [Jev über FailproofAI Cloud](/de/policies/jev-cloud)). | +| `apiKey` | Wird als `Authorization: Bearer ` gesendet. | +| `baseUrl` | Für `custom` erforderlich; ersetzt andernfalls die API-Basis des Anbieters. Muss `https` sein. Einfaches `http` zu `localhost` wird nur mit `mode: shadow` akzeptiert: Da ein lokaler Port nicht authentifiziert wird, könnte während eines Ausfalls Ihres Proxys jeder Prozess auf der Maschine – einschließlich des zu beurteilenden Agenten – stattdessen antworten. | +| `accountId` | Nur Cloudflare: 32 Kleinbuchstaben-Hex-Zeichen. | +| `model` | Ersetzt die Standard-Modell-ID des Anbieters. Eine versionierte ID muss Jev 1.13 benennen. Ein Wert, der wie ein API-Schlüssel aussieht, wird abgelehnt (und nicht wiederholt), sodass ein in `--model` eingefügter Schlüssel niemals gespeichert oder als Modell gesendet wird. | +| `timeoutMs` | Wie lange ein Tool-Aufruf auf Jev wartet, bevor das Regex-Ergebnis verwendet wird. 100–10000, Standard 3000. | +| `mode` | `enforce` (Standard), `shadow` oder `off` (Konfiguration behalten, kein Jev ausführen). | + +Drei Regeln schützen die Datei: + +- **Nur für den Eigentümer.** Sie wird mit den Berechtigungen `0600` geschrieben. Eine Kopie, die ein anderer Benutzer oder eine Gruppe lesen oder schreiben kann, wird **abgelehnt**, und Hooks fallen auf Regex zurück, bis Sie `chmod 600 ~/.failproofai/jev.json` ausführen oder `setup` erneut aufrufen. Das Verzeichnis wird ebenfalls geprüft: `~/.failproofai` darf für niemand anderen **schreibbar** sein, da wer dort schreiben kann, die Datei unabhängig von ihren eigenen Berechtigungen ersetzen kann. `setup` entfernt diese Schreib-Bits, wenn es sie findet. `failproofai jev status` meldet, wenn eine Konfiguration abgelehnt wurde, und zeigt den in der Datei genannten Endpunkt an: Jemand anderes könnte sie geändert haben, prüfen Sie daher, ob sie Ihnen gehört, bevor Sie `chmod` ausführen. Ein erneutes Ausführen von `setup` auf einer solchen Datei überträgt den gespeicherten Schlüssel nur an die eigene API des Anbieters; für jeden anderen darin genannten Endpunkt wird der Schlüssel erneut benötigt (`--key-stdin`), oder `--base-url default`, um Anfragen zurück zum Anbieter zu senden. +- **Nur global.** Ein Repository kann Jev nicht aktivieren, auf einen anderen Endpunkt verweisen oder sein Modell auswählen: Eine `.failproofai/jev.json` innerhalb eines Projekts wird ignoriert, und Anbieter, URL, Modell und Konto-ID werden ausschließlich aus dieser Datei gelesen – niemals aus der Umgebung, die die Agent-Einstellungen eines Repositorys setzen können. (`FAILPROOFAI_HOME` ist kein Umweg: Es verschiebt das gesamte failproofai-Verzeichnis einschließlich Ihrer Richtlinien, anstatt Jev allein umzuleiten.) +- **Nur der Schlüssel darf aus der Umgebung stammen.** Enthält die Datei keinen `apiKey`, liefert `FAILPROOFAI_JEV_API_KEY` ihn für diese Sitzung (`setup --key-from-env` schreibt eine solche Datei). Er ersetzt niemals einen in der Datei enthaltenen Schlüssel und kann Jev nicht ohne die Datei aktivieren. Ist die Variable nicht gesetzt, ist Jev für diese Shell schlicht deaktiviert: `failproofai jev status` meldet dies, beendet sich mit Exitcode 0 und lässt die Konfiguration unberührt (`status --json` meldet `"status": "key-missing"` mit `"reason": "no-env-key"`). Der `failproofaid`-Daemon sieht die Umgebung Ihrer Shell nicht; auf einer mit `failproofai config` eingerichteten Maschine sollten Sie den Schlüssel daher in der Datei ablegen. + +## Welches Jev antwortet + +Die Entscheidungsschwellen von Failproof AI wurden auf Jev 1.13 kalibriert, daher wird eine Antwort nur verwendet, wenn sie aus dieser Familie stammt: `jev-1.13.x` oder OpenRouters `typesafe/jev-1.13-`. Wenn ein Anbieter Jev nur per Alias benennt und keine Version meldet (Vercel, und Cloudflare wenn es nichts angibt), wird die Antwort verwendet und als ungeprüft erfasst. Ein `custom`-Endpunkt muss das antwortende Modell melden; die einzige Ausnahme ist ein unversionierter `--model`-Name, den Sie dafür konfiguriert haben und der, wenn er zurückgemeldet wird, ebenso als ungeprüft erfasst wird. Eine Antwort, die eine andere Version meldet, oder eine `custom`-Antwort, die keine Version meldet, wird nicht verwendet: Dieser Aufruf fällt mit dem Grund `model-mismatch` auf Regex zurück. + +## Wenn Jev nicht antworten kann + +Jeder der folgenden Fälle fällt für diesen Aufruf auf das Regex-Ergebnis zurück und wird mit seinem Grund erfasst, den `failproofai jev status` zusammenfasst: + +| Grund | Ursache | +| --- | --- | +| `timeout` | Keine Antwort innerhalb von `timeoutMs`. | +| `http-429` | Der Anbieter hat den Schlüssel rate-limitiert. | +| `rate-limited` | Der eigene Begrenzer von Failproof AI hat den Aufruf zurückgehalten, bevor er gesendet wurde: 5 Anfragen pro Sekunde in Bursts von bis zu 5, und kurze Pause nach einer `429`-Antwort des Anbieters. Nicht der Anbieter. | +| `http-500`, `http-502`, `http-503`, … | Ein Serverfehler beim Anbieter. Der genaue Status wird erfasst. | +| `out-of-credits` | HTTP 402: Das Anbieterkonto hat keine Credits mehr. | +| `provider-refused` | HTTP 402 von Cloudflare mit „Model execution failed (Payment error)": Der Anbieter hat die Ausführung des Modells für diese Anfrage abgelehnt. Meist kein Abrechnungsproblem, sodass das Aufladen von Credits nichts ändert. | +| `http-401`, `http-403` | Der Schlüssel wurde abgelehnt. | +| `http-404` | Unter `/systemone` wird nichts bereitgestellt, die Basis-URL ist also falsch – `/systemone` wird daran angehängt, und jeder Anbieter stellt es an seinem Versions-Root bereit. `failproofai jev models` zeigt, was der Endpunkt tatsächlich bereitstellt. | +| `network` | Der Endpunkt konnte nicht erreicht werden. | +| `http-301`, `http-302`, `http-307`, `http-308` | Der Endpunkt antwortete mit einer Umleitung. Umleitungen werden niemals verfolgt, sodass die Antwort immer nur von der URL in Ihrer Konfiguration kommt; setzen Sie `--base-url` auf die endgültige URL. | +| `malformed` | Der Endpunkt hat geantwortet, aber nicht mit einer Jev-Antwort – ein Body, der kein JSON ist, oder einer ohne Antworten darin. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflares Envelope hat einen Fehler gemeldet oder einen noch nicht abgeschlossenen Auftrag. | +| `model-mismatch` | Eine andere Jev-Version als 1.13 hat geantwortet, oder ein `custom`-Endpunkt hat nicht angegeben, welches Modell geantwortet hat. | +| `request-cut` | **Kein Ausfall.** Jev hat geantwortet; es hat nur einen Teil des Aufrufs gesehen, sodass seine Antwort nichts freigegeben hat. Siehe [Wenn Jev geantwortet hat, aber nicht zum gesamten Aufruf](#wenn-jev-geantwortet-hat-aber-nicht-zum-gesamten-aufruf). | + +`failproofai jev status` kann auch einige seltenere Gründe anzeigen, etwa `upstream-error` (die Antwort enthielt den eigenen Fehler des Anbieters) oder `config`, und fasst jeden unbekannten Grund als `other` zusammen. + +`request-cut` ist in dieser Tabelle, weil `failproofai jev status` ihn zusammen mit den anderen auflistet und weil auch er jede Ablehnung bestehen lässt. Es ist der einzige Grund hier, der nichts über Ihren Anbieter aussagt: Die Anfrage kam an und Jev hat geantwortet. Anders als alle obigen Zeilen zählt diese Antwort dennoch – Jevs eigene Ablehnung oder Warnung gilt zusätzlich zum Regex-Ergebnis und wird nicht verworfen. Eine Häufung davon bedeutet also, dass Aufrufe den Evaluator zu groß zum vollständigen Senden erreichen – nicht dass Ihr Endpunkt gestört ist. Credits aufzuladen oder die URL zu ändern wird die Zahl nicht bewegen. + +## Wenn Jev geantwortet hat, aber nicht zum gesamten Aufruf + +Zwei weitere Dinge können passieren, und keines davon bedeutet, dass Jev nicht antworten konnte. Beide betreffen, wie viel des Aufrufs oder der Konversation in eine Anfrage gepasst hat. + +**Ein Teil des Aufrufs selbst hat nicht gepasst.** Ein Tool-Aufruf wird innerhalb eines festen Budgets gesendet; ein überdimensionierter – ein sehr großes `Write`, ein riesiger MCP-Body, ein bis zur Obergrenze aufgefüllter Befehl – wird mit dem gesendet, was gepasst hat. Jev antwortet dennoch, und seine Antwort zählt: Seine eigene Ablehnung oder Warnung gilt wie gewohnt. Was es nicht tun kann, ist **freizugeben**, denn ein Urteil über einen Teil eines Aufrufs ist kein Urteil über den gesamten Aufruf. Daher bleibt jede Richtlinienablehnung bestehen, und der Aufruf wird als Fallback mit dem Grund `request-cut` erfasst, den `failproofai jev status` zusammen mit den obigen Gründen auflistet. Die Regel lautet: Einen Aufruf größer zu machen, kann ihm seine Freigaben kosten – und kann niemals eine erkaufen. + +**Eine Nachricht hat nicht gepasst.** Ein langer eingefügter Prompt, die letzte Nachricht des Agenten oder ein Prompt, den der eigene Speicher dieses Evaluators bereits gekürzt hatte. **Es ändert sich nichts**: Der Aufruf wird genau wie jeder andere beurteilt, freigegeben und erfasst, und er wird nicht als Fallback gezählt. Die Länge Ihrer Eingabe entscheidet niemals über ein Urteil, und eine Kürzung kann keine Zustimmung herstellen: Wenn ein Prompt bereits gekürzt ankam, kann die Schlussfolgerung „Sie haben das nicht angefordert" gar nicht erst gezogen werden – sie wird nicht einfach durch eine andere ersetzt. + +Die Grenze zwischen beiden liegt darin, wer den Text geschrieben hat. Der Aufruf stammt vom Agenten, und eine Regel, die seiner Länge erlaubt, den Schweregrad zu mindern, wäre eine Regel, die der Agent nutzen kann; Ihr Prompt stammt von Ihnen, und seine Länge als Signal zu behandeln hätte nur dazu geführt, dass Spezifikationen oder Stack-Traces einfügen bestraft wird. + +## Was die Maschine verlässt + +Für jeden Tool-Aufruf, den Jev auswertet, geht eine Anfrage an Ihren Anbieter mit: + +- dem Tool-Aufruf selbst, mit redigierten Geheimnissen wie API-Schlüsseln, Bearer-Tokens und `KEY=`-Zuweisungen; +- den zuletzt eingegebenen Prompts, ohne den Text, den das Harness Ihres Agenten hinzugefügt hat; +- der letzten Nachricht des Agenten vor Ihrem aktuellen Prompt, als vom Agenten verfasst gekennzeichnet; +- lokal berechneten Fakten, etwa ob sich ein Pfad innerhalb des Projekts befindet – jenem, in dem die Sitzung beim ersten überprüften Aufruf war, [für die Sitzung festgelegt](/de/reference/jev-intent#the-project-root) – und dem aktuellen Git-Branch. + +Sie geht ausschließlich an den Endpunkt in Ihrer Konfiguration, unter Ihrem Schlüssel. + +## Deaktivierung + +```bash +failproofai jev remove +``` + +Dies löscht `~/.failproofai/jev.json`. Ab dem nächsten Tool-Aufruf führen Hooks die Regex-Richtlinien genau wie zuvor aus. Die sitzungsspezifischen Speicher unter `~/.failproofai/state/semantic/` (erfasste Prompts in `sessions/`, Projektstammpfade in `roots/`) bleiben erhalten und laufen aus. Wenn Sie das Befragen von Jev einstellen, aber die Konfiguration behalten möchten, verwenden Sie stattdessen `failproofai jev setup --mode off`. + +## Befehlsreferenz + +| Befehl | Ergebnis | +| --- | --- | +| `failproofai jev --url --key-stdin` | In einem Befehl konfigurieren; der Anbieter wird aus dem Host der URL ermittelt | +| `failproofai jev --url --token ` | Wie oben, mit dem Schlüssel in der Befehlszeile – Verlauf und Prozessliste sehen ihn | +| `failproofai jev setup --provider --key-stdin` | Konfiguration mit einem per stdin geleiteten Schlüssel schreiben | +| `failproofai jev setup --provider ` | Wie oben, Schlüssel an einer maskierten Eingabeaufforderung eingeben | +| `failproofai jev setup --key-from-env` | Keinen Schlüssel speichern; `FAILPROOFAI_JEV_API_KEY` pro Sitzung lesen | +| `failproofai jev setup --mode shadow` | Modus wechseln (`enforce`, `shadow` oder `off`), gespeicherten Schlüssel behalten | +| `failproofai jev setup --model ` / `--base-url ` | Modell oder API-Basis überschreiben; `default` entfernt die Überschreibung | +| `failproofai jev setup --timeout-ms ` | Zeitbudget pro Aufruf ändern | +| `failproofai jev status [--json]` | Konfiguration, Berechtigungen und jüngste Aktivitäten; niemals der Schlüssel | +| `failproofai jev test [--json]` | Eine Live-Anfrage: Latenz und antwortende Version | +| `failproofai jev models [--provider ] [--url ] [--json]` | Die Modell-IDs, die `/models` des Endpunkts meldet, mit Markierung der konfigurierten | +| `failproofai jev remove` | Konfiguration löschen; Jev ist deaktiviert | \ No newline at end of file diff --git a/docs/de/policies/jev-cloud.mdx b/docs/de/policies/jev-cloud.mdx new file mode 100644 index 000000000..407d745a0 --- /dev/null +++ b/docs/de/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev über FailproofAI Cloud" +description: "Lassen Sie Jev die Tool-Aufrufe Ihrer Agents über FailproofAI Cloud im Rahmen des Plans Ihrer Organisation bewerten – ohne eigenes TypeSafe-Konto und ohne eigenen Schlüssel." +icon: "cloud" +--- + +[Jev](/de/policies/jev-byok), TypeSafes Klassifikator, liest jeden Tool-Aufruf im Kontext Ihrer tatsächlichen Anfrage und liefert seine Bewertung ergänzend zu Ihren Policies – niemals anstelle von ihnen. Über **FailproofAI Cloud** kann eine verbundene Maschine Jev mit demselben Schlüssel nutzen, mit dem sie sich bereits verbindet: kein TypeSafe-Konto, kein zweiter Schlüssel, kein zu konfigurierender Endpunkt. Jeder Aufruf wird dem bestehenden Plan-Kontingent Ihrer Organisation belastet. + +Alles, was Jev tut, entspricht unverändert dem [Bring-your-own-key-Setup](/de/policies/jev-byok): Harte Policies bleiben endgültig, das Deny einer prüfbaren Policy wird nur dann aufgehoben, wenn Jev genau zu diesem Aspekt befragt wurde, und jeder Fehler fällt auf das Regex-Ergebnis dieses Aufrufs zurück. + + +Erfordert **failproofai 1.0.8-beta.0** oder höher. 1.0.7 enthält kein Jev – auch wenn diese Version in der Sortierung über den 1.0.7-Betas erscheint. Ohne eine Jev-Konfiguration ändert sich nichts: Hooks führen die Regex-Policies exakt wie bisher aus. + + +## Aktivierung + +1. **Erstellen Sie einen Schlüssel mit Jev.** Öffnen Sie im FailproofAI Cloud-Dashboard **Keys → Create key** und wählen Sie das **machine**-Preset. Es gewährt die drei Berechtigungen, die eine Maschine benötigt: `events:add` (Aktivität senden), `policies:pull` (Policies empfangen) und `jev:evaluate` (Jev, wird dem Plan Ihrer Organisation belastet). Ein Schlüssel kann `jev:evaluate` nicht ohne die anderen beiden Berechtigungen tragen. +2. **Verbinden Sie die Maschine** mit diesem Schlüssel: + + ```bash + failproofai config --token + ``` + + Falls Ihre Organisation eine eigene FailproofAI Cloud betreibt statt der gehosteten Version, fügen Sie deren Adresse hinzu: `--url https://` (oder exportieren Sie `FAILPROOFAI_CLOUD_URL`). Ohne diese Angabe wird der Schlüssel gegen den gehosteten Dienst geprüft, und die Verbindung schlägt fehl. Wenn das Zertifikat dieses Hosts von einer privaten CA stammt, installieren Sie die CA im System-Trust-Store der Maschine (z. B. mit `update-ca-certificates`) und nicht nur in `NODE_EXTRA_CA_CERTS`: Der Daemon, der Events sendet und Policies abruft, liest den System-Store. Siehe [Troubleshooting](/de/reference/troubleshooting). + +Das ist alles. Beim Verbinden wird der Schlüssel gespeichert, und wenn die Maschine **noch keine** Jev-Konfiguration hat, wird Jev über FailproofAI Cloud im **Shadow**-Modus aktiviert: Jev wird zu jedem überwachten Tool-Aufruf befragt und seine Urteile werden aufgezeichnet, aber das Ergebnis Ihrer Policies ist das, was durchgesetzt wird. Die Ausgabe macht das deutlich: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**Mit `--no-transcripts` aktiviert das Verbinden Jev nicht.** Jev sendet jeden geprüften Tool-Aufruf und den jüngsten Prompt an FailproofAI Cloud – das ist mehr, als eine reine Verbindung für Entscheidungen senden soll. Der Schlüssel wird trotzdem gespeichert, und die Ausgabe teilt mit, dass Jev verfügbar ist und wie man ihn einschaltet: + +```bash +failproofai jev setup --provider failproofai +``` + +Dies schaltet Jev auch **nicht aus**. Läuft Jev auf der Maschine bereits über FailproofAI Cloud per `jev.json`, bleibt dies unverändert, und die Ausgabe informiert darüber, dass Jev weiterhin jeden geprüften Tool-Aufruf und den jüngsten Prompt sendet – und dass `failproofai jev setup --mode off` es deaktiviert. + + +Beim Verbinden wird eine vorhandene `~/.failproofai/jev.json` **niemals überschrieben**. Wenn Sie bereits Ihren eigenen Jev-Endpunkt verwenden, wird dieser weiterhin genutzt, und die Ausgabe teilt mit, dass die Datei unverändert blieb – und, wenn Jev in dieser Datei deaktiviert ist (abgelehnt oder ausgeschaltet), wird das ebenfalls gemeldet samt Hinweis zur Behebung. Um die Maschine auf FailproofAI Cloud umzustellen, führen Sie `failproofai jev setup --provider failproofai` aus. + + +## Shadow, Enforce oder Off + +Starten Sie im Shadow-Modus, beobachten Sie auf der Policy-Seite, was Jev getan hätte, und lassen Sie ihn dann handeln: + +```bash +failproofai jev setup --mode enforce # Jevs Urteile gelten: Er kann ein prüfbares Deny aufheben und eigene hinzufügen +failproofai jev setup --mode shadow # Jev wird befragt und protokolliert; das Ergebnis Ihrer Policies wird durchgesetzt +failproofai jev setup --mode off # Konfiguration behalten, Jev nicht mehr befragen +``` + +Denselben Schalter gibt es im lokalen Dashboard: **Settings → Jev** hat einen Ein/Aus-Schalter und shadow/enforce. Nur der Modus wird überschrieben, sonst nichts. Hooks lesen die Konfiguration bei jedem Tool-Aufruf, sodass eine Änderung ab dem nächsten Aufruf gilt – ohne Neustart. + +## Überprüfen, was passiert + +```bash +failproofai jev status +failproofai jev test +``` + +`status` zeigt den Provider als **FailproofAI Cloud**, den Cloud-Host, mit dem die Maschine verbunden ist, den Modus und die Schlüsselquelle als **FailproofAI Cloud connection** – niemals den Schlüssel selbst. Wenn eine FailproofAI Cloud `jev.json` vorhanden ist, Jev aber nicht laufen kann, wird der Grund angegeben: + +| `status` zeigt | `status --json` | Bedeutung | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | Die Maschine ist verbunden, aber kein Jev-Schlüssel ist für sie gespeichert: Der Schlüssel fehlt `jev:evaluate`, oder die Verbindung konnte es nicht bestätigen. Führen Sie `failproofai config --token ` erneut mit demselben Schlüssel aus; falls ihm die Berechtigung fehlt, verwenden Sie einen **machine**-Schlüssel. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Auf dieser Maschine besteht keine FailproofAI Cloud-Verbindung, der der Jev-Schlüssel gehören könnte. | + +Nach `failproofai config --disconnect` gibt es keine FailproofAI Cloud `jev.json` mehr (es sei denn, sie war ausgeschaltet, was beibehalten wird), sodass `status` Jev einfach als deaktiviert meldet. `status --json` enthält dieselben Fakten (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), auch wenn die Konfiguration fehlt oder abgelehnt wurde. `permissions` bezieht sich immer auf `jev.json`; eine Ablehnung wegen `credentials.json` fügt `credentialsPermissions` hinzu sowie `fix`, wenn ein einzelner Befehl das Problem löst. `test` sendet eine echte Live-Anfrage und meldet die Latenz sowie die Jev-Version, die geantwortet hat. Es gibt 1 zurück und kennzeichnet das in seinem Titel, wenn die Antwort nach dem Hook-Timeout eintrifft (Hooks würden `timeout` aufzeichnen) oder die Prüffrage falsch beantwortet wird. + +Das **Settings → Jev**-Panel im Dashboard zeigt ebenfalls die **FailproofAI Cloud connection**: welcher Organisation die Maschine zugeordnet ist und ob ihr Schlüssel Jev trägt. Es wird aus den lokalen Dateien der Maschine gelesen, ohne Netzwerkanfrage. + +## Was auf der Policy-Seite ankommt + +Die Maschine sendet ihre Hook-Aktivität bereits an FailproofAI Cloud (`events:add`). Mit aktiviertem Jev enthält der Datensatz jedes überwachten Aufrufs außerdem: welcher Evaluator ausgeführt wurde, was Jev entschied, welche Policies er aufhob, warum er ggf. zurückgefallen ist, seine Latenz und das Modell, das geantwortet hat – Entscheidungen, Codes und Namen, niemals den Befehl oder Ihren Prompt. Auf der **Policies**-Seite Ihrer Organisation: + +- Ein Aufruf, der durch Jevs eigenes Urteil entschieden wurde (Enforce-Modus), wird **Jev** zugeschrieben; wenn die ausschlaggebende Prüfung aus einem Pack stammt, nennt der Datensatz auch dieses Pack und seine Version. +- Im Shadow-Modus erscheint Jevs Deny oder Warning als **would-have** neben den Rollouts, die Sie beobachten. +- Die Policies, die Jev aufgehoben hat oder im Shadow-Modus aufgehoben hätte, werden pro Policy gezählt. + +## Wenn Jev nicht antworten kann + +Jeder der folgenden Fälle fällt auf das Ergebnis Ihrer Policies für diesen Aufruf zurück und wird mit seinem Grund aufgezeichnet: + +| Grund | Ursache | +| --- | --- | +| `out-of-credits` | Ihre Organisation hat ihr Plan-Kontingent aufgebraucht. | +| `http-401`, `http-403` | Der Schlüssel wurde widerrufen oder trägt kein `jev:evaluate`. Verbinden Sie sich mit einem Schlüssel, der es tut. | +| `http-429` | FailproofAI Cloud begrenzt Jev für Ihre Organisation. Bis die geforderte Wartezeit abgelaufen ist (`Retry-After`, maximal 60 Sekunden), sendet die Maschine nichts und jeder Aufruf fällt sofort zurück. So zurückgehaltene Aufrufe werden als `http-429` aufgezeichnet oder als `rate-limited`, wenn das eigene Rate-Limit der Maschine sie zuerst zurückhält. | +| `http-429` (Tageslimit) | Ihre Organisation hat ihr tägliches Jev-Kontingent aufgebraucht: **10.000 pro UTC-Tag**, es sei denn, der Betreiber Ihrer FailproofAI Cloud hat ein anderes Limit festgelegt. Jeder Aufruf fällt zurück, bis der Zähler um 00:00 UTC zurückgesetzt wird; die Maschine fragt höchstens einmal pro Minute erneut an, erkennt also den Reset innerhalb einer Minute. `failproofai jev test` meldet: „Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev hat die Anfrage dieses Aufrufs abgelehnt, meist weil der Tool-Aufruf dichten Text (Base64, Hex, minifizierten Code) über Jevs Token-Budget enthielt. Dieser Aufruf fällt jedes Mal zurück; es handelt sich nicht um einen Ausfall. | +| `http-502` | Jev ist momentan nicht verfügbar. | +| `http-503` | Diese Cloud kann Jev für Ihre Organisation nicht bereitstellen: kein Model-Gateway, eine noch nicht provisionierte Organisation oder das Gateway ist ausgefallen. Wenden Sie sich an Ihren Administrator; Hooks fragen höchstens einmal pro Minute erneut an. | +| `http-404` | Diese FailproofAI Cloud stellt Jev noch nicht bereit. | +| `timeout` | Keine Antwort innerhalb von `timeoutMs` (Standard: 3000). | +| `model-mismatch` | Eine andere Jev-Version als 1.13 hat geantwortet. | + +## Wo der Schlüssel gespeichert wird und wohin er geht + +- Der Schlüssel wird einmalig in `~/.failproofai/credentials.json` gespeichert (`0600`, in einem nur für den Eigentümer zugänglichen Verzeichnis), neben den anderen FailproofAI Cloud-Anmeldedaten. `jev.json` enthält für diese Route keinen Schlüssel; ein dort eingetragener Schlüssel macht die Konfiguration ungültig. +- Wenn `credentials.json` für irgendjemanden außer Ihnen **irgendeine** Berechtigung trägt (Gruppe oder andere, Lesen oder Schreiben), oder wenn sein Verzeichnis von irgendjemanden außer Ihnen **beschrieben** werden kann, wird die Datei **abgelehnt**, nicht gelesen, und Jev bleibt deaktiviert, bis Sie das beheben: `chmod 600` auf die Datei, `chmod 700` auf das Verzeichnis (oder erneut verbinden, was die Datei mit `0600` neu schreibt und das Verzeichnis auf den Eigentümer beschränkt). Ein Verzeichnis, das andere nur lesen können, ist in Ordnung; eines, in das andere schreiben können, ermöglicht das Austauschen der Datei. +- Der Schlüssel gilt nur, solange die Verbindung, von der er stammt, auf der Maschine vorhanden ist: eine Policy- oder Reporting-Credential für dieselbe FailproofAI Cloud **mit demselben Schlüssel** in derselben Datei. Ein hinterlassener Jev-Schlüssel ohne eine solche Verbindung wird ignoriert, und Jev bleibt deaktiviert. Das passiert, wenn `config --disconnect` einer älteren failproofai-Version den Jev-Schlüssel stehen lässt (sie weiß nicht, dass er entfernt werden muss), oder wenn `config --token` einer älteren failproofai-Version mit einem anderen Schlüssel verbindet, der auf FailproofAI Cloud zu einer anderen Organisation gehören kann. Um Jev wieder einzuschalten, verbinden Sie sich erneut mit einem **machine**-Schlüssel. +- Der Schlüssel wird ausschließlich an den Cloud-Ursprung gesendet, gegen den er verifiziert wurde. Eine `jev.json`, die auf einen anderen Ort verweist, wird abgelehnt. +- **Ein Agent auf der Maschine kann sie lesen.** `credentials.json` ist nur für den Eigentümer zugänglich, und der Agent läuft als dieser Eigentümer. Das Lesen von failproofais eigenen Dateien ist bewusst erlaubt (nur das Ändern ist blockiert, durch `block-failproofai-commands`); das Einzige, was zwischen einem Agent und dieser Datei steht, ist `block-read-outside-cwd` – eine *prüfbare* Policy – und von einer Sitzung, die im Home-Verzeichnis gestartet wurde, nichts. Ein Schlüssel mit `jev:evaluate` verbraucht das Jev-Kontingent Ihrer Organisation (bis zur Tagesobergrenze) von überall, wo er verwendet wird. Behandeln Sie einen Machine-Schlüssel daher wie jede andere Spending-Credential: Wenn ein Agent ihn möglicherweise gelesen hat, deaktivieren Sie ihn auf der Keys-Seite und verbinden Sie sich mit einem neuen. +- Nur Ihre globalen Dateien entscheiden das. Ein Repository kann Cloud-Jev nicht einschalten, auf einen anderen Ort verweisen oder seinen Schlüssel bereitstellen, und `FAILPROOFAI_JEV_API_KEY` wird für diese Route ignoriert. +- Für jeden von Jev bewerteten Aufruf geht eine Anfrage an FailproofAI Cloud, die das enthält, was die [Bring-your-own-key-Seite](/de/policies/jev-byok#what-leaves-the-machine) auflistet (Secrets werden geschwärzt). FailproofAI Cloud leitet es an TypeSafe weiter und protokolliert oder speichert es nicht. + +## Deaktivierung + +| Befehl | Ergebnis | +| --- | --- | +| `failproofai jev setup --mode off` | Konfiguration behalten; Jev wird nicht befragt. **Dies ist der dauerhaft wirksame Schalter:** Erneutes Verbinden überschreibt eine vorhandene `jev.json` nie, sodass Jev deaktiviert bleibt, bis Sie es mit `--mode shadow` wieder einschalten. | +| `failproofai jev remove` | `~/.failproofai/jev.json` löschen; Jev ist deaktiviert – bis zum nächsten `failproofai config --token` mit einem Schlüssel, der `jev:evaluate` trägt. Dieser findet keine `jev.json` und aktiviert Jev erneut im Shadow-Modus (es sei denn, er wird mit `--no-transcripts` ausgeführt). Um es deaktiviert zu lassen, verwenden Sie `--mode off`. | +| `failproofai config --disconnect` | Verbindung der Maschine trennen: Der Schlüssel wird entfernt, ebenso `jev.json`, wenn sie FailproofAI Cloud benennt und nicht ausgeschaltet ist. Eine `jev.json` für Ihren eigenen Endpunkt bleibt bestehen, ebenso eine ausgeschaltete – sodass Jev deaktiviert bleibt, wenn Sie sich erneut verbinden. | + +Ab dem nächsten Tool-Aufruf führen Hooks die Regex-Policies exakt wie zuvor aus. \ No newline at end of file diff --git a/docs/de/policies/jev.mdx b/docs/de/policies/jev.mdx new file mode 100644 index 000000000..8c6b6198a --- /dev/null +++ b/docs/de/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Füge Jevs Live-Überprüfung zu gesperrten Tool-Aufrufen hinzu und inspiziere sie, bevor die Entscheidungen durchgesetzt werden." +icon: "shield-check" +--- + +Jev liest einen Tool-Aufruf im Kontext dessen, was die Person den Agenten zu tun gebeten hat. Verwende es, wenn eine auf Zeichenkettenabgleich basierende Policy valide Arbeit blockiert oder eine riskante Aktion übersieht, die Kontext erfordert. Es antwortet zusammen mit deinen Policies am `PreToolUse`- oder `PermissionRequest`-Gate. Für eine Bewertung **nach** dem Ende einer Sitzung verwende [Jev evaluations](/de/evaluations/jev). + +## Im Beobachtungsmodus starten + +Installiere Failproof AI und hänge Hooks an ein [unterstütztes Harness](/de/reference/harnesses) an. Verwende failproofai 1.0.8-beta.0 oder neuer. + +Failproof AI enthält keine Jev-Prüfungen. Installiere sie als Pack, sonst hat Jev nichts zu überprüfen und wird nie aufgerufen: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Wähle dann, wie Anfragen Jev erreichen: + +| Route | Erster Schritt | +| --- | --- | +| FailproofAI Cloud | Verbinde dich mit einem **Machine**-Key, der `jev:evaluate` besitzt. Auf einer Maschine ohne Jev-Konfiguration schaltet `failproofai config` Jev im Beobachtungsmodus ein. | +| Eigener Anbieter | Öffne im lokalen Dashboard **Settings → Jev**, wähle den Anbieter, füge dessen Token ein und wähle **observe**. Oder führe `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key` aus. | + +![Die Jev-Einstellungen des lokalen Dashboards: Anbieter, Endpunkt, Token und Beobachtungsmodus, bevor Jev aktiviert wird.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` prüft den Endpunkt. Um den Hook-Pfad zu überprüfen, bitte einen mit Hooks versehenen Agenten, sein Dateilesewerkzeug auf `README.md` anzuwenden. Bestätige, dass dieser Tool-Aufruf in der Sitzung erscheint, und inspiziere dann **Policies → Activity** im [lokalen Dashboard](/de/reference/local-dashboard#review-policy-activity). Der Jev-Zähler in `status` sollte sich erhöhen. Der Beobachtungsmodus zeichnet auf, wie Jev entschieden hätte, während dein bestehendes Policy-Ergebnis weiterhin gilt. + +## Entscheiden, wann durchgesetzt wird + +Eine **harte** Policy hat immer das letzte Wort. Jev kann ein Deny nur von einer Policy aufheben, die explizit als **reviewable** markiert ist, und nur wenn es das benannte Anliegen dieser Policy geprüft hat. Lies [policy authority](/de/policies/authority), bevor du dich auf eine Freigabe verlässt. Jev kann auch eigenständig warnen oder ablehnen. Kann es nicht antworten, entscheidet das Policy-Ergebnis über diesen Aufruf. + +Sobald die Beobachtungsergebnisse korrekt aussehen, wechsle in **Settings → Jev** in den Durchsetzungsmodus oder führe aus: + +```bash +failproofai jev setup --mode enforce +``` + +Informationen zu Anbieter-URLs, Cloud-Keys, Konfiguration, Fallbacks und den mit jeder Anfrage gesendeten Daten findest du in der [Jev-Integrationsreferenz](/de/reference/jev). \ No newline at end of file diff --git a/docs/de/reference/custom-agents-typescript.mdx b/docs/de/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..1d2522bf2 --- /dev/null +++ b/docs/de/reference/custom-agents-typescript.mdx @@ -0,0 +1,433 @@ +--- +title: "Eigene Agenten (TypeScript)" +description: "Konfiguration, der Event-Katalog, die Scopes und die Framework-Adapter für @failproofai/sdk." +icon: "square-js" +--- + +Beschreibung jeder Einstellung, Methode und jedes Felds im TypeScript-SDK. Wenn Sie zum ersten Mal instrumentieren, beginnen Sie mit der Anleitung — diese Seite dient als Nachschlagewerk. + + + + Installation, Instrumentierung, die Event-Methoden, ein ausgearbeitetes Beispiel und häufige Probleme. + + + Dieselben Events, dasselbe Wire-Format, derselbe Spool — aus Python. + + + +Node 20.9 oder neuer. ESM und CommonJS. Keine Runtime-Abhängigkeiten. + + + Dieses SDK und das Python-SDK schreiben **dieselben Events in denselben Spool**. Eine Flotte mit Node-Agenten und Python-Agenten erzeugt einen einzigen Satz von Sessions, nicht zwei, und das Dashboard unterscheidet sie nicht. Wählen Sie pro Service, nicht pro Unternehmen. + + +## Installation + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Die Framework-Adapter sind im Paket selbst enthalten. Die Frameworks sind **optionale Peer-Abhängigkeiten** — deklariert, damit die unterstützten Versionen sichtbar sind, werden nie in Ihrem Namen installiert und nur beim Aufruf von `instrument()` importiert. + +## Failproof-Daemon verbinden + +Identisch mit dem Python-SDK: Erstellen Sie einen `events:add`-Schlüssel unter **Admin → Keys**, und [verbinden Sie dann den Daemon](/de/start/setup#connect-a-machine-to-cloud) auf dem Agenten-Rechner. Das SDK schreibt auf Disk; der Daemon sendet die Daten. + +## Konfiguration + +### OpenTelemetry-Spans (opt-in) + +Installieren Sie OpenTelemetry separat mit `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Fügen Sie dann FailproofAI zu den Prozessoren Ihres Providers hinzu: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Für einen bestehenden Provider behalten Sie dessen andere Prozessoren in derselben Liste. Provider, +die `addSpanProcessor` anbieten, können stattdessen als `{ provider }` übergeben werden. Ohne +Optionen registriert die Einrichtung nur dann einen neuen Provider, wenn noch kein Provider registriert ist. +`OtelSpanExporter` kann auch direkt mit Ihrem eigenen Prozessor verwendet werden. + +Exporte laufen über den verbundenen FailproofAI-Daemon; das SDK sendet keine Netzwerkanfragen +und benötigt weder einen Schlüssel noch einen lokalen Listener. Bitten Sie einen Administrator, +[OpenTelemetry-Ingest](/de/agenteye/opentelemetry) zu aktivieren. Ein einfaches `instrument()` aktiviert +diesen Exporter nicht. `uninstrument("otel")` deaktiviert nur seinen eigenen Prozessor. +Ihre Span-Attribute steuern die Inhaltserfassung; leeren Sie Ihren Provider vor dem Beenden. +OpenTelemetry bleibt eine optionale Anwendungsabhängigkeit, keine feste SDK-Abhängigkeit. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Option | Funktion | +| --- | --- | +| `environment` | Das Label für jeden Event — `production`, `staging`, `prod-eu`. Standard: `dev`. | +| `flushInterval` | Wie oft der Timer auf Disk schreibt, in Sekunden. Standard: `0.5`. | +| `baseDir` | Wohin geschrieben wird. Standardmäßig der Spool des Daemons, was in der Regel gewünscht ist. | + +Nichts wird angewendet, solange nicht alles validiert ist. Ein abgelehnter Aufruf lässt das SDK genau so, wie es war, anstatt einen neuen `baseDir` mit dem alten Intervall zu kombinieren. + +Stattdessen per Umgebungsvariable setzen: + +| Variable | Funktion | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Setzt `environment` ohne Codeänderung. Eine `configure()`-Option hat Vorrang. | +| `FAILPROOFAI_HOME` | Verschiebt das Failproof AI-Stammverzeichnis, das den Spool enthält. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (Standard), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` lässt Instrumentierungsfehler werfen, statt sie zu protokollieren. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` lässt ein Framework-Kompatibilitätsproblem werfen, statt zu warnen und fortzufahren. | + + + **Kein Komma in `environment`.** Der Ingest teilt dieses Feld an Kommas auf, um seine Filter zu erstellen, und überspringt jeden Event, dessen Label eines enthält — ein ganzer Durchlauf verschwindet lautlos. Schreiben Sie `prod-eu`, nicht `prod,eu`. + + `configure({ environment: "prod,eu" })` wirft einen Fehler, damit Sie es sofort bemerken. `AGENTEYE_ENVIRONMENT` kann nicht werfen — nichts ruft Sie auf — daher wird einmal gewarnt und auf `dev` zurückgefallen. + + +Leiten Sie die eigenen Log-Zeilen des SDK mit `failproofai.setLogger({ debug, info, warn, error })` in Ihren Logger. + +## Herunterfahren + +Gepufferte Events werden bei `process.on("exit")` geleert. + +Ein durch ein Signal beendeter Prozess erreicht das niemals, und Nodes Standard für `SIGTERM` ist, ohne Ausführung der Exit-Handler zu beenden — ein containerisierter Agent verliert also alles, was das letzte Intervall noch nicht geschrieben hat. + + + **Dieses SDK installiert keinen Signal-Handler für Sie.** Das Registrieren eines solchen ändert das Verhalten Ihres Prozesses: Ein Listener unterdrückt Nodes Standard-Terminierung, sodass eine Bibliothek, die einen hinzufügt, Ctrl-C lautlos deaktivieren würde. Fügen Sie Ihren eigenen hinzu: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Ein kurzlebiges Skript oder ein serverloser Handler sollte `await failproofai.flush()` vor der Rückgabe aufrufen — das Intervall allein garantiert keine Zustellung. + +## Identität + +Jeder Event gehört zu einer Session und einem Agenten. **Die Scopes füllen beides aus**, daher müssen Sie sie selten übergeben: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Die explizite Übergabe von `sessionId` oder `agentId` funktioniert weiterhin und hat Vorrang. Ist weder gebunden noch übergeben, wirft der Aufruf einen Fehler, anstatt einen Event auszusenden, den Cloud stillschweigend verwerfen würde. + + + Identität wird über `AsyncLocalStorage` übertragen. Sie folgt `await`, `.then()`, Timern und jedem Callback, der innerhalb des Scopes erstellt wird. Sie folgt **nicht** einem Callback, der während eines Durchlaufs gespeichert und während eines anderen aufgerufen wird, oder Arbeit, die über eine `worker_threads`-Grenze übergeben wird — umschließen Sie diese mit `failproofai.propagate()`, oder ihre Events werden nicht zugeordnet. + + +### Scopes + +| Scope | Sendet | Gibt zurück | +| --- | --- | --- | +| `session(body)` | nichts — nur Identität | was auch immer `body` zurückgibt | +| `agent(id, options?, body)` | `agent_start`, dann `agent_end` | was auch immer `body` zurückgibt | +| `toolCall(name, options?, body)` | `tool_use`, dann `tool_result` | was auch immer `body` zurückgibt | + +Ein synchroner Body bleibt synchron: `agent("x", () => 1)` gibt `1` zurück, kein Promise. + +`toolCall` zeichnet den aufgelösten Wert des Bodys als `output` des Tools auf, sofern Sie `call.output` nicht selbst zuweisen. + + + +| Was geschah | Events | `outcome` | +| --- | --- | --- | +| Der Block hat zurückgegeben | `agent_end` | `"success"`, oder Ihr `outcome` | +| Der Block hat geworfen | `error`, dann `agent_end` | `"failed"` | +| Ein `AbortError` | nur `agent_end` | `"cancelled"` | + +Der Fehler wird immer erneut geworfen. + +Ein Tool-Fehler wird auf dem Blatt aufgezeichnet — `tool_result` mit einem `error`-String — und sendet **keinen** Lauf-Level-`error`-Event. Einer, den die Agentenschleife abfängt, ist kein Laufversagen, und einer, der sich fortsetzt, wird genau einmal vom umschließenden `agent()` gemeldet. + + + + + +Wenn die Arbeit keine einzelne Funktion ist — ein Scope, der in einem Konstruktor geöffnet und in einem Teardown geschlossen wird, oder einer, der vorhandenen Kontrollfluss überspannt: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +Beide Formen senden byteidentische Events. Bevorzugen Sie die Callback-Form: Sie läuft innerhalb von `AsyncLocalStorage.run()`, sodass nichts abzuwickeln ist und die gesamte Klasse von „hier geöffnet, dort geschlossen"-Fehlern nicht erreichbar ist. + +Ein `using`-Block, der seinen eigenen Fehler abfängt, meldet ihn mit `span.fail(error)` — der Disposer hat keinen eigenen Exception-Kanal. + + + +## Event-Katalog + +Dieselben fünfzehn Methoden wie das Python-SDK, in camelCase. Die meisten kommen in **Paaren** — Sie rufen den Öffner auf, dann den Schließer, und das SDK misst die Zeitdifferenz. + +| | Öffnet | Schließt | +| --- | --- | --- | +| **Agenten** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Modelle** | `modelRequest` | `modelResponse` | +| **Tools** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Menschen** | `humanWait` | `humanInput` | + +Drei stehen allein: `error`, `humanPause`, `humanInterrupt`. + + + +Jede Methode akzeptiert auch `sessionId` und `agentId`, die die Scopes für Sie ausfüllen. Alles Weggelassene wird verworfen, anstatt als JSON `null` gesendet zu werden. + +| Methode | Erforderlich | Optional | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Jeder weitere Schlüssel, den Sie hinzufügen, wird zu einem benutzerdefinierten Payload-Feld. Vergeben Sie für framework-spezifische Bezeichnungen den Namensraum `fw_*`; ein Name, der mit einem deklarierten Feld kollidiert, wird abgelehnt, anstatt eine hochgestufte Spalte stillschweigend zu überschreiben. + + + + + **`duration_ms` wird berechnet, nicht akzeptiert.** Die vier schließenden Methoden messen die Zeitdifferenz ab dem Öffner und lehnen ein vom Aufrufer angegebenes `duration_ms` ab — eine gemeldete Dauer ist unveränderlich. + + Paare werden anhand der **Session** und der ID abgeglichen, niemals anhand des Agenten. Ein Tool, das unter `planner` geöffnet und unter `worker` geschlossen wird, bildet trotzdem ein Paar — genau das tun verschachtelte Multi-Agenten-Läufe. + + +## Framework-Adapter + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| Framework | Unterstützt | Wie es sich einbindet | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, sodass jedes `invoke`/`stream`/`batch` abgedeckt ist, ohne `callbacks:` irgendwo zu übergeben — oder übergeben Sie `langchainHandler()` selbst und patchen Sie nichts. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` an der Aufrufstelle, oder `instrument("ai")` für den gesamten Prozess auf `ai` 7 (auf 4–6 ist das opt-in — siehe unten). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, die Modell- und Tool-Auflösung des Agenten sowie die Workflow-Lauf/Schritt-Engine. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (abonniert) plus `AgentWorkflow.runStream`, für Workflow-Läufe und deren Schritte. | + +Jeder Versionsbereich wird gegen echte Framework-Releases getestet, an beiden Enden, als ES-Modul und als CommonJS, bei jedem CI-Lauf. + +Das Mapping entspricht dem des Python-SDK, sodass dasselbe Programm in beiden Sprachen denselben Baum zeichnet. Ein Konstrukt ist nur dann ein **Agent**, wenn es eine eigene LLM-Entscheidungsschleife besitzt — ein Graph- oder Chain-Lauf, ein AI SDK `generateText`/`streamText`-Aufruf, ein Mastra-Agent, ein LlamaIndex-Agentenlauf. Ein LangGraph-Knoten oder ein Workflow-Schritt ist ein **Hook** (`hook_triggered`/`hook_completed`), niemals ein verschachtelter Agent. Modellaufrufe sind `model_request`/`model_response`-Paare mit Token-Zählungen; Tool-Aufrufe tragen die eigene Tool-Call-ID des Modells. Ein Fehler wird einmal aufgezeichnet, bei dem Event, in dem er aufgetreten ist. + +Ein Adapter, der sich nicht installieren lässt, wird protokolliert und übersprungen; die anderen werden trotzdem installiert, denn ein defektes LlamaIndex soll Sie nicht LangGraph kosten. + + + `instrument()` ohne Argument erkennt ein Framework daran, ob es sich **auflösen** lässt, nicht daran, ob es bereits importiert ist — Node bietet kein Äquivalent zu Pythons `sys.modules` für ES-Module. Ein Framework, das Sie installiert, aber nicht verwenden, wird importiert und gepatcht. Benennen Sie das gewünschte Framework explizit, wenn das relevant ist. + + + + Die meisten dieser Frameworks liefern sowohl einen ES-Modul-Build als auch einen CommonJS-Build, die Node als zwei unabhängige Kopien lädt. Die Adapter patchen die Kopie, die Ihre Anwendung lädt (und auch die CommonJS-Kopie, falls etwas sie bereits via `require` geladen hat), sodass beide Modulsysteme funktionieren. Ein Framework, das von esbuild oder webpack **in Ihre eigene Ausgabe gebündelt** wurde, ist nicht erreichbar — verwenden Sie dort die Aufrufstellen-Helfer: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain ohne Patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +Der Handler funktioniert mit oder ohne `instrument()` und zeichnet nie doppelt auf. `instrument("langchain")` akzeptiert `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` und `captureLimit`, wie der Python-Adapter; `metadata: { failproofai_sdk_session_id }` bei einem Aufruf wählt die Session für diese Ausführung. + +### Vercel AI SDK + +Das AI SDK exportiert einfache Funktionen aus einem ES-Modul, und ein ES-Modul-Namensraum ist spezifikationsgemäß unveränderlich — es gibt keinen Ort zum Patchen. Es verwendet die Erweiterungspunkte, die das SDK selbst dokumentiert: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +Das ist die vollständige Integration: ein Agenten-Span, ein Modell-Request/Response-Paar pro Schritt mit Token-Zählungen und jeder Tool-Aufruf. Eine Aufrufstelle funktioniert auf jeder Major-Version — `ai` 4–6 liest den mitgelieferten Tracer, `ai` 7 die Telemetrie-Integration. + +`instrument("ai")` tut dasselbe prozessweit **auf `ai` 7**: jeden Aufruf, über die globale Telemetrie-Integrationsliste des AI SDK, die additiv ist und niemandem anderen etwas wegnimmt. + +**Auf `ai` 4–6 zeichnet `instrument("ai")` alleine nichts auf und protokolliert eine Warnung.** Der einzige prozessweite Hook dieser Major-Versionen ist der globale OpenTelemetry-Tracer-Provider — ein einzelner Slot, den OpenTelemetry nach einmaliger Belegung nicht mehr freigibt. Die Registrierung unseres eigenen würde Ihr späteres `NodeSDK.start()` beim Start lautlos ablehnen und Ihre http/Datenbankspans an einen Tracer senden, der nichts exportiert. Verwenden Sie `telemetry()` an der Aufrufstelle oder dort `wrapModel`. Falls der Prozess kein eigenes OpenTelemetry betreibt, aktivieren Sie es mit `instrument("ai", { registerGlobalTracer: true })`: Es zeichnet dann jeden Aufruf auf, der `experimental_telemetry: { isEnabled: true }` übergibt, und belegt den Slot nur, wenn er noch frei ist. `registerGlobalTracer: false` behält den Standard bei und unterdrückt die Warnung. + +Wenn Sie das Modell lieber einmalig umschließen möchten, sieht `wrapModel` nur Modellaufrufe, da Tool-Aufrufe oberhalb der Modellebene stattfinden. Ein umschlossenes Modell, das ohne Umgebung aufgerufen wird, wird als eigener Lauf aufgezeichnet. Ein gestreamter Aufruf schließt, wie auch immer der Stream endet — `stop_reason: "cancelled"`, wenn der Konsument ihn abbricht, `"error"` mit dem Fehler, wenn er auf halbem Weg scheitert: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Beides gleichzeitig zu verwenden ist in Ordnung: Die Middleware erkennt, dass der Aufruf bereits aufgezeichnet wird, und verzichtet, sodass jeder Aufruf genau einmal aufgezeichnet wird. + +`functionId` benennt den Agenten-Span. Halten Sie die Kardinalität niedrig — er landet in `agent_id`, der primären Dashboard-Facette. + +### Next.js + +`next build` bündelt standardmäßig die Abhängigkeiten Ihres Servers, und ein in den Build gebündeltes Framework ist eine Kopie, die `instrument()` nicht erreichen kann. Umschließen Sie die Konfiguration einmalig und rufen Sie `instrument()` über Nexts Startup-Hook auf: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` fügt LangChain, Mastra, LlamaIndex und das SDK selbst zu `serverExternalPackages` hinzu und behält Ihre eigene Liste. Ohne es warnt `instrument()` einmal pro nicht erreichbarem Framework, anstatt lautlos zu versagen; wenn Sie die Pakete selbst auflisten, setzen Sie `FAILPROOFAI_NEXT_EXTERNALS=1`. Das Vercel AI SDK und die Aufrufstellen-Helfer funktionieren in jedem Fall. Eine Edge-Route erhält einen No-op-Build: Das Importieren des SDK ist sicher und zeichnet nichts auf. + +### Token-Zählungen bei gestreamten Aufrufen + +OpenAI-kompatible APIs melden die Nutzung bei einem Stream nur, wenn der Client danach fragt. LangChain und das Vercel AI SDK fragen; für LlamaIndex übergeben Sie `additionalChatOptions: { stream_options: { include_usage: true } }` an sein `OpenAI`-LLM, und für Mastra erstellen Sie das Modell mit aktivierter Nutzungserfassung (zum Beispiel `createOpenAICompatible({ includeUsage: true })`). Andernfalls tragen gestreamte Modellaufrufe keine Token-Zählungen. + +### Laufzeitumgebungen + +Node ≥ 20.9, Bun und Deno — jedes Framework, als ES-Modul und als CommonJS, wird auf jedem gegen Nodes Trace getestet. Das SDK läuft neben dem `failproofaid`-Daemon, der die Schreibdaten versendet. + +## Eigener Agent — kein Framework + +Für eine selbst geschriebene Agentenschleife oder ein Framework ohne Adapter. Sie senden die Events mit derselben API, die die Adapter darunter verwenden, sodass der Trace dieselbe Form und Qualität hat. + +Sie müssen die Struktur des Agenten nicht kennen. Jeder handgebaute Agent hat bereits drei Stellen, unabhängig davon, wie seine Funktionen heißen, und diese drei bilden die gesamte Integration: + +| Wo | Was hinzufügen | Sendet | +| --- | --- | --- | +| Wo **ein Lauf** beginnt und endet | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| Die **eine Funktion, die das Modell aufruft** | `event.modelRequest` davor, `event.modelResponse` danach — beide Hälften, auch bei Fehler | ein Paar pro Modell-Turn | +| Die **eine Funktion, die Tools ausführt** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +Identität ist ambient: Alles innerhalb von `agent()` landet in der Session dieses Laufs, ohne eine ID anzugeben, und nichts anderes im Programm ändert sich — einschließlich dessen, was der Agent bereits in seine eigene Datenbank schreibt. + +- **Ein Service oder ein Worker:** Übergeben Sie Ihre eigene Request- oder Job-ID als `sessionId`, damit eine Session im Dashboard und der Datensatz in Ihren eigenen Logs oder in der Datenbank denselben String haben. +- **Sub-Agenten:** Verschachteln Sie `agent()`-Aufrufe. Der innere tritt der Session mit dem äußeren als dessen `parent_id` bei. +- **Paare senden.** Ein `modelRequest` ohne `modelResponse` ist ein Span, den das Dashboard als ewig laufend anzeigt — daher der `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) im Repository ist die vollständige, ausführbare Version: eine echte OpenAI-Tool-Schleife, genau so instrumentiert, bei jedem Commit als ES-Modul und als CommonJS in CI ausgeführt. + +## Auswertungen + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Weitere Informationen zum Protokoll, den Worker-Einstellungen und den Ergebnistypen finden Sie in der [Evaluator SDK-Referenz](/de/reference/evaluator-sdk). + + + **Eine Auswertung muss zurückgeben.** Eine synchrone Funktion, die nie zurückgibt, blockiert den einzigen Thread, den Node hat, und kein Timeout kann feuern, solange sie das tut. Schreiben Sie `async`-Auswertungen. + + +## Was es Ihrem Prozess nicht antut + +| | | +| --- | --- | +| **Ihre Agentenschleife blockieren** | Events werden in eine In-Memory-Warteschlange geschrieben; ein Timer schreibt sie. Der Timer ist `unref`t, sodass das Importieren dieses Pakets das Beenden eines Skripts nie verhindert. | +| **Unbegrenzt wachsen** | Die Warteschlange ist sowohl nach Anzahl *als auch* nach gemessenen Bytes begrenzt. Ist eines davon überschritten, werden die ältesten Events verworfen und eine Warnung ausgegeben — ein Telemetrie-Ausfall darf kein OOM-Kill werden. | +| **Den Prozess beenden** | Ein nicht kodierbarer Event wird einzeln verworfen, nicht der Batch um ihn herum. Ein werfender Getter, eine zirkuläre Referenz, ein `BigInt`, ein einzelnes Surrogate: Jedes wird behandelt, anstatt weitergegeben zu werden. | +| **Einen halb geschriebenen Batch hinterlassen** | Inhalte werden mit `fsync` gesichert, bevor eine atomare Umbenennung erfolgt, das Verzeichnis wird danach mit `fsync` gesichert, und ein fehlgeschlagener Schreibvorgang bereinigt seine temporäre Datei. | +| **Transkripte lesbar lassen** | Batches haben `0600`-Rechte innerhalb eines `0700`-Verzeichnisses. Sie enthalten Ziele, Prompts, Tool-Argumente und Tool-Ausgaben. | +| **Zugangsdaten versenden** | API-Schlüssel, Tokens, JWTs, Bearer-Header und secret-förmige Zuweisungen werden geschwärzt, bevor die Bytes die Disk erreichen. Der Daemon schwärzt erneut vor dem Upload. | \ No newline at end of file diff --git a/docs/de/reference/custom-agents.mdx b/docs/de/reference/custom-agents.mdx index 99b197f96..9751b4928 100644 --- a/docs/de/reference/custom-agents.mdx +++ b/docs/de/reference/custom-agents.mdx @@ -15,7 +15,7 @@ Was jede Einstellung, Methode und jedes Feld bewirkt. Wenn Sie zum ersten Mal in -Python 3.10 oder neuer. Keine Laufzeitabhängigkeiten. +Python 3.11 oder neuer. Keine Laufzeitabhängigkeiten. ## Installation diff --git a/docs/de/reference/jev-cloud.mdx b/docs/de/reference/jev-cloud.mdx new file mode 100644 index 000000000..5a5d091f1 --- /dev/null +++ b/docs/de/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev über FailproofAI Cloud" +description: "Cloud-Machine-Keys, Verbindungsstatus, Limits und Fehlerverhalten für die Live-Jev-Richtlinienprüfung." +icon: "cloud" +--- + +Dies ist die Cloud-Routenreferenz für [Jev-Richtlinien](/de/policies/jev). Jev, TypeSafes Classifier, liest jeden Tool-Aufruf gegen das, was Sie tatsächlich angefragt haben, und antwortet neben Ihren Richtlinien – niemals anstelle von ihnen. Über **FailproofAI Cloud** verwendet eine verbundene Maschine Jev mit demselben Key, mit dem sie bereits verbunden ist: kein TypeSafe-Konto, kein zweiter Key, kein Endpoint zum Konfigurieren. Jeder Aufruf wird dem bestehenden Plan-Kontingent Ihrer Organisation angerechnet. + +Alles, was Jev tut, ist gegenüber dem [Bring-your-own-key-Setup](/de/reference/jev-providers) unverändert: Harte Richtlinien bleiben endgültig, das Deny einer überprüfbaren Richtlinie wird nur dann aufgehoben, wenn Jev genau zu diesem Anliegen befragt wurde, und jeder Fehler fällt auf das Regex-Ergebnis für diesen Aufruf zurück. + + +Erfordert **failproofai 1.0.8-beta.0** oder höher. 1.0.7 hat kein Jev, auch wenn es in der Sortierung über den 1.0.7-Betas erscheint. Ohne eine Jev-Konfiguration ändert sich nichts: Hooks führen die Regex-Richtlinien genau wie bisher aus. + + +## Vor dem Start + +Installieren Sie Failproof AI auf der Maschine, auf der Ihr Agent läuft, und hängen Sie dessen Hooks an einen [unterstützten Harness](/de/reference/harnesses). Wenn Sie von Grund auf neu starten, folgen Sie dem [Quickstart](/de/start/quickstart) bis zur Hook-Installation. Prüfen Sie die installierte CLI mit `failproofai --version`; aktualisieren Sie sie, wenn sie älter als Jev ist. Sie benötigen außerdem Zugriff auf die Seite **Administration → Keys** Ihrer Organisation, um einen Machine-Key zu erstellen. + +Jev überprüft benannte Tool-Aufrufe am `PreToolUse`- oder `PermissionRequest`-Gate. Es überprüft nicht jedes Ereignis in einer Sitzung. Um zu sehen, wie Jev ein Richtlinien-Deny aufhebt, benötigen Sie eine installierte Richtlinie, die als [reviewable](/de/policies/authority) markiert ist; alle anderen Richtlinien-Denys bleiben endgültig. + +## Aktivierung + +1. **Erstellen Sie einen Key mit Jev.** Öffnen Sie im FailproofAI Cloud-Dashboard **Administration → Keys → Key erstellen** und wählen Sie das **machine**-Preset. Es gewährt die drei Berechtigungen, die eine Maschine benötigt: `events:add` (Aktivität senden), `policies:pull` (Richtlinien empfangen) und `jev:evaluate` (Jev, dem Plan Ihrer Organisation angerechnet). Ein Key kann `jev:evaluate` nicht ohne die anderen beiden tragen. +2. **Verbinden Sie die Maschine** mit diesem Key. Lesen Sie sein einmaliges Secret an einer Eingabeaufforderung, dann führen Sie den vollständigen Setup-Befehl aus: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` installiert den Daemon, hängt Hooks für die gefundenen Agent-CLIs an und verbindet die Maschine. Die Umgebungsvariable hält den Key aus den Befehlsargumenten und Ihrem Shell-Verlauf heraus. Wenn Ihr Harness später installiert wurde, [hängen Sie ihn explizit an](/de/start/quickstart). + + Wenn Ihre Organisation ihre eigene FailproofAI Cloud anstelle des gehosteten Dienstes betreibt, fügen Sie deren Adresse hinzu: `--url https://` (oder exportieren Sie `FAILPROOFAI_CLOUD_URL`). Ohne sie wird der Key gegen den gehosteten Dienst geprüft und die Verbindung schlägt fehl. Wenn das Zertifikat dieses Hosts von einer privaten CA stammt, installieren Sie die CA im System-Truststore der Maschine (z. B. mit `update-ca-certificates`), nicht nur in `NODE_EXTRA_CA_CERTS`: Der Daemon, der Ereignisse sendet und Richtlinien abruft, liest den System-Truststore. Siehe [Troubleshooting](/de/reference/troubleshooting). + +Das ist alles. Die Verbindung speichert den Key und, wenn die Maschine noch **keine** Jev-Konfiguration hat, schreibt sie eine für FailproofAI Cloud. Ab dem ersten Deployment der Maschine (innerhalb von ca. 30 s) legt FailproofAI Cloud den Modus fest: `enforce`, solange eine Jev-Richtlinie auf ihr deployed ist, `off`, wenn keine vorhanden ist (siehe [Wer den Modus festlegt](#wer-den-modus-festlegt)). Die Ausgabe zeigt dies an: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Prüfungen, die FailproofAI Cloud deployed, laufen auf Cloud. Um eigene Prüfungen auf der Maschine hinzuzufügen, installieren Sie ein Pack: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**Mit `--no-transcripts` schaltet die Verbindung Jev nicht ein.** Jev sendet jeden geprüften Tool-Aufruf und die aktuelle Eingabeaufforderung an FailproofAI Cloud, was mehr ist, als eine Verbindung, die nur Entscheidungen sendet, gefragt ist zu senden. Der Key wird dennoch gespeichert, und die Ausgabe zeigt an, dass Jev verfügbar ist und wie man es einschaltet: + +```bash +failproofai jev setup --provider failproofai +``` + +Es schaltet Jev über FailproofAI Cloud auch **aus**. Eine `jev.json`, die Jev über FailproofAI Cloud ausführt (hinterlassen von einer früheren Verbindung mit aktivierten Transkripten), wird nach derselben Regel entfernt, die `config --disconnect` verwendet, und die Ausgabe zeigt an, dass Jev über FailproofAI Cloud auf dieser Maschine deaktiviert bleibt. Eine `jev.json` für Ihren eigenen Jev-Endpoint bleibt unverändert, ebenso eine FailproofAI Cloud-Konfiguration, die Sie deaktiviert haben (`--mode off`). + + +Beim Verbinden wird eine vorhandene `~/.failproofai/jev.json` **niemals überschrieben**. Wenn Sie bereits Ihren eigenen Jev-Endpoint verwenden, wird dieser weiterhin verwendet, und die Ausgabe zeigt an, dass die Datei so belassen wurde, wie sie konfiguriert ist — und wenn diese Datei Jev deaktiviert lässt (verweigert oder ausgeschaltet), wird dies und die Behebung angezeigt. Um diese Maschine auf FailproofAI Cloud umzustellen, führen Sie `failproofai jev setup --provider failproofai` aus. + + +## Wer den Modus festlegt + +Auf einer mit FailproofAI Cloud verbundenen Maschine **legt FailproofAI Cloud den Jev-Modus fest**; nichts auf der Maschine selbst tut dies: + +- `enforce`, solange eine Jev- (oder Regex + Jev-)Richtlinie auf der Maschine deployed ist: Jeder geprüfte Tool-Aufruf eines Agents, auf den eine dieser Richtlinien zielt, wird an FailproofAI Cloud gesendet, das seine Prüfungen zusammen mit den Prüfungen der dort installierten Packs durchführt. Ein Aufruf eines Agents, auf den keine Cloud-Jev-Richtlinie zielt und der keine eigene Pack-Prüfung hat, wird überhaupt nicht gesendet. Im `enforce`-Modus blockieren Jevs eigene Deny-Prüfungen Aufrufe und heben auch die Regex-Urteile auf, die sie überprüfen. +- `off`, wenn keine vorhanden ist: kein Jev, unabhängig davon, was `jev.json` angibt. + +Um eine Jev-Richtlinie zu testen, bevor sie wirkt, deployen Sie sie mit Effekt **observe**: Ihre Prüfungen werden trotzdem durchgeführt, und was sie getan hätten, wird als **would-have** auf der Richtlinienseite aufgezeichnet, aber es blockiert oder hebt niemals einen Aufruf auf. `failproofai jev setup --mode` und der **Settings → Jev**-Schalter im Dashboard zeigen an, dass der Modus von FailproofAI Cloud verwaltet wird, und ändern nichts. `jev.json` wird nicht für Cloud-Prüfungen verwendet, selbst wenn dort ein anderer Provider angegeben ist. `failproofai config --disconnect` übergibt Jev zurück an die eigene `jev.json` der Maschine. + +`failproofai jev status` meldet dann `Jev checks run on FailproofAI Cloud (mode: enforce)`. Es nennt auch die Prüfungen, die jede `both`-Richtlinie überprüfen. Die Fleet-Seite zeigt, warum eine Maschine mit einem Modus nicht fragen kann: + +- `transcripts_disabled`: Die Maschine wurde mit `--no-transcripts` verbunden, was Jev nie einschaltet. +- `jev_unconfigured`: Der Key der Maschine trägt nicht `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud hat einige Aufrufe der Maschine aufgrund des Jev-Rate-Limits der Organisation abgelehnt, und diese Aufrufe wurden allein durch die Regex-Richtlinien entschieden. +- `jev_unavailable`: Mehrere aufeinanderfolgende Aufrufe sind fehlgeschlagen, sodass die Maschine das Jev von FailproofAI Cloud jeweils für eine Minute überspringt. Sie versucht es selbstständig erneut. + +Wenn FailproofAI Cloud nicht innerhalb von 5 Sekunden antwortet, entscheiden die Regex-Richtlinien allein, wie bei jedem Jev-Ausfall. Nach 3 aufeinanderfolgenden Fehlern hört die Maschine jeweils für eine Minute auf zu fragen, damit ein Cloud-Ausfall nicht jeden Tool-Aufruf verlangsamt. + +Eine Sitzungspause (`failproofai config --pause`) stoppt die Jev-Prüfungen von FailproofAI Cloud nicht, genau wie sie von Cloud verwaltete Richtlinien nicht stoppt. Sie pausiert die Jev-Prüfungen von auf der Maschine installierten Packs. + +## Überprüfen Sie die Aktivität + +```bash +failproofai jev status +failproofai jev test +``` + +`status` zeigt den Provider als **FailproofAI Cloud**, den Cloud-Host, mit dem die Maschine verbunden ist, den Modus und die Key-Quelle als **FailproofAI Cloud connection** an – niemals den Key selbst. Wenn eine FailproofAI Cloud-`jev.json` vorhanden ist, Jev aber nicht ausgeführt werden kann, wird der Grund angegeben: + +| `status` zeigt | `status --json` | Bedeutung | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | Die Maschine ist verbunden, aber es ist kein Jev-Key für sie gespeichert: dem Key fehlt `jev:evaluate`, oder die Verbindung konnte ihn nicht bestätigen. Führen Sie `failproofai config` erneut mit dem Key in `FAILPROOFAI_CLOUD_TOKEN` aus; wenn ihm die Berechtigung fehlt, verwenden Sie einen **machine**-Key. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Auf dieser Maschine gibt es keine FailproofAI Cloud-Verbindung, zu der der Jev-Key gehören könnte. | + +Nach `failproofai config --disconnect` gibt es keine FailproofAI Cloud-`jev.json` mehr (es sei denn, sie wurde deaktiviert, was beibehalten wird), sodass `status` Jev einfach als deaktiviert meldet. `status --json` enthält dieselben Informationen (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), auch wenn die Konfiguration fehlt oder verweigert wird. `permissions` ist immer das der `jev.json`; eine Verweigerung bezüglich `credentials.json` fügt `credentialsPermissions` hinzu, und `fix`, wenn ein Befehl es behebt. `test` sendet eine Live-Anfrage und meldet deren Latenz und die Jev-Version, die geantwortet hat. Es beendet sich mit 1 und zeigt dies im Titel an, wenn die Antwort nach dem Hook-Timeout eintrifft (Hooks würden `timeout` aufzeichnen) oder ihre Prüffrage falsch beantwortet. + +Das **Settings → Jev**-Panel im Dashboard zeigt auch die **FailproofAI Cloud connection**: in welche Organisation die Maschine berichtet und ob ihr Key Jev trägt. Es wird aus den eigenen Dateien der Maschine gelesen, ohne Netzwerkaufruf. + +## Einen echten Aufruf verifizieren + +Starten Sie eine neue Sitzung im eingehängten Agent. Bitten Sie ihn, sein Datei-Lese-Tool auf `README.md` zu verwenden und den Titel zu melden. Bestätigen Sie, dass die Sitzung diesen Tool-Aufruf enthält, und führen Sie dann erneut `failproofai jev status` aus: Der Zähler der zuletzt ausgewerteten Aufrufe sollte steigen. Öffnen Sie **Policies → Activity** im [lokalen Dashboard](/de/reference/local-dashboard#review-policy-activity), um das Jev-Urteil und den Modus dieses Aufrufs zu untersuchen. In Cloud zeigt die **Policies**-Seite der Organisation Jev-Ergebnisse für gelieferte Aktivitäten. Im Observe-Modus wird das Urteil als **would-have** aufgezeichnet, und das Richtlinienergebnis entscheidet weiterhin den Aufruf. Eine Aufhebung erscheint nur, wenn eine überprüfbare Richtlinie übereinstimmte und Jev ihre benannten Prüfungen aufgehoben hat. + +## Was auf der Richtlinienseite erscheint + +Die Maschine sendet ihre Hook-Aktivität bereits an FailproofAI Cloud (`events:add`). Mit aktiviertem Jev enthält der Datensatz jedes gesperrten Aufrufs außerdem, welcher Evaluator ausgeführt wurde, was Jev entschieden hat, welche Richtlinien es aufgehoben hat, warum es zurückgefallen ist (falls zutreffend), seine Latenz und das Modell, das geantwortet hat – Entscheidungen, Codes und Namen, niemals den Befehl oder Ihre Eingabeaufforderung. Auf der **Policies**-Seite Ihrer Organisation: + +- Ein Aufruf, den Jevs eigenes Urteil entschieden hat (Enforce-Modus), wird **Jev** zugeordnet, und wenn die entscheidende Prüfung aus einem Pack stammt, nennt der Datensatz auch dieses Pack und seine Version; +- Im Observe-Modus erscheint Jevs Deny oder Warnung als **would-have**, neben den Rollouts, die Sie beobachten; +- Die Richtlinien, die Jev aufgehoben hat oder im Observe-Modus aufgehoben hätte, werden pro Richtlinie gezählt. +- Eine Entscheidung, an der Jev beteiligt war (eine Blockierung, eine Warnung, eine Aufhebung oder ein would-have im Observe-Modus), listet jede durchgeführte Prüfung und ihr Ergebnis auf: Urteil, Warum (`not-detected`, `exempt`, `fired`, `op-requested`, …), die Evidenz `p`, die `exempt`-Antwort und die Antwort jeder Probe. Eine Prüfung einer Richtlinie, die zum Beobachten (observe) deployed wurde, wird ebenfalls aufgelistet, als beobachtet markiert; sie blockiert niemals. Jev antwortet mit Wahrscheinlichkeiten, nicht mit Prosa, daher gibt es keinen Freitext-Grund. Einfache Allows werden zu Zählungen zusammengefasst und tragen diese Liste nicht. + +## Wenn Jev nicht antworten kann + +Jeder dieser Fälle fällt auf das Ergebnis Ihrer Richtlinien für diesen Aufruf zurück und wird mit seinem Grund aufgezeichnet: + +| Grund | Ursache | +| --- | --- | +| `out-of-credits` | Ihre Organisation hat ihr Plan-Kontingent aufgebraucht. | +| `http-401`, `http-403` | Der Key wurde widerrufen oder trägt nicht `jev:evaluate`. Verbinden Sie sich erneut mit einem Key, der dies tut. | +| `http-429` | FailproofAI Cloud begrenzt Jev für Ihre Organisation. Bis die angeforderte Wartezeit abgelaufen ist (sein `Retry-After`, höchstens 60 Sekunden), sendet die Maschine nichts und jeder Aufruf fällt sofort zurück. Auf diese Weise zurückgehaltene Aufrufe werden als `http-429` aufgezeichnet oder als `rate-limited`, wenn das eigene Rate-Limit der Maschine sie zuerst zurückhält. | +| `http-429` (Tageslimit) | Ihre Organisation hat ihr tägliches Jev-Aufruf-Kontingent aufgebraucht: **10.000 pro UTC-Tag**, es sei denn, der Betreiber Ihrer FailproofAI Cloud hat ein anderes Limit festgelegt. Jeder Aufruf fällt zurück, bis der Zähler um 00:00 UTC zurückgesetzt wird; die Maschine fragt höchstens einmal pro Minute erneut, sodass sie den Reset innerhalb einer Minute erkennt. `failproofai jev test` meldet: "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev hat die Anfrage dieses Aufrufs abgelehnt, normalerweise weil der Tool-Aufruf dichten Text (Base64, Hex, minifizierten Code) über Jevs Token-Budget enthielt. Dieser Aufruf fällt jedes Mal zurück; es handelt sich nicht um einen Ausfall. | +| `http-502` | Jev ist derzeit nicht verfügbar. | +| `http-503` | Diese Cloud kann Jev für Ihre Organisation nicht bedienen: kein Model-Gateway, eine noch nicht bereitgestellte Organisation oder das Gateway ist ausgefallen. Fragen Sie Ihren Admin; Hooks fragen höchstens einmal pro Minute erneut. | +| `http-404` | Diese FailproofAI Cloud bedient Jev noch nicht. | +| `timeout` | Keine Antwort innerhalb von `timeoutMs` (Standard 3000). Während FailproofAI Cloud den Jev-Modus der Maschine festlegt, beträgt die Wartezeit 5000 ms und das `timeoutMs` von `jev.json` wird nicht verwendet. | +| `model-mismatch` | Eine andere Jev-Version als 1.13 hat geantwortet. | + +## Wo der Key gespeichert wird und wohin er geht + +- Der Key wird einmal gespeichert, in `~/.failproofai/credentials.json` (`0600`, in einem nur dem Eigentümer zugänglichen Verzeichnis), neben den anderen FailproofAI Cloud-Credentials. `jev.json` enthält für diese Route keinen Key; ein dort eingetragener Key macht die Konfiguration ungültig. +- Wenn `credentials.json` **irgendeine** Berechtigung für jemand anderen als Sie trägt (Gruppe oder andere, Lesen oder Schreiben), oder wenn ihr Verzeichnis von jemand anderem als Ihnen **beschrieben** werden kann, wird sie **verweigert**, nicht gelesen, und Jev ist deaktiviert, bis Sie es beheben: `chmod 600` für die Datei, `chmod 700` für das Verzeichnis (oder erneut verbinden, was die Datei mit `0600` neu schreibt und das Verzeichnis nur dem Eigentümer zugänglich macht). Ein Verzeichnis, das andere nur lesen können, ist in Ordnung; eines, in das sie schreiben können, ermöglicht ihnen den Austausch der Datei. +- Der Key zählt nur, solange die Verbindung, mit der er kam, auf der Maschine ist: ein Richtlinien- oder Reporting-Credential für dieselbe FailproofAI Cloud **mit demselben Key**, in derselben Datei. Ein hinterlassener Jev-Key ohne eine solche Verbindung wird ignoriert, und Jev bleibt deaktiviert. Das passiert, wenn `config --disconnect` einer älteren failproofai-Version den Jev-Key hinterlässt (sie weiß nicht, ihn zu entfernen), oder wenn `config --token` einer älteren failproofai-Version mit einem anderen Key verbindet, der auf FailproofAI Cloud einer anderen Organisation gehören kann. Um Jev wieder einzuschalten, verbinden Sie sich erneut mit einem **machine**-Key. +- Der Key wird ausschließlich an den Cloud-Origin gesendet, gegen den er verifiziert wurde. Eine `jev.json`, die woanders hinzeigt, wird verweigert. +- **Ein Agent auf der Maschine kann ihn lesen.** `credentials.json` ist nur dem Eigentümer zugänglich, und der Agent läuft als dieser Eigentümer. Das Lesen von failproofais eigenen Dateien ist absichtlich erlaubt (nur das Ändern wird blockiert, durch `block-failproofai-commands`), sodass das Einzige zwischen einem Agent und dieser Datei `block-read-outside-cwd` ist – eine *reviewable*-Richtlinie – und von einer Sitzung aus, die in Ihrem Home-Verzeichnis gestartet wurde, nichts. Ein Key mit `jev:evaluate` verbraucht das Jev-Kontingent Ihrer Organisation (bis zur Tageshöchstgrenze) von überall, wo er verwendet wird; behandeln Sie daher einen Machine-Key wie jedes andere Ausgaben-Credential: Wenn ein Agent ihn möglicherweise gelesen hat, deaktivieren Sie ihn auf der Keys-Seite und verbinden Sie sich mit einem neuen erneut. +- Nur Ihre globalen Dateien entscheiden dies. Ein Repository kann Cloud-Jev nicht einschalten, es woanders verweisen oder seinen Key bereitstellen, und `FAILPROOFAI_JEV_API_KEY` wird für diese Route ignoriert. +- Für jeden von Jev ausgewerteten Aufruf geht eine Anfrage an FailproofAI Cloud, die das enthält, was die [Bring-your-own-key-Seite](/de/reference/jev-providers#what-leaves-the-machine) auflistet (Secrets geschwärzt). FailproofAI Cloud leitet es an TypeSafe weiter und protokolliert oder speichert es nicht. + +## Deaktivierung + +Auf einer verbundenen Maschine ist Jev deaktiviert, wenn FailproofAI Cloud keine Jev-Richtlinie auf ihr deployed: Entfernen oder archivieren Sie die Jev-Richtlinien dort. + +| Befehl | Ergebnis | +| --- | --- | +| Entfernen Sie die Jev-Richtlinien der Maschine in FailproofAI Cloud | Der Modus von Cloud wird beim nächsten Poll (ca. 30 s) zu `off`: kein Jev, unabhängig davon, was `jev.json` angibt. | +| `failproofai config --disconnect` | Trennen Sie die Maschine: Der Key wird entfernt, ebenso `jev.json`, wenn sie FailproofAI Cloud benennt und nicht deaktiviert ist. Eine `jev.json` für Ihren eigenen Endpoint bleibt erhalten. | + +Ab dem nächsten Tool-Aufruf führen Hooks die Regex-Richtlinien genau wie zuvor aus. \ No newline at end of file diff --git a/docs/de/reference/jev-evaluations.mdx b/docs/de/reference/jev-evaluations.mdx new file mode 100644 index 000000000..27018d52a --- /dev/null +++ b/docs/de/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev-Evaluierungsreferenz" +description: "Fragetypen, kalibrierte Bewertungen, Grenzen und Backfill für Jev-Sitzungsevaluierungen." +icon: "list-checks" +--- + +Diese Seite beschreibt die Frageformen und Bewertungsregeln hinter [Jev-Evaluierungen](/de/evaluations/jev). Manche Fragen erfordern ein Modell, das das Gespräch *liest*, aber nicht darüber *schreibt*. „Hat der Kunde Dringlichkeit ausgedrückt?" hat zwei Antworten. „Wie frustriert waren sie?" hat eine Handvoll, in einer bestimmten Reihenfolge. Sie kennen jede Antwort, bevor Sie fragen. + +Eine **Klassifizierer-Evaluierung** ist genau dafür gedacht. Sie schreiben die Frage und die möglichen Antworten, und ein kleines, speziell für die Klassifizierung entwickeltes Modell gibt eine kalibrierte Zahl zurück — niemals Freitext. + + +Wie ein Richter kostet eine Klassifizierer-Evaluierung einen Modellaufruf pro Sitzung. Im Gegensatz zu einem Richter handelt es sich jedoch um ein kleines, zweckgebundenes Modell und nicht um ein allgemeines — es ist daher schneller und günstiger, erklärt sich aber nie selbst. Wenn Sie die Begründung benötigen, verwenden Sie einen [Richter](/de/evaluations/judge). + + +## Was möchte ich verwenden? + +| Frage | Verwenden | +| --- | --- | +| Wie viele Tool-Aufrufe gab es? | Code | +| Dauerte die Sitzung unter 30 Sekunden? | Code | +| Hat der Kunde Dringlichkeit ausgedrückt? | **Klassifizierer** | +| Welches Team soll sich darum kümmern: Abrechnung, Technik oder Vertrieb? | **Klassifizierer** | +| Wie frustriert war der Kunde? | **Klassifizierer** | +| War die Antwort tatsächlich korrekt? | **Richter** | +| Hat es unsere Eskalationsrichtlinie befolgt, und warum denken Sie das? | **Richter** | + +Die Faustregel: **Zählbares → Code, aufzählbare Antworten → Klassifizierer, Erklärung erforderlich → Richter.** + +Sie müssen sich nicht im Voraus entscheiden. Beschreiben Sie, was gemessen werden soll, und der Assistent wählt aus, teilt Ihnen mit, was er gewählt hat und warum — und Sie können jederzeit wechseln. + +## Die zwei Fragetypen + +### `noul` — ist das wahr? + +Zwei Antworten, und Sie beschreiben beide. Das Ergebnis ist die Wahrscheinlichkeit, dass die „wahre" Beschreibung zutrifft: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Beschreiben Sie beide Seiten. „Keine Dringlichkeit ausgedrückt" ist eine echte Antwort, und diese anzugeben macht die andere schärfer. + +### `score` — wie viel davon? + +Eine geordnete Rubrik, **schlechteste zuerst**. Das Ergebnis gibt an, wo die Sitzung auf dieser Skala liegt, normiert auf 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Eine Rubrik umfasst drei bis fünf Stufen, die alle unterschiedlich sein müssen.** Beide Grenzen sind gemessen, nicht stilistisch: + +- **Zwei Stufen** kollabieren in das, was `noul` bereits besser leistet, und **mehr als fünf** veranlassen das Modell, zur Mitte hin auszuweichen, anstatt sich festzulegen. Dieselbe Frage über dieselbe Sitzung ergab 0,00 bei zwei Stufen, 0,01 bei drei und 0,55 bei zehn. +- **Wiederholte Stufen** teilen die Antwort willkürlich auf. Eine Sitzung, die eindeutig wütend war, erzielte 1,00 gegen `["Calm", "Frustrated", "Very angry"]` und 0,66 gegen `["Angry", "Angry", "Angry"]` — eine wohlgeformte Zahl, die nichts bedeutet. + +Kategorien ohne Reihenfolge — „Abrechnung, Technik oder Vertrieb" — sind keine Rubrik. Stellen Sie sie als `noul` pro Kategorie, oder verwenden Sie einen Richter. + +## Ergebnisse lesen + +Ein Klassifizierer erzeugt einen **Score** von 0 bis 1, genau wie ein Richter — er wird also in Diagrammen dargestellt, gefiltert und löst Benachrichtigungen auf dieselbe Weise aus. Zwei Unterschiede sind wichtig: + +- **Es gibt keine Begründung.** Das Feld ist absichtlich leer. Dieses Modell erklärt sich nicht selbst, und eine Erklärung zu erfinden wäre eine Fälschung und kein Feature. +- **Unsicherheit wird gekennzeichnet.** Eine `score`-Frage gibt ihre eigene Konfidenz an, und ein Ergebnis, bei dem das Modell unsicher war, wird mit `low_confidence` markiert — „welche davon sollte ein Mensch sich ansehen?" ist also ein Filter und keine Schätzung. Eine `noul`-Frage gibt keine Konfidenz an und wird daher nie markiert. + +Sehr lange Sitzungen werden in Ausschnitten gelesen und kombiniert. Wenn eine Sitzung zu lang ist, um vollständig gelesen zu werden, gibt das Ergebnis an, wie viele Gesprächsrunden ausgelassen wurden — Sie werden nie ein Urteil sehen, das auf einem Teil einer Sitzung basiert und als eines präsentiert wird, das auf der gesamten basiert. + +## Grenzen + +- **Drei bis fünf Rubrikstufen, alle unterschiedlich.** Siehe oben; beide Grenzen werden bei der Erstellung erzwungen. +- **Eine Frage pro Evaluierung.** Stellen Sie zwei Fragen, erhalten Sie zwei Evaluierungen — was auch das ist, was Sie in einem Diagramm möchten. +- **Das Bearbeiten der Frage veröffentlicht eine neue Version.** Alte und neue Bewertungen sind nicht vergleichbar, daher werden sie getrennt gehalten und nicht in eine Trendlinie gemischt. +- **Ein Klassifizierer erzeugt immer einen Score**, niemals eine Metrik oder eine Aussage. +- **Keine Begründung**, wie oben beschrieben. Wenn eine Zahl jemanden zu „warum?" veranlassen wird, schreiben Sie stattdessen einen Richter. + +## Testen und Backfill + +Im Gegensatz zu einem Richter **kann** eine Klassifizierer-Evaluierung getestet werden, bevor Sie sie einsetzen — [testen Sie sie](/de/evaluations/test) gegen echte Sitzungen auf dieselbe Weise wie eine Code-Evaluierung, und lesen Sie die Bewertungen, bevor etwas live geht. + +Sie kann auch über bereits vorhandene Sitzungen [nachgefüllt](/de/evaluations/deploy#score-sessions-you-already-have) werden. Es kostet einen Modellaufruf pro Sitzung — wählen Sie das Zeitfenster daher bewusst, anstatt alles erneut zu verarbeiten. \ No newline at end of file diff --git a/docs/de/reference/jev-intent.mdx b/docs/de/reference/jev-intent.mdx new file mode 100644 index 000000000..fbf018bc8 --- /dev/null +++ b/docs/de/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev Intent-Erfassung" +description: "Welche Harness-Ereignisse dem Jev-Evaluator mitteilen, was der Mensch angefragt hat, welches Feld den Text enthält, was niemals gezählt wird und welches Risiko mit dem Vertrauen in einen harness-gelieferten Prompt einhergeht." +icon: "message-square-quote" +--- + +Wenn Sie die [Jev-Richtlinienprüfung](/de/policies/jev) konfigurieren, beurteilt der Evaluator jeden kontrollierten Tool-Aufruf anhand von **dem, was der Mensch angefragt hat** — nicht anhand dessen, was der Harness dem Agenten vorgelegt hat. Eine Antwort wie „ja, force-push it" kann eine **reviewable**-Richtlinie freigeben — das ist der eigentliche Zweck des Evaluators, da ein Regex, der die Anfrage nicht lesen kann, ein Drittel aller echten Aufgaben blockiert. + +Dieser Text stammt aus einer einzigen Quelle: **dem Prompt, den der Harness selbst bei seinem Prompt-Submit-Ereignis an den Hook übergibt**. Failproof AI zeichnet den vom Menschen eingegebenen Teil davon auf — Harness-Umrahmung entfernt, Secrets redigiert, Länge begrenzt — in einer `0600`-Datei in seinem eigenen Zustandsverzeichnis. Es wird nichts auf der Festplatte abgefragt: Das Session-Transkript ist eine Datei, die der Agent mit einem einzigen Befehl überschreiben kann, daher wird nie gefragt, wer einen Prompt verfasst hat. + +## Das damit verbundene Risiko, unverblümt + +Ein Agent, der bereits Befehle ausführen kann, kann einen Harness veranlassen, einen Prompt einzureichen. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` und `pi -p` lösen alle dasselbe Prompt-Submit-Ereignis aus — mit demselben Payload, wie ein Mensch es eintippen würde — in einer untergeordneten Session, die dieser Agent kontrolliert. Der Agent kann auch Failproof AIs eigene Hook-Binärdatei ausführen und ihr einen selbst erstellten Payload übergeben. Nichts innerhalb von Failproof AI kann beides vom Echten unterscheiden — beide sind dasselbe Programm, das denselben stdin liest. + +**Ein Agent mit Shell-Zugriff kann also seine eigene Zustimmung fälschen.** Das ist ein bewusster Kompromiss, der am 2026-09-23 eingegangen wurde, und hier sind beide Seiten davon: + +- **Was er einbringt.** Die Alternative wurde gebaut und gemessen: Ein Feld verlangen, in dem der Harness einen Menschen als Autor des Prompts benennt, und andernfalls nichts aufzeichnen. Kein verfügbarer Harness sendet ein solches Feld, sodass diese Version **auf jedem Harness nichts aufzeichnete** — Jev beurteilte jeden Aufruf ohne angegebene Absicht und konnte niemals eine einzige Richtlinie freigeben. Eine Erfassung, die niemals auslöst, ist kein sichereres Produkt, sondern überhaupt kein Produkt. +- **Was er nicht leisten kann.** Ein aufgezeichneter Prompt kann immer nur eine Richtlinie freigeben, die bereits als **reviewable** markiert ist. Eine **hard**-Richtlinie wird durch nichts, was Jev sagt, jemals freigegeben — ein gefälschter Prompt kann also niemals aus einem hard deny ein allow machen. Und das Überspringen des Hooks bringt einem Agenten ebenfalls nichts: Der Harness ruft Failproof AI für den Tool-Aufruf unabhängig davon auf. +- **Was er im schlimmsten Fall bewirken kann.** Das Schlimmste, was er tun kann, ist eine der fünfzehn reviewable eingebauten Richtlinien freizugeben — und **zwölf dieser fünfzehn blockieren**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` sowie die sechs Infrastruktur-CLI-Blöcke (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) sind Denies — eine gefälschte Zustimmung kann also ein echtes Deny in ein Allow verwandeln für: das Ausgeben von Umgebungs-Secrets, das Lesen einer `.env`-Datei, das Lesen außerhalb des Projekts, `rm -rf`, einen force-push, das Schreiben einer Secrets-Datei oder das Ändern von Live-Infrastruktur. Nur `warn-git-amend`, `warn-destructive-sql` und `warn-global-package-install` sind Hinweise. Eine Standardinstallation aktiviert zwei der zwölf: `protect-env-vars` und `block-env-files`; die anderen zehn sind nur auf Maschinen aktiv, wo jemand sie manuell aktiviert hat. Was kein Prompt jemals erreicht, ist alles Hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, der Schutz, der verhindert, dass ein Agent Failproof AI deaktiviert, und jedes andere eingebaute, das nicht als reviewable markiert ist. [Policy authority](/de/policies/authority) listet alle fünfzehn auf und was jede prüft. + +Weiterhin abgelehnt wird alles, was einfach zu prüfen ist und was ein Agent nicht allein durch Fragen erlangen kann: ein Turn, den der eigene Harness-Payload als maschinell eingereicht kennzeichnet, ein Payload, der einen Sub-Agenten benennt, eine Session-ID, die kein einfacher Name ist, ein Ereignis, das nicht das Prompt-Submit-Ereignis ist, und Text, der ausschließlich aus Harness-Umrahmung besteht — einschließlich Failproof AIs eigener Stop-Gate-Wörter, die mehrere Harnesses als nächsten User-Turn zurücksenden. + +## Harness-Tabelle + +„Text field" ist das stdin-Payload-Feld nach Failproof AIs harnessspezifischer Normalisierung. „Recorded" gibt an, ob der Prompt als Anfrage des Menschen gespeichert wird. + +| Harness | `--cli` | Prompt-Ereignis → kanonisch | Text-Feld | Aufgezeichnet | Letzte Agenten-Nachricht gelesen aus | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Ja, es sei denn, das `source`-Feld des Payloads benennt einen Turn, den niemand eingereicht hat (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, ein unbekannter Wert und ein Build, der gar kein `source` sendet, werden alle aufgezeichnet | das Session-Transkript (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Ja | das Rollout-JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Ja | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Ja, wobei der ``-Wrapper entfernt wird, wenn er den gesamten Prompt umschließt | das Agent-Transkript-JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | Ja — aber das aktuelle OpenCode enthält in diesem Ereignis keinen Text, sodass in der Praxis nichts aufgezeichnet wird; eine Wiederholung derselben Nachricht wird einmal aufgezeichnet | keines (Sessions sind SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Ja, es sei denn, `input_source` ist `extension` — die `sendUserMessage()` einer anderen Extension, deren Text modellgeneriert oder repo-abgeleitet sein kann | das Pi-Session-JSONL | +| Hermes | `hermes` | keines | — | Nein — Hermes hat überhaupt kein Prompt-Submit-Ereignis | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Ja, es sei denn, die Run-Metadaten kennzeichnen den Run als maschinell: ein `trigger` außer `user`, ein `inputProvenance.kind` außer `external_user` oder `senderIsOwner: false` | keines (`before_agent_run` enthält keinen Transkriptpfad) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Ja | das Droid-Session-JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Ja | keines (Sessions sind SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | keines | Nein — `PreInvocation` löst vor *jedem* Modell-Aufruf in einem Turn aus und enthält keinen Prompt-Text | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Ja | keines (Sessions sind SQLite) | + +Zwei Harnesses zeichnen nichts auf, und aus demselben Grund: Ihr Ereignis liefert keinen menschlichen Text. Hermes hat kein Prompt-Submit-Ereignis — sein natives Plugin verarbeitet `pre_llm_call` selbst und leitet nur Tool-, Session- und Subagenten-Ereignisse weiter. Antigravitys `PreInvocation` löst vor jedem Modell-Aufruf aus — beim Human-Turn und bei den fünf nachfolgenden — und enthält kein Prompt-Feld; Hooks können außerdem `userMessage`-Schritte in dasselbe Gespräch injizieren. In keinem der beiden Ereignisse gibt es etwas aufzuzeichnen. + +## Was einen Prompt zum Prompt des Menschen macht + +1. **Das Ereignis.** Failproof AI wurde für das Prompt-Submit-Ereignis des Harnesses aufgerufen, das der Handler zu `UserPromptSubmit` kanonisiert. +2. **Der Payload.** Der Harness schreibt ihn auf den stdin des Hooks, und er enthält den Text im oben genannten Feld. Ein Aufruf, der Failproof AI ohne Payload erreicht, zeichnet nichts auf. +3. **Nichts im Payload schließt den Turn aus.** Ein Payload, der einen Sub-Agenten benennt (`agent_id`), ist der Agent, der sich selbst promptet. Ein `source`-, `input_source`- oder OpenClaw-Run-Marker, der einen maschinell eingereichten Turn benennt, wird abgelehnt. Ein **fehlender** Marker schließt nichts aus — das ist der Unterschied zur Version, die nichts aufzeichnete, da jeder Marker hier bei jedem verfügbaren Build fehlt. +4. **Nach dem Entfernen der Umrahmung bleibt etwas übrig** (siehe unten). + +**Das Session-Transkript ist kein Beweis dafür, wer einen Prompt verfasst hat.** Frühere Versionen dieser Seite beschrieben eine Transkript-Querprüfung: Der Prompt wurde abgelehnt, wenn das Transkript zeigte, dass das Modell ihn geplant hatte, und das Transkript musste das des vorherigen Prompts fortsetzen. Diese Prüfung ist abgeschafft. Ein Transkript ist eine Datei, über die der Agent bereits Shell-Zugriff hat — es kann abgeschnitten, ersetzt, über das Lesebudget hinaus aufgefüllt, zu Beginn eines Turns gesichert und am Ende wiederhergestellt oder mit vom Agenten selbst geschriebenen Einträgen neu befüllt werden. Jede Härtungsrunde wurde von einer weiteren Variante derselben Fälschung gefolgt, sodass der gesamte Mechanismus entfernt statt repariert wurde. + +Das Transkript wird noch für eine Sache gelesen: **die letzte sichtbare Nachricht des Agenten**. Diese Nachricht ist per Definition agentengeschrieben, Jev wird darüber informiert, und sie gilt allein niemals als Zustimmung. + +## Was von einem Prompt aufbewahrt wird + +Harnesses stecken mehr als nur die Worte des Menschen in einen Prompt. Bevor etwas gespeichert wird: + +- ``-Blöcke werden entfernt, die Worte des Menschen darum herum bleiben erhalten. +- Eine Session-Fortsetzungszusammenfassung („This session is being continued from a previous conversation…") wird vollständig verworfen. +- Aufgabenbenachrichtigungen, lokale Befehlsausgaben und Unterbrechungsmarkierungen werden vollständig verworfen. +- Ein Turn, den ein anderer Agent oder eine andere Session geschrieben hat, wird vollständig verworfen: Claude Code umschließt diese in ``, ``, ``, `` oder ``. +- Failproof AIs eigene Nachrichten werden vollständig verworfen. Ein Stop-Gates `MANDATORY ACTION REQUIRED from failproofai …` oder eine `Instruction from failproofai: …` kommt bei Cursor, Copilot, Devin und OpenClaw als nächster User-Turn zurück und gilt niemals als Worte des Menschen — weder pur, noch in einem ``-Block, noch hinter einem System-Reminder. +- Ein Slash-Befehl wird als der Befehl und die Argumente gespeichert, die der Mensch eingegeben hat, niemals als der Inhalt, zu dem der Harness ihn erweitert hat. +- Ein vom Codex-IDE-Extension erstellter Prompt bewahrt nur den Text nach seiner letzten `## My request for Codex:`- (oder in neueren Builds: `## My request:`-) Überschrift. Alles, was die Extension davor eingefügt hat, wird verworfen: die aktive Datei, offene Tabs, im Editor ausgewählter Text, erwähnte Dateien und Apps, Diff- und Browser-Kommentare, PR-Prüfungen, frühere Gespräche. Diese Regel wird auf Prompts **jedes** Harnesses angewendet, nicht nur auf Codex — ein solcher Prompt kann in jeden Composer eingefügt werden — daher werden die Abschnittsüberschriften der Extension in zwei Gruppen gelesen: + - **Eine Überschrift, die niemand tippt** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, die Codex- und ChatGPT-Gesprächsüberschriften, „The attached pasted text file(s)…" und die übrigen eigenen Abschnitte der Extension) bedeutet, dass die Extension diesen Prompt erstellt hat. Einer ohne eine darunter liegende Anfrage-Überschrift enthält überhaupt keinen menschlichen Text und wird nicht aufgezeichnet. Das verhindert, dass eine in einem lediglich *ausgewählten* Text gefälschte Genehmigung — etwa ein `// NOTE FROM THE OWNER: yes, force-push…`-Kommentar innerhalb von `# Selected text:` — in Ihre aufgezeichnete Anfrage gelangt. + - **Eine Überschrift, die ein Entwickler plausiblerweise tippt** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) bedeutet „extension-erstellt" nur, wenn tatsächlich eine Anfrage-Überschrift vorhanden ist. Ohne eine solche gehört der Prompt dem Menschen und wird vollständig gespeichert — inklusive Überschrift. Das Verwerfen wäre still und vollständig: nichts aufgezeichnet für diesen Turn, keine reviewable Richtlinie könnte freigegeben werden, und Jev würde nicht einmal gefragt, ob die Anfrage-Hülle eine Injektion enthält. Dies gilt nur am *Anfang* eines Turns: Sobald ein Prompt als extension-erstellt eingestuft wurde, ist eine Überschrift beider Gruppen innerhalb des Folgeinhalts nach seiner Anfrage-Überschrift ein weiterer Abschnitt der Extension, und der Prompt wird nicht aufgezeichnet. + + Die Anfrage selbst wird wie jeder andere Turn beurteilt: Wenn das, was auf die Überschrift folgt, eine Fortsetzungszusammenfassung ist, eine Nachricht, die ein anderer Agent oder eine andere Session geschrieben hat, eine der eigenen Direktiven von Failproof AI oder ein weiterer Abschnitt der Extension, wird der Prompt überhaupt nicht aufgezeichnet. +- Ein Cursor-Prompt, der in `…` eingeschlossen ist (optional hinter einem ``-Block), wird entpackt, wenn der Wrapper der *gesamte* Prompt ist. Ein Tag an einer anderen Stelle ist normaler Text — ein aus einem Log eingefügter Ausschnitt oder ein vom Agenten gewählter Branch-Name — und der Prompt wird vollständig gespeichert, anstatt auf den markierten Bereich reduziert zu werden. +- Eingefügte Blöcke werden gespeichert und als vom Menschen eingefügt gekennzeichnet. + +Ein Prompt, der ausschließlich aus Harness-Text besteht, wird überhaupt nicht aufgezeichnet. + +## Die letzte Nachricht des Agenten + +Eine Antwort wie „ja" bedeutet ohne die Frage, auf die sie antwortet, nichts. Wenn ein Prompt aufgezeichnet wird, liest Failproof AI auch die letzte sichtbare Nachricht des Agenten aus dem Session-Transkript **zu diesem Zeitpunkt** und speichert sie zusammen mit dem Prompt. Jev erhält sie in einem eigenen Feld, als agentengeschrieben gekennzeichnet: Sie erklärt eine kurze Antwort und gilt allein niemals als Anfrage des Menschen. Sie ist das Einzige, wofür das Transkript gelesen wird, und das Schlimmste, was ein umgeschriebenes Transkript tun kann, ist eine vom Agenten geschriebene Nachricht dort einzutragen, wo eine vom Agenten geschriebene Nachricht erwartet wird. + +Sie wird vom Ende des Transkripts gelesen, höchstens die letzten 4 MB. Unterstützte Transkriptformate sind Claude Code, Codex-Rollouts (ältere `agent_message`-Ereignisse und neuere `AgentMessage`-Einträge), Cursor, Copilot `events.jsonl` sowie das Pi-, Factory- und OpenClaw-Session-JSONL. Claude Codes eigene synthetische Nachrichten, API-Fehlermeldungen und Subagenten-(Sidechain-)Nachrichten werden übersprungen. Für Goose und OpenCode, die Sessions in SQLite speichern, für Devin, dessen Transkript ein einzelnes JSON-Dokument ist, sowie für OpenClaw, dessen `before_agent_run`-Ereignis keinen Transkriptpfad enthält, gibt es keinen Snapshot. + +## Speicherung + +| Eigenschaft | Wert | +| --- | --- | +| Speicherort | `~/.failproofai/state/semantic/sessions//.json`, wobei `` das Agenten-Profil ist, in das der Prompt eingegeben wurde: `.` für einen Agenten, den FailproofAI kennt (die Identität, auf die Cloud-Richtlinien abzielen), oder andernfalls nur `` | +| Berechtigungen | Datei `0600`, Verzeichnis `0700`. Jedes übergeordnete Verzeichnis bis zu `~/.failproofai` unterliegt derselben Regel wie das Verzeichnis von `jev.json`: Eines, in das jemand anderes **schreiben** kann, kann umbenannt und ersetzt werden — daher entfernt der Lesepfad diese Schreibbits, wo möglich, und liest **nichts**, wo dies nicht möglich ist. Ein aufgezeichneter Prompt ist dann abwesend statt gefälscht, und nichts wird freigegeben | +| Pro Session gespeichert | die letzten 5 Prompts; ein Prompt, der mit dem vorherigen identisch ist, ersetzt ihn, statt einen neuen Slot zu belegen | +| Zeitfenster | Prompts, die älter als 6 Stunden sind, werden ignoriert | +| Größe | Jeder Prompt und jede Agenten-Nachricht ist auf 6.000 Zeichen begrenzt, wobei Anfang und Ende erhalten bleiben | +| Secrets | Vor dem Schreiben mit denselben Mustern wie die `sanitize-*`-Richtlinien redigiert. Ein Text mit mehr als 48.000 Zeichen wird als seine ersten 28.800 und letzten 19.200 Zeichen redigiert, und der Text neben diesen Schnittstellen, wo ein Secret aufgeteilt worden sein könnte, wird niemals gespeichert | + +Eine Session-ID, die etwas anderes als Buchstaben, Ziffern, `.`, `_` und `-` enthält oder länger als 128 Zeichen ist, wird niemals als Dateiname verwendet — für sie wird also nichts aufgezeichnet. + +Eine Session-Datei existiert erst, nachdem ein Prompt darin aufgezeichnet wurde. Sie enthält nur Prompts — keinen Ursprungszustand, keinen Transkript-Marker — und wird gelöscht, sobald sie länger als das Sechsstunden-Fenster inaktiv war, wenn eine neue Session ihren ersten Prompt schreibt. + +Ein Prompt wird nur für dasselbe Agenten-Profil und dieselbe Session-ID zurückgelesen, unter der er aufgezeichnet wurde. Session-IDs kommen vom Agenten, sodass zwei Profile dieselbe verwenden können; die Zuordnung nach Profil stellt sicher, dass die Worte eines Profils niemals als Anfrage eines anderen zählen. Dateien aus einem früheren Layout (`sessions/.json`) können nicht angeben, welches Profil sie geschrieben hat, werden daher niemals gelesen und verfallen mit dem Sechsstunden-Fenster. + +Nichts wird aufgezeichnet, sofern kein Jev-Endpunkt konfiguriert ist. Im FailproofAI-Cloud-Jev-Modus wird für ein Agenten-Profil nichts aufgezeichnet, dem keine Cloud-Jev-Prüfung zugewiesen ist und dessen Prüfung kein installiertes Pack enthält. + +### Das Projektstammverzeichnis + +„Innerhalb des Projekts" — wogegen `read-outside-workspace` und die anderen Pfadprüfungen urteilen — bedeutet innerhalb des Projekts, in dem sich die Session bei ihrem **ersten geprüften Aufruf** befand. Der Stamm wird dann fixiert, und ein späteres `cd` verschiebt ihn nicht; ein `cd` ändert jedoch weiterhin, wie ein relativer Pfad aufgelöst wird. Würde er dem `cd` folgen, würde `cd ~/.ssh` in einem Aufruf `~/.ssh` zum Projekt für den nächsten machen. + +Die Fixierung erfolgt in `~/.failproofai/state/semantic/roots/.json` und enthält `{root, at}`: Datei `0600`, Verzeichnis `0700`, und dieselbe Session-ID-Regel wie oben. Dateien, die älter als 7 Tage sind, werden gelöscht, wenn eine neue Session ihren Stamm fixiert. Ein `roots`-Verzeichnis, in das andere Benutzer schreiben können, wird ignoriert, und stattdessen wird der Stamm des Live-Verzeichnisses verwendet. Um eine Session neu zu fixieren, löschen Sie deren Datei. + +## Bekannte Einschränkungen + +- **Ein Prompt ist nur so vertrauenswürdig wie der Hook-Aufruf.** Alles hier liest den Payload, den der Harness auf den stdin des Hooks geschrieben hat. Ein Agent, der Befehle ausführen kann, kann den Harness ohne Benutzeroberfläche ausführen (`claude -p` und die sieben weiteren oben genannten) oder Failproof AIs eigene Hook-Binärdatei mit einem selbst erstellten Payload aufrufen und einen Prompt aufzeichnen, den niemand eingegeben hat. Dies ist der akzeptierte Kompromiss, der oben beschrieben wird: Er gibt nur reviewable Richtlinien frei, niemals eine hard — aber zwölf der fünfzehn reviewable eingebauten sind Denies, sodass ein gefälschter Prompt bei diesen zwölf einen echten Block in ein Allow verwandeln kann. +- **Sub-Agenten-Erkennung ist Claude-spezifisch.** Ein Payload, der `agent_id` enthält, wird auf keinem Harness aufgezeichnet. Das ist das Feld, das Claude Code, Factory Droid und Devin verwenden würden. Codex löst sein Prompt-Ereignis innerhalb von Sub-Agenten-Threads aus, Copilot führt In-Process-Sidekicks aus, Goose hat ein `delegate`-Tool und OpenClaw führt Personas aus — keines davon kennzeichnet den Payload auf eine erkennbare Weise, sodass ein Sub-Agenten-Prompt auf diesen Harnesses als eigener der Session aufgezeichnet wird. OpenClaws `openclaw.agentId` ist **nicht** dieses Merkmal: Das mitgelieferte Plugin setzt es bei jedem Run, auch beim des Eigentümers. +- **Scheduler ohne Markierung.** Claude Codes `schedule_wakeup` und `loop_wakeup` sowie OpenClaws `cron`- und `heartbeat`-Trigger werden abgelehnt, weil diese Harnesses es im Payload angeben. Gooses eigener Scheduler (`goose schedule add`) und Codex's `codex exec` geben nichts an, sodass ein von ihnen gestarteter Run wie jeder andere aufgezeichnet wird. +- **Die letzte Nachricht eines Agenten kann eine vom Agenten gewählte Nachricht sein.** Das Transkript ist nicht authentifiziert, sodass ein Agent, der sein eigenes Transkript schreibt, entscheiden kann, was seine „letzte Nachricht" besagt. Sie wird als agentengeschrieben gekennzeichnet und gibt allein nichts frei — beachten Sie jedoch, dass der v1-Pfad von `decide.ts` es ermöglicht, die deterministische Prüfung „Hat der Benutzer dieses Ziel benannt" zu erfüllen, sodass ein Agent, der sein Transkript kontrolliert, einen Zielnamen liefern kann, den ein Override benötigt. +- **Ein Prompt, der mit einer der maschinellen Erweiterungs-Überschriften beginnt, wird vollständig verworfen.** Beginnen Sie einen Prompt mit `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` oder einer anderen Abschnittsüberschrift aus der ersten Gruppe oben, und schreiben Sie keine `## My request:`-Überschrift, so wird für diesen Turn nichts aufgezeichnet — und daher auch nichts freigegeben. Das ist beabsichtigt: Diese Abschnitte enthalten Text, den jemand anderes kontrolliert (ausgewählter Code, der Diff-Kommentar eines Reviewers, ein Seitentitel), und diesen als Ihre Worte aufzuzeichnen wäre das größere Versagen. Überschriften, die ein Entwickler plausiblerweise tippt, befinden sich in der zweiten Gruppe und verwerfen einen Prompt niemals allein. +- **OpenCode zeichnet in der Praxis nichts auf.** Sein `message.updated`-Ereignis enthält im aktuellen OpenCode keinen Text, und es löst auch für die untergeordneten Sessions aus, die sein Task-Tool erstellt, deren „Benutzer"-Nachricht der übergeordnete Agent geschrieben hat. +- **`CODEX_HOME` wird** von der Rollout-Erkennung in `lib/codex-sessions.ts` **nicht berücksichtigt**. Dies betrifft nur den Ort, an dem nach einem Agenten-Nachrichten-Snapshot gesucht wird, nicht die Frage, ob ein Prompt aufgezeichnet wird. \ No newline at end of file diff --git a/docs/de/reference/jev-providers.mdx b/docs/de/reference/jev-providers.mdx new file mode 100644 index 000000000..711990f31 --- /dev/null +++ b/docs/de/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev-Anbieter und eigener API-Schlüssel" +description: "Anbieter-Endpunkte, Modell-IDs, Konfiguration und Fehlerverhalten für die Echtzeit-Jev-Richtlinienprüfung mit eigenem Schlüssel." +icon: "key-round" +--- + +Dies ist die Anbieter- und Konfigurationsreferenz für [Jev-Richtlinien](/de/policies/jev) mit eigenem Schlüssel. Regex-Richtlinien gleichen Zeichenketten ab. Sie können nicht unterscheiden, ob `rm -rf build/` von Ihnen angefordert wurde oder ob `rm -rf ~` in einen Plan gerutscht ist – deshalb blockieren sie an einer Stelle zu viel und an einer anderen zu wenig. **Jev**, der Klassifikator von TypeSafe, liest den Aufruf im Kontext Ihrer tatsächlichen Anfrage und beantwortet dabei eine Reihe von Ja/Nein-Fragen in einer einzigen schnellen Anfrage. + +Wenn ein eigener Jev-Endpunkt und -Schlüssel konfiguriert sind, fragt Failproof AI Jev zu jedem Tool-Call **zusätzlich** zu den Regex-Richtlinien ab – niemals stattdessen: + +- Ein **hartes** Policy-Deny ist endgültig. Jev kann es nicht aufheben. Jede Richtlinie ist hart, es sei denn, sie ist ausdrücklich als prüfbar markiert und benennt die Jev-Prüfungen, die sie abdecken. Eine benutzerdefinierte, aus einem Paket stammende oder Cloud-Richtlinie, die nichts angibt, ist hart, und der immer aktive Selbstschutz ist ebenfalls immer hart. +- Ein **prüfbares** Policy-Deny kann aufgehoben werden – aber nur, wenn Jev explizit zu dem genauen Anliegen befragt wurde, das diese Richtlinie abdeckt, und mit „nichts hier" oder „der Benutzer hat darum gebeten" geantwortet hat. Eine Prüfung, die das Anliegen als tatsächlich vorhanden identifiziert, wenn der Benutzer den Aufruf nicht angefordert hat, hält das Deny aufrecht – selbst wenn ihr eigenes Urteil nur eine Warnung ist, denn vor einem Tool-Call hält eine Warnung den Agenten nicht auf. Und wenn diese Prüfung eine ist, die ein Deny auslösen kann (Secret-Exposition, Credential-Exfiltration, destruktives Löschen, …), wird für diesen Aufruf nichts aufgehoben. +- Eine Blockierung kann dennoch zur **Warnung** werden, wenn der Aufruf ein Schritt der von Ihnen gestellten Aufgabe ist und nicht weiter reicht: Jev mildert sein eigenes Deny zu einer Warnung ab, und diese Warnung – die benennt, was tatsächlich mit dem Aufruf nicht stimmt – ersetzt die Blockierung der Richtlinie. +- Jev kann auch eigenständig warnen oder ablehnen, bei Schäden, die kein Regex beschreibt. +- Wenn Jev nicht antworten kann (Timeout, Rate-Limit, Serverfehler, kein Guthaben, eine unerwartete Modellversion), erhält dieser Aufruf das Regex-Ergebnis – genau wie ohne Jev. +- Jev macht einen Aufruf nie zulässiger als Ihre Richtlinien allein, es sei denn, es hat den gesamten Aufruf gelesen und wurde zu genau dem relevanten Anliegen befragt. Alles darunter – ein zu großer Aufruf, ein vermuteter Injection-Versuch – zieht die Freigaben zurück und hält jedes Deny aufrecht. + + +Ohne Jev-Konfiguration ändert sich nichts: Hooks führen die Regex-Richtlinien exakt so aus wie bisher. Die Konfiguration ist der vollständige Opt-in. + + + +Nutzen Sie FailproofAI Cloud? Sie benötigen keinen eigenen Schlüssel: Eine Maschine, die mit einem Schlüssel mit `jev:evaluate`-Berechtigung verbunden ist, kann Jev im Rahmen des Organisationsplans verwenden. Siehe [Jev über FailproofAI Cloud](/de/reference/jev-cloud). + + +## Vorbereitung + +Installieren Sie **failproofai 1.0.8-beta.0 oder höher** und hängen Sie die Hooks an ein [unterstütztes Harness](/de/reference/harnesses) auf der Maschine an, auf der Ihr Agent läuft. Folgen Sie dem [Quickstart](/de/start/quickstart) für eine neue Maschine oder richten Sie [lokale Durchsetzung ein](/de/start/setup#enforce-locally), wenn Sie Cloud nicht verwenden. Prüfen Sie die installierte CLI mit `failproofai --version`. + +Holen Sie sich einen API-Schlüssel von einem der unten aufgeführten Anbieter, oder halten Sie einen kompatiblen Endpunkt und dessen Schlüssel bereit. Jev prüft benannte Tool-Calls am `PreToolUse`- oder `PermissionRequest`-Gate. Es kann ein eigenes Urteil abgeben, aber das Aufheben eines bestehenden Policy-Denys erfordert außerdem eine installierte, als [prüfbar](/de/policies/authority) markierte Richtlinie. Harte Policy-Denys bleiben endgültig. + +## Anbieter wählen + +Jev ist über fünf Wege erreichbar. Bringen Sie für einen davon einen Schlüssel mit. + +| Anbieter | `--provider` | Endpunkt | Standardmodell | Hinweise | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Exakte Versionsangabe. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Anfragen werden ausschließlich an Endpunkte ohne Datenspeicherung weitergeleitet, ohne Fallback zu einem anderen Anbieter. Meldet eine datierte Version wie `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Benennt Jev nur per Alias, daher wird die antwortende Version als nicht verifiziert aufgezeichnet. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Benötigt `--account-id`. Gemessen wurden etwa sechs Anfragen pro Sekunde je Schlüssel, bevor HTTP 429 auftrat. | +| Eigener Endpunkt | `custom` | `/systemone` | `jev-1.13.0` | Jeder Endpunkt, der den TypeSafe-Request-Body akzeptiert und meldet, welches Modell geantwortet hat. Nur `https`; einfaches `http` zu einem Loopback-Host (`localhost`, `127.0.0.1`, `::1`) wird für lokale Tests akzeptiert. | + + +Mit Vercels eigenem Bring-your-own-key-Feature wird eine fehlgeschlagene Anfrage stillschweigend mit Vercels Zugangsdaten wiederholt. Wenn Sie sicherstellen möchten, dass jeder Aufruf ausschließlich Ihrem eigenen TypeSafe-Konto in Rechnung gestellt und von ihm gesehen wird, nutzen Sie TypeSafe direkt. + + +## Einrichten + +Ein Befehl, der Endpunkt und der Schlüssel. Starten Sie im `observe`-Modus, damit Sie Jevs Urteile prüfen können, während die bestehenden Richtlinien weiterhin über Aufrufe entscheiden: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### Die URL bestimmt den Anbieter + +Sie müssen den Anbieter nicht explizit benennen: Der **Host** der URL entscheidet, welcher es ist. + +| URL-Host | Anbieter | Zusätzlich benötigt | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| beliebiger anderer Host | `custom` | — die angegebene URL ist die Basis-URL | + +Daraus folgen drei Dinge: + +- **Eine URL, die der eigene API des Anbieters ist, schreibt keine Überschreibung.** `--url https://api.typesafe.ai/v1` erzeugt exakt die Konfiguration, die `--provider typesafe` erzeugt hätte. Geben Sie einen anderen Pfad oder Host bei einem bekannten Anbieter an, wird er als Basis-URL gespeichert, genau wie es `--base-url` tun würde. +- **`--provider` überschreibt weiterhin die Ableitung**, was die Möglichkeit bietet, einen Proxy zu erreichen, der die API eines Anbieters von einem eigenen Host aus spricht: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Ein `--provider`, der dem Host widerspricht, wird abgelehnt** – ohne Rätselraten. `--provider openrouter --url https://api.typesafe.ai/v1` schreibt nichts und erklärt warum: Die beiden Angaben stimmen darüber nicht überein, wohin Ihr Schlüssel geschickt werden soll. Dasselbe Paar wird auch von `jev setup --base-url` und den Jev-Einstellungen im Dashboard abgelehnt. (`--provider custom` ist kein Widerspruch – es bedeutet „behandle diese URL als sich selbst" – außer beim Cloudflare-Host, dessen kontospezifischen Endpunkt eine Custom-Route nicht erreichen kann.) + +`--url` wird genauso validiert wie `baseUrl` in der Konfigurationsdatei und mit denselben Worten abgelehnt: `https`, oder einfaches `http` zu einem Loopback-Host (`localhost`, `127.0.0.1`, `::1`) in jedem Modus. Risiko: Ein Loopback-Server wird nicht authentifiziert; solange er ausgefallen ist, könnte ein anderer lokaler Prozess seinen Port übernehmen und antworten. Verwenden Sie außerhalb lokaler Tests `https`. + +### Der Schlüssel + +Leiten Sie ihn mit `--key-stdin` ein, oder führen Sie den Befehl ohne dieses Flag in einem Terminal aus und fügen Sie den Schlüssel an einer verdeckten Eingabeaufforderung ein. In beiden Fällen landet er direkt in der Konfigurationsdatei und wird nie zurückgegeben. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` akzeptiert dieselben Flags und ist die Langform für alles: `setup --provider `, wenn Sie lieber den Anbieter als die URL angeben möchten. + +### `--token` und die Kosten + +`--token ` übergibt den Schlüssel als Kommandozeilenargument – der schnellste Weg, eine Maschine zu konfigurieren, aber auch die einzige Variante, bei der der Schlüssel außerhalb der Konfigurationsdatei landet: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Ein Kommandozeilenargument landet anschließend in der Shell-History und ist während der Ausführung in der Prozessliste sichtbar – von `/proc` aus lesbar für alles, was als Sie ausgeführt wird. `setup` weist bei jeder Verwendung von `--token` darauf hin. Bevorzugen Sie `--key-stdin` auf einer gemeinsam genutzten Maschine, in aufgezeichneten Sitzungen oder überall dort, wo die History-Datei synchronisiert wird. Rotieren Sie einen so übergebenen Schlüssel, wenn dies sicherheitsrelevant ist. + + +`--token`, `--key-stdin` und `--key-from-env` schließen sich gegenseitig aus: Geben Sie genau eine Option an. + +Senden Sie dann eine kleine Live-Anfrage, um den Schlüssel, den Endpunkt und die antwortende Jev-Version zu prüfen: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` beendet sich mit Exit-Code 1 und zeigt dies im Titel an, wenn die Antwort nach dem Timeout eintrifft (jeder Hook würde dann auf Regex zurückfallen, Grund: `timeout`) oder die Prüffrage falsch beantwortet. + +Hooks lesen die Konfiguration bei jedem Tool-Call neu, sie greift also ab dem nächsten Aufruf. Es muss nichts neu gestartet werden – weder mit noch ohne Daemon. + +## Aktivität prüfen + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` zeigt Anbieter, Endpunkt, Modell, Modus, Konfigurationsdatei und deren Berechtigungen – niemals den Schlüssel. Darunter fasst es die letzte Aktivität zusammen: wie viele Aufrufe Jev ausgewertet hat, wie oft es auf Regex zurückgefallen ist und warum, die Latenz und welche prüfbaren Richtlinien aufgehoben wurden. + +## Einen echten Aufruf verifizieren + +Starten Sie eine neue Sitzung im Hook-Agenten. Bitten Sie ihn, sein File-Reading-Tool auf `README.md` anzuwenden und den Titel zurückzugeben. Vergewissern Sie sich, dass die Sitzung diesen Tool-Call enthält, und führen Sie dann erneut `failproofai jev status` aus: Der Zähler der ausgewerteten Aufrufe sollte gestiegen sein. Öffnen Sie **Policies → Activity** im [lokalen Dashboard](/de/reference/local-dashboard#review-policy-activity), um das Jev-Urteil und den Modus für diesen Aufruf zu inspizieren. Im Observe-Modus entscheidet weiterhin das Richtlinien-Ergebnis. Eine Freigabe erscheint nur, wenn eine prüfbare Richtlinie anschlug und Jev jede benannte Prüfung bestanden hat; ein einfacher Lesevorgang hat möglicherweise keine aufzuhebende Richtlinie. + +## Observe-Modus + +`enforce` ist der Standard. Um Jev zu beobachten, ohne dass es Entscheidungen beeinflusst, wechseln Sie zu `observe`: Jev wird weiterhin befragt und seine Urteile aufgezeichnet, aber das Regex-Ergebnis wird durchgesetzt. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` behält die Konfiguration – Endpunkt und Schlüssel – und stellt die Jev-Abfragen ein: Hooks führen die Regex-Richtlinien exakt wie ohne Konfiguration aus, und `failproofai jev status` meldet „off (switched off)". Wechseln Sie mit `--mode observe` oder `--mode enforce` zurück. + +Ein erneuter `setup`-Aufruf für denselben Anbieter behält den gespeicherten Schlüssel, ein Moduswechsel erfordert also nur ein einziges Flag. Ein Anbieterwechsel startet neu und fordert den Schlüssel für den neuen Anbieter an. Dasselbe gilt für eine `--base-url`, die Anfragen zu einem anderen Host umleitet: Ein gespeicherter Schlüssel wird nur an den Host gesendet, für den er eingegeben wurde, oder an die eigene API des Anbieters. + +## Die Konfigurationsdatei + +Alles liegt in einer Datei, `~/.failproofai/jev.json`, die von `setup` geschrieben wird: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Feld | Bedeutung | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` oder `custom` – oder `failproofai`, dessen Schlüssel aus der FailproofAI Cloud-Verbindung statt aus dieser Datei kommt (siehe [Jev über FailproofAI Cloud](/de/reference/jev-cloud)). | +| `apiKey` | Wird als `Authorization: Bearer ` gesendet. | +| `baseUrl` | Für `custom` erforderlich; ersetzt andernfalls die API-Basis des Anbieters. Muss `https` sein. Einfaches `http` zu `localhost` wird nur mit `mode: observe` akzeptiert: Ein lokaler Port wird nicht authentifiziert; solange Ihr Proxy ausgefallen ist, könnte jeder Prozess auf der Maschine – einschließlich des zu beurteilenden Agenten – an seiner Stelle antworten. | +| `accountId` | Nur für Cloudflare: 32 hexadezimale Kleinbuchstaben. | +| `model` | Ersetzt die Standard-Modell-ID des Anbieters. Eine versionierte ID muss Jev 1.13 benennen. Ein Wert in der Form eines API-Schlüssels wird abgelehnt (und nicht zurückgegeben), damit ein versehentlich als Modell eingetragener Schlüssel weder gespeichert noch gesendet wird. | +| `timeoutMs` | Wie lange ein Tool-Call auf Jev wartet, bevor das Regex-Ergebnis verwendet wird. 100–10000, Standard 3000. | +| `mode` | `enforce` (Standard), `observe` oder `off` (Konfiguration behalten, kein Jev ausführen). | + +Drei Regeln schützen die Datei: + +- **Nur für den Besitzer.** Sie wird mit Berechtigungen `0600` geschrieben. Eine Kopie, die ein anderer Benutzer oder eine andere Gruppe lesen oder schreiben kann, wird **abgelehnt**, und Hooks fallen auf Regex zurück, bis Sie `chmod 600 ~/.failproofai/jev.json` oder erneut `setup` ausführen. Das Verzeichnis wird ebenfalls geprüft: `~/.failproofai` darf von niemandem anderen **beschreibbar** sein, denn wer dort schreiben kann, kann die Datei unabhängig von ihren eigenen Berechtigungen ersetzen. `setup` entfernt solche Schreibbits, wenn es sie findet. `failproofai jev status` zeigt an, wenn eine Konfiguration abgelehnt wurde, und zeigt den Endpunkt an, den die Datei benennt: Jemand anderes könnte sie geändert haben, prüfen Sie also, ob sie Ihnen gehört, bevor Sie `chmod` ausführen. Ein erneuter `setup`-Aufruf für eine solche Datei überträgt den gespeicherten Schlüssel nur an die eigene API des Anbieters; für jeden anderen Endpunkt, den die Datei nennt, wird der Schlüssel erneut benötigt (`--key-stdin`), oder `--base-url default` leitet Anfragen zurück zum Anbieter. +- **Nur global.** Ein Repository kann Jev weder aktivieren noch auf einen anderen Endpunkt zeigen noch ein Modell auswählen: Eine `.failproofai/jev.json` innerhalb eines Projekts wird ignoriert, und Anbieter, URL, Modell und Account-ID werden ausschließlich aus dieser Datei gelesen – nie aus der Umgebung, die die Agenten-Einstellungen eines Repositories setzen können. (`FAILPROOFAI_HOME` ist kein Umweg: Es verschiebt das gesamte failproofai-Verzeichnis einschließlich Ihrer Richtlinien, anstatt Jev gezielt umzuleiten.) +- **Nur der Schlüssel kann aus der Umgebung kommen.** Enthält die Datei kein `apiKey`, liefert `FAILPROOFAI_JEV_API_KEY` ihn für diese Sitzung (`setup --key-from-env` schreibt eine solche Datei). Es ersetzt nie einen in der Datei enthaltenen Schlüssel und kann Jev ohne die Datei nicht aktivieren. Ist die Variable nicht gesetzt, ist Jev für diese Shell schlicht deaktiviert: `failproofai jev status` meldet dies, beendet sich mit Exit-Code 0 und lässt die Konfiguration unberührt (`status --json` meldet `"status": "key-missing"` mit `"reason": "no-env-key"`). Der `failproofaid`-Daemon sieht Ihre Shell-Umgebung nicht; halten Sie den Schlüssel auf einer mit `failproofai config` eingerichteten Maschine daher in der Datei. + +## Welches Jev antwortet + +Die Entscheidungsschwellen von Failproof AI wurden auf Jev 1.13 kalibriert, daher wird eine Antwort nur dann verwendet, wenn sie aus dieser Familie stammt: `jev-1.13.x` oder OpenRouters `typesafe/jev-1.13-`. Wo ein Anbieter Jev nur per Alias benennt und keine Version meldet (Vercel und Cloudflare, wenn keine Version angegeben wird), wird die Antwort verwendet und als nicht verifiziert aufgezeichnet. Ein `custom`-Endpunkt muss das antwortende Modell melden; die einzige Ausnahme ist ein unversionierter `--model`-Name, den Sie für ihn konfiguriert haben, der – wenn er zurückgemeldet wird – ebenfalls als nicht verifiziert aufgezeichnet wird. Eine Antwort, die eine andere Version meldet, oder eine `custom`-Antwort ohne Versionsangabe wird nicht verwendet: Dieser Aufruf fällt auf Regex zurück mit dem Grund `model-mismatch`. + +## Wenn Jev nicht antworten kann + +Jeder der folgenden Fälle führt für diesen Aufruf zum Regex-Fallback und wird mit seinem Grund aufgezeichnet, den `failproofai jev status` zusammenfasst: + +| Grund | Ursache | +| --- | --- | +| `timeout` | Keine Antwort innerhalb von `timeoutMs`. | +| `http-429` | Der Anbieter hat den Schlüssel rate-limitiert. | +| `rate-limited` | Der eigene Begrenzer von Failproof AI hat den Aufruf zurückgehalten, bevor er gesendet wurde: 5 Anfragen pro Sekunde in Bursts von bis zu 5, und eine kurze Pause nach einer `429`-Antwort des Anbieters. Nicht der Anbieter. | +| `http-500`, `http-502`, `http-503`, … | Ein Serverfehler beim Anbieter. Der genaue Status wird aufgezeichnet. | +| `out-of-credits` | HTTP 402: Das Anbieterkonto hat kein Guthaben mehr. | +| `provider-refused` | HTTP 402 von Cloudflare mit der Meldung „Model execution failed (Payment error)": Der Anbieter hat es abgelehnt, das Modell für diese Anfrage auszuführen. Meist kein Abrechnungsproblem, das durch Aufladen behoben werden könnte. | +| `http-401`, `http-403` | Der Schlüssel wurde abgelehnt. | +| `http-404` | Unter `/systemone` wird nichts bereitgestellt, die Basis-URL ist also falsch – `/systemone` wird an sie angehängt, und jeder Anbieter stellt es an seinem Versions-Root bereit. `failproofai jev models` zeigt, was der Endpunkt tatsächlich bereitstellt. | +| `network` | Der Endpunkt war nicht erreichbar. | +| `http-301`, `http-302`, `http-307`, `http-308` | Der Endpunkt antwortete mit einer Weiterleitung. Weiterleitungen werden nie gefolgt; die Antwort kommt also immer von der in Ihrer Konfiguration hinterlegten URL. Setzen Sie `--base-url` auf die endgültige URL. | +| `malformed` | Der Endpunkt antwortete, aber nicht mit einer Jev-Antwort – ein Body, der kein JSON ist, oder einer ohne Antworten darin. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflares Envelope meldete einen Fehler oder einen noch nicht abgeschlossenen Job. | +| `model-mismatch` | Eine Jev-Version außer 1.13 antwortete, oder ein `custom`-Endpunkt gab nicht an, welches Modell geantwortet hat. | +| `request-cut` | **Kein Ausfall.** Jev antwortete; es sah aber nur einen Teil des Aufrufs, daher hob seine Antwort nichts auf. Siehe [Wenn Jev antwortete, aber nicht auf den gesamten Aufruf](#wenn-jev-antwortete-aber-nicht-auf-den-gesamten-aufruf). | + +`failproofai jev status` kann auch einige seltenere Gründe anzeigen, wie `upstream-error` (die Antwort enthielt den eigenen Fehler des Anbieters) oder `config`, und fasst jeden nicht benennbaren Grund als `other` zusammen. + +`request-cut` ist in dieser Tabelle aufgeführt, weil `failproofai jev status` es zusammen mit den übrigen zählt und weil es ebenfalls jedes Deny aufrechterhält. Es ist der einzige Grund hier, der nichts über Ihren Anbieter aussagt: Die Anfrage kam an und Jev hat geantwortet. Anders als bei allen Zeilen darüber zählt diese Antwort noch – Jevs eigenes Deny oder seine Warnung gilt zusätzlich zum Regex-Ergebnis, statt verworfen zu werden. Eine Häufung solcher Fälle bedeutet also, dass Aufrufe den Evaluator in einer Größe erreichen, die nicht vollständig gesendet werden kann – nicht dass Ihr Endpunkt nicht in Ordnung ist. Guthaben aufzuladen oder die URL zu ändern, wird die Zahl nicht reduzieren. + +## Wenn Jev antwortete, aber nicht auf den gesamten Aufruf + +Zwei weitere Situationen können eintreten, bei denen es sich nicht um einen Jev-Ausfall handelt. Beide betreffen, wie viel des Aufrufs oder des Gesprächsverlaufs in eine einzige Anfrage passte. + +**Ein Teil des Aufrufs selbst passte nicht hinein.** Ein Tool-Call wird innerhalb eines festen Budgets gesendet, und ein überdimensionierter – ein sehr großes `Write`, ein riesiger MCP-Body, ein bis zum Limit aufgefüllter Befehl – wird mit dem gesendeten, was gepasst hat. Jev antwortet dennoch, und seine Antwort zählt weiterhin: sein eigenes Deny oder seine Warnung gilt wie gewohnt. Was es nicht tun kann, ist etwas **aufzuheben**, denn ein Urteil über einen Teil eines Aufrufs ist kein Urteil über den gesamten Aufruf. Jedes Policy-Deny bleibt also bestehen, und der Aufruf wird als Fallback mit dem Grund `request-cut` aufgezeichnet, den `failproofai jev status` zusammen mit den obigen Gründen zählt. Die Regel, die sich daraus ergibt: Einen Aufruf größer zu machen kann seine Freigaben kosten und kann nie eine hinzugewinnen. + +**Eine Nachricht passte nicht hinein.** Ein langer eingefügter Prompt, die letzte Nachricht des Agenten oder ein Prompt, den der eigene Store dieses Evaluators bereits beschnitten hatte. **Es ändert sich nichts**: Der Aufruf wird genauso beurteilt, freigegeben und aufgezeichnet wie jeder andere und wird nicht als Fallback gezählt. Die Länge Ihrer Eingabe entscheidet nie über ein Urteil, und ein Beschnitt kann keine Zustimmung herstellen: Wenn ein Prompt bereits beschnitten ankam, ist „Sie haben das nicht angefordert" eine Schlussfolgerung, die gar nicht mehr gezogen werden kann – sie wird nicht einfach zur Schlussfolgerung. + +Die Grenze zwischen beiden Fällen liegt darin, wer den Text verfasst hat. Der Aufruf gehört dem Agenten, und eine Regel, die seine Länge den Schweregrad verringern lässt, wäre eine Regel, die der Agent ausnutzen kann; Ihr Prompt gehört Ihnen, und seine Länge als Signal zu behandeln würde nur dazu führen, dass das Einfügen einer Spezifikation oder eines Stack-Trace bestraft wird. + +## Was die Maschine verlässt + +Für jeden Tool-Call, den Jev auswertet, wird eine Anfrage an Ihren Anbieter gesendet, die enthält: + +- den Tool-Call selbst, wobei Secrets wie API-Schlüssel, Bearer-Token und `KEY=`-Zuweisungen geschwärzt sind; +- die zuletzt von Ihnen eingegebenen Prompts, ohne den Text, den das Harness Ihres Agenten hinzugefügt hat; +- die letzte Nachricht des Agenten vor Ihrem neuesten Prompt, als agentenverfasst gekennzeichnet; +- lokal berechnete Fakten, z. B. ob ein Pfad innerhalb des Projekts liegt – des Projekts, in dem die Sitzung beim ersten geprüften Aufruf war, [für die Sitzung fixiert](/de/reference/jev-intent#the-project-root) – und den aktuellen Git-Branch. + +Sie geht ausschließlich an den Endpunkt in Ihrer Konfiguration, unter Ihrem Schlüssel. + +## Deaktivieren + +```bash +failproofai jev remove +``` + +Dies löscht `~/.failproofai/jev.json`. Ab dem nächsten Tool-Call führen Hooks die Regex-Richtlinien exakt wie zuvor aus. Die sitzungsspezifischen Stores unter `~/.failproofai/state/semantic/` (aufgezeichnete Prompts in `sessions/`, Projektwurzeln in `roots/`) bleiben erhalten und laufen ab. Um Jev zu stoppen, aber die Konfiguration zu behalten, verwenden Sie stattdessen `failproofai jev setup --mode off`. + +## Befehlsreferenz + +| Befehl | Ergebnis | +| --- | --- | +| `failproofai jev --url --key-stdin` | In einem Befehl konfigurieren; der Anbieter ergibt sich aus dem URL-Host | +| `failproofai jev --url --token ` | Dasselbe, mit dem Schlüssel in der Kommandozeile – History und Prozessliste sehen ihn | +| `failproofai jev setup --provider --key-stdin` | Konfiguration aus einem per stdin eingeleiteten Schlüssel schreiben | +| `failproofai jev setup --provider ` | Dasselbe, Schlüssel an verdeckter Eingabeaufforderung eingeben | +| `failproofai jev setup --key-from-env` | Keinen Schlüssel speichern; `FAILPROOFAI_JEV_API_KEY` pro Sitzung lesen | +| `failproofai jev setup --mode observe` | Modus wechseln (`enforce`, `observe` oder `off`), gespeicherter Schlüssel bleibt erhalten | +| `failproofai jev setup --model ` / `--base-url ` | Modell oder API-Basis überschreiben; `default` hebt die Überschreibung auf | +| `failproofai jev setup --timeout-ms ` | Budget pro Aufruf ändern | +| `failproofai jev status [--json]` | Konfiguration, Berechtigungen und letzte Aktivität; niemals der Schlüssel | +| `failproofai jev test [--json]` | Eine Live-Anfrage: Latenz und die antwortende Version | +| `failproofai jev models [--provider ] [--url ] [--json]` | Die Modell-IDs, die das `/models`-Verzeichnis des Endpunkts meldet, mit Markierung des konfigurierten | +| `failproofai jev remove` | Konfiguration löschen; Jev ist deaktiviert | \ No newline at end of file diff --git a/docs/de/reference/jev.mdx b/docs/de/reference/jev.mdx new file mode 100644 index 000000000..da009477d --- /dev/null +++ b/docs/de/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev Integrationsreferenz" +description: "Konfiguration, Anbieter, Schlüssel, Anfragedaten und Fehlerverhalten für Jev." +icon: "braces" +--- + +Jev hat zwei Verwendungszwecke in Failproof AI: + +| Verwendung | Wann es ausgeführt wird | Was es zurückgibt | Einstieg | +| --- | --- | --- | --- | +| Sitzungsauswertung | Nach Abschluss einer Sitzung | Eine Bewertung für eine Frage mit festgelegter Antwort | [Jev-Auswertungen](/de/evaluations/jev) | +| Überprüfung von Tool-Call-Richtlinien | Vor der Ausführung eines gesperrten Tool-Calls | Ein Urteil zusammen mit den installierten Richtlinien | [Jev-Richtlinien](/de/policies/jev) | + +## Referenzseiten + +| Thema | Details | +| --- | --- | +| [Auswertungsfragen](/de/reference/jev-evaluations) | Boolesche und geordnete Bewertungskriterien, Ergebnisse, Limits und Nachfüllung. | +| [Anbietervergleich und Einrichtung eigener Schlüssel](/de/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare und benutzerdefinierte Endpunkte; URL-Inferenz, Modell-IDs, `jev.json`, Modi und Fallback-Codes. | +| [FailproofAI Cloud-Route](/de/reference/jev-cloud) | Machine-Key-Berechtigungen, automatische Observe-Einrichtung, Nutzungslimits, Verbindungsstatus und Datenverarbeitung. | + +Die lokalen CLI-Befehle sind in der [Failproof AI CLI-Referenz](/de/reference/failproof-cli) aufgeführt. Die [Referenz für das lokale Dashboard](/de/reference/local-dashboard#set-up-jev) beschreibt dessen Jev-Einstellungen und die Aktivitätsansicht. \ No newline at end of file diff --git a/docs/de/reference/mcp.mdx b/docs/de/reference/mcp.mdx new file mode 100644 index 000000000..b7eae8698 --- /dev/null +++ b/docs/de/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP-Server" +description: "Verbinde Claude, Cursor, Codex oder einen anderen MCP-Client mit Failproof AI Cloud und nutze dabei deine eigenen Berechtigungen." +icon: "plug" +--- + +Verbinde ein KI-Tool mit Failproof AI Cloud und arbeite damit mit den Daten deiner Agenten. Dein Tool kann Sitzungen und Events abfragen, schreibgeschütztes SQL ausführen, Dashboards, Alerts, Issues, Audits und Policies lesen – und, sofern du die entsprechende Berechtigung besitzt, Änderungen vornehmen, z. B. einen Alert erstellen oder eine Policy deployen. + +Jeder Aufruf wird mit **deinen eigenen** Berechtigungen ausgeführt, in **einer** Organisation, die du beim Verbinden auswählst. + +Es gibt eine einzige Adresse für alle – egal ob gehostet oder selbst gehostet: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Client verbinden + +Füge die Adresse in deinem Client hinzu. Beim ersten Aufruf eines Tools öffnet sich dein Browser. Wähle aus, wo sich deine Failproof AI Cloud befindet, melde dich an, wähle eine Organisation aus und klicke auf **Allow**. Mit **Cancel** wird keine Verbindung hergestellt. + +Die Seite zeigt den Namen der App sowie die Rücksprungadresse an. Eine App, die nicht durch ihre eigene Webadresse identifiziert wird, ist als **unverified app** markiert – fahre also nur fort, wenn du dies gerade selbst von deinem Client aus gestartet hast. + + + + Gehe in claude.ai oder Claude Desktop zu **Settings → Connectors → Add custom connector**. Benenne den Connector `Failproof AI`, gib die Adresse ein und wähle **Add** und dann **Connect**. + + Bei Team- und Enterprise-Plänen richtet ein Owner den Connector zunächst für die gesamte Organisation ein. Anschließend verbindet jede Person ihr eigenes Konto. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Führe dann `/mcp` in Claude Code aus, wähle `failproofai` und klicke auf **Authenticate**. + + + Füge Folgendes zu `~/.cursor/mcp.json` oder zur `.cursor/mcp.json` deines Projekts hinzu: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor zeigt neben dem Server **Needs login** an. Klicke darauf, um dich anzumelden. + + + Füge Folgendes zu `~/.codex/config.toml` hinzu: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Führe dann `codex mcp login failproofai` aus. + + + Jeder Client, der Remote-MCP-Server über Streamable HTTP mit OAuth unterstützt, funktioniert. Gib ihm die obige Adresse. Es gibt keine Client-ID oder kein Secret, das konfiguriert werden muss. + + + +## Eine Organisation pro Verbindung + +Eine Verbindung agiert ausschließlich in der Organisation, die du ausgewählt hast. Um zwei Organisationen zu verwenden, füge den Server zweimal unter verschiedenen Namen hinzu – z. B. `failproofai-acme` und `failproofai-sandbox` – und verbinde jeden mit seiner eigenen Organisation. + +Demo-Organisationen akzeptieren keine Verbindungen. Wähle stattdessen deine eigene Organisation. + +## Berechtigungen + +Eine Verbindung kann alles tun, was du in der Organisation tun kannst – innerhalb der unten aufgeführten Menge. Sie folgt deinen aktuellen Berechtigungen: Wenn dir ein Admin mehr Rechte gibt, erhält das Tool diese ebenfalls, und wenn ihm etwas entzogen wird, verliert das Tool es beim nächsten Aufruf. + +| Berechtigung | Das Tool darf | +| --- | --- | +| `events:read` | Events auflisten, die Übersicht einer Sitzung lesen, Agenten und Umgebungen auflisten | +| `evaluations:read` | Sitzungen auflisten sowie Evaluierungsergebnisse und -jobs lesen und zusammenfassen | +| `evaluations:trigger` | Evaluierungen erstellen, neue Versionen veröffentlichen, sie aktivieren oder deaktivieren, Backfills durchführen und eine Sitzung neu evaluieren | +| `dashboards:read`, `dashboards:write` | Dashboards lesen oder erstellen, umbenennen und Abfragen hinzufügen | +| `queries:read`, `queries:write` | Gespeicherte Abfragen lesen oder speichern und bearbeiten | +| `queries:run` | Eine schreibgeschützte SQL-Abfrage ausführen und das Abfrageschema lesen | +| `alerts:read`, `alerts:write` | Alerts lesen oder erstellen, bearbeiten, pausieren, löschen und testen | +| `issues:read` | Issues lesen, bestätigen und kommentieren | +| `issues:create` | Ein Issue zu einem Alert öffnen | +| `issues:close` | Issues lösen und schließen | +| `audits:read`, `audits:write` | Audits, Durchläufe und Befunde lesen oder Audits erstellen und bearbeiten sowie einen Durchlauf starten | +| `code_fixes:read` | Sehen, wie ein Issue behoben werden kann, und den Kontext für einen eigenen Agenten zum Beheben abrufen | +| `code_fixes:write` | Eine Behebung in Failproof AI Cloud starten, wodurch ein Pull Request auf deinem GitHub geöffnet wird | +| `policies:read`, `policies:write` | Policies, Maschinen und Deployments lesen oder Policies veröffentlichen, deployen und zurückrollen | + +Einige Tools benötigen keine Berechtigung, da sie keine Organisationsdaten lesen: das Erstellen von Sitzungs- und Event-Links sowie das Durchsuchen dieser Dokumentation. + +Ein KI-Tool kann niemals API-Schlüssel, Benutzer, Einstellungen oder die Organisationsverwaltung berühren und kann keine Events senden. + +## Änderungen genehmigen + +Schreiboperationen fordern dich zunächst zur Bestätigung auf, sofern dein Client die Eingabeaufforderung anzeigen kann. Du siehst, was sich ändern wird, und wählst **Approve this change**, um fortzufahren. Wenn du ablehnst oder innerhalb von etwa 4 Minuten nicht antwortest, ändert sich nichts. Manche Clients hören nach einer Minute auf zu warten, also antworte zeitnah. + + + Ein Client, der keine Eingabeaufforderungen unterstützt, wird nicht gefragt, und ein Schreibvorgang wird ausgeführt, sobald der Client den Aufruf macht. In diesem Fall ist die eigene Bestätigung deines Clients die einzige – halte sie daher für Schreib-Tools aktiviert. + + +## Verbundene Apps und Widerrufen + +**Settings → Integrations → MCP** listet deine verbundenen Apps in der aktuellen Organisation auf, zusammen mit ihren Berechtigungen und der letzten Nutzung. **Revoke** trennt eine App sofort. Das Entfernen des Servers in deinem Client widerruft die Verbindung ebenfalls. + +Du kannst bis zu 5 verbundene Apps pro Organisation haben. Wenn du dieselbe App erneut verbindest, ersetzt dies ihre frühere Verbindung. + +## Selbst gehostete Deployments + +Wähle beim Verbinden **Self-hosted Failproof AI Cloud** und gib die Adresse ein, unter der du dich anmeldest. Dein Deployment muss über öffentliches HTTPS erreichbar sein. + +Tool-Aufrufe und ihre Ergebnisse werden über das gehostete Failproof AI-Gateway zwischen deinem KI-Tool und deinem Deployment übertragen. Das Gateway speichert sie nicht. + +## Was mit deinen Daten passiert + +Ergebnisse gehen an das KI-Tool, das du verbunden hast, und dessen Anbieter verarbeitet sie gemäß seinen eigenen Bedingungen. Für jeden Tool-Aufruf protokolliert Failproof AI den Namen des Tools, sein Ergebnis, die Dauer und die Organisation – niemals die Argumente oder Ergebnisse. Siehe die [Datenschutzrichtlinie](https://befailproof.ai/privacy/). + +## Fehlerbehebung + +| Was du siehst | Was zu tun ist | +| --- | --- | +| „Started in another browser" | Schließe die Anmeldung in dem Browser ab, den der Client geöffnet hat (mit aktivierten Cookies) und starte erneut vom Client | +| Ein Fehler nach **Allow** | Der Link funktioniert nur einmal und läuft nach 10 Minuten ab – starte erneut vom Client | +| Ein erwartetes Tool fehlt | Du besitzt die zugehörige Berechtigung in dieser Organisation nicht. Wende dich an einen Admin. Du musst dich nicht erneut verbinden, sobald du sie hast | +| Der Client fordert dich wiederholt zur Anmeldung auf | Die Verbindung wurde widerrufen, du hast die Organisation verlassen oder sie war 90 Tage lang nicht genutzt. Verbinde dich erneut | +| „You have 5 connected apps" | Widerrufe eine App unter **Settings → Integrations → MCP** und verbinde dich dann erneut | + +Noch immer nicht gelöst? Schreib eine E-Mail an [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/de/reference/otel.mdx b/docs/de/reference/otel.mdx new file mode 100644 index 000000000..5a3207c7f --- /dev/null +++ b/docs/de/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "OpenTelemetry für Coding-Agents aktivieren, Datenübertragung prüfen und frühere Einstellungen wiederherstellen." +icon: "radio" +--- + +`failproofai otel` konfiguriert die optionale OpenTelemetry-Berichterstattung an Failproof AI Cloud. Verbinden Sie zunächst Ihren Rechner mit `failproofai config` und bitten Sie einen Organisations-Admin, unter **Settings → OpenTelemetry** die Funktion zu aktivieren. + +Die interaktive Einrichtung fragt nach dem Cloud-Schlüsselfeld und der Agent-Auswahl nach OpenTelemetry. Dieser optionale Schritt ist standardmäßig auf „Nein" gesetzt. Wählen Sie „Ja", um OTEL-Agents auszuwählen; derselbe Aktivierungscode wird ausgeführt, nachdem die Verbindung gespeichert wurde. Ein Abbruch mit Esc vor Abschluss der Einrichtung ändert nichts. Unbeaufsichtigte Einrichtung, ein übergebener Schlüssel, der Open-Source-Modus sowie das Beibehalten einer gespeicherten Verbindung aktivieren OpenTelemetry nicht. + +## Einen Agent aktivieren + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Die unterstützten Agents sind `claude`, `codex` und `copilot` (VS Code). Die Copilot-Einrichtung erfordert eine VS-Code-Executable oder eine installierte Copilot-Erweiterung. Ein verwaistes Einstellungsverzeichnis allein genügt nicht; die Einrichtung überspringt Copilot, wenn keines von beidem gefunden wird. + +`--local` sendet an den lokalen Relay statt direkt an Cloud. Copilot verwendet den Relay automatisch, da dessen Einstellungen keinen Authentifizierungs-Header speichern können. + +Der Relay lauscht ausschließlich auf Ihrem Rechner. Ihr konfigurierter Failproof AI-Daemon übernimmt die Änderung innerhalb weniger Sekunden; ein Neustart ist nicht erforderlich. Falls eine andere Anwendung den Relay-Port belegt, meldet der Status ihn als inaktiv, während der Daemon weiterläuft. + + +Die Texterfassung ist standardmäßig aktiviert. Fügen Sie `--no-content` hinzu, um Prompts und Tool-Details wegzulassen. Agent-Versionen können unterschiedliche Inhaltskontrollen bereitstellen; prüfen Sie, was Ihr Agent exportiert, bevor Sie ihn mit sensiblen Daten verwenden. + + +Codex exportiert ausschließlich Gesprächsprotokolle, keine internen Laufzeit-Traces oder Metriken. Ein explizites `log_user_prompt = false` in Ihrer Codex-Konfiguration bleibt deaktiviert; bei der Aktivierung wird ein Hinweis ausgegeben, wenn diese Einstellung beibehalten wird. + +### Einen Berichtspfad wählen + +Wenn die Transkript-Berichterstattung für einen Agent aktiv ist, fragt die Einrichtung: + +> failproofai sendet Claude Code-Sitzungen bereits an Cloud. Sollen diese stattdessen per OTEL gesendet werden? Der Transkript-Upload für Claude Code wird dann eingestellt. + +Der Standardwert ist „Nein". `--yes` akzeptiert den Wechsel ohne Nachfrage. Andere Agents und die Richtliniendurchsetzung sind davon nicht betroffen. + +Die Codex-Einrichtung wartet darauf, dass der Daemon die Collector-Änderung bestätigt, bevor die Exporter-Einstellungen geschrieben werden. Läuft die Bestätigung ab, warnt die Einrichtung Sie, vor dem Start von Codex zu warten. + +Config v2 speichert die gespeicherte Tracing-Liste unter `agents.selected` (und den Erkennungsverlauf unter `agents.seen`). Die agentenbezogene Transkript-Präferenz verbleibt unter `collector.agents..sessions`, der OTEL-Besitz unter `otel.agents` und die Relay-Einstellungen unter `collector.otlp.enabled` / `collector.otlp.port`. Diese getrennten Schlüssel halten alte OTEL-Konfigurationen lesbar: Die Einrichtung kann die Tracing-Liste ändern, ohne die Transport-Präferenz oder den für die Wiederherstellung der Agent-Einstellungen benötigten Zustand zu verlieren. + +## Einrichtung prüfen + +```bash +failproofai otel status +``` + +Der Status zeigt jeden Agent, ob seine Einstellungen von Failproof AI verwaltet werden, sein Ziel, den Organisations-Ingest-Schalter, den Relay-Status und das letzte Relay-Upload-Ergebnis. + +`unknown` beim Organisations-Schalter bedeutet, dass der Server diesen nicht bereitgestellt hat oder nicht erreichbar war. Dies ist kein Fehler und verhindert keine Konfiguration auf einer älteren Cloud-Version. + +Unterstützt Cloud noch kein OTEL, behält der Relay abgelehnte Exporte, anstatt sie zu verwerfen. Ist der Organisations-Ingest deaktiviert, schreibt `enable` nichts und beendet sich mit einem Fehler; bitten Sie einen Admin, diesen zuerst zu aktivieren. + +## Konfiguration für eine Anwendung ausgeben + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +Die Ausgabe ist ein Shell-Umgebungsblock für einen OTLP/HTTP-Exporter. Die Cloud-Ausgabe setzt `OTEL_EXPORTER_OTLP_ENDPOINT` auf den OTLP-Basispfad von Cloud, `https:///otel`, und der Exporter hängt `/v1/` an; eine signalspezifische Variable wie `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` benötigt die vollständige URL `https:///otel/v1/logs`. Die lokale Ausgabe zeigt auf den Relay, `http://127.0.0.1:`. Die Cloud-Ausgabe enthält den konfigurierten API-Schlüssel; behandeln Sie ihn als Geheimnis. Die lokale Ausgabe lässt den Schlüssel weg. Um die lokale Ausgabe zu verwenden, aktivieren Sie zunächst einen lokalen Agent, damit der Relay läuft. + +## Frühere Einstellungen wiederherstellen + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Deaktivieren stellt nur die von Failproof AI geschriebenen Einstellungen wieder her, behält nicht verwandte Änderungen und stellt die frühere Transkript-Berichtswahl jedes Agents wieder her. Wenn der letzte verwaltete lokale Agent deaktiviert wird, stellt der Relay die Annahme von Exporten ein. + +Für Codex zeichnet das Deaktivieren außerdem `collector.agents.codex.sessions_resume_after` (Epoch-Millisekunden) auf. Vorhandene Rollout-Bytes gelten als zugestellt, sodass mit OTEL erfasste Sitzungen nicht erneut hochgeladen werden; spätere Ergänzungen fließen weiterhin durch die Transkript-Berichterstattung. + +Jeder Befehl unterstützt `--help`. Weitere Anwendungs- und Coding-Agent-Beispiele finden Sie unter [OpenTelemetry in Cloud](/de/agenteye/opentelemetry). \ No newline at end of file diff --git a/docs/de/reference/slack.mdx b/docs/de/reference/slack.mdx new file mode 100644 index 000000000..86d3818ec --- /dev/null +++ b/docs/de/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack-App" +description: "Stelle dem Failproof Assistant Fragen aus Slack, erhalte Diagramme im Thread und genehmige Änderungen per Schaltfläche." +icon: "slack" +--- + +Stelle dem [Failproof Assistant](/de/sessions/assistant) Fragen direkt aus Slack. Erwähne die App in einem Channel, schreibe ihr eine Direktnachricht oder verwende `/failproof `. Antworten nutzen **deine eigenen** Failproof AI-Berechtigungen, Diagramme erscheinen im Thread, und alles, was eine Änderung vornehmen würde, bedarf zuerst deiner Genehmigung. + +Es gibt eine offizielle App. Sie funktioniert gleich, egal ob deine Failproof AI Cloud gehostet oder selbst gehostet wird. + + + Antworten werden von KI-Modellen generiert und können ungenau sein. Überprüfe alles Wichtige anhand der verlinkten Quelldaten. + + +## Workspace verbinden + +Du benötigst die `settings:write`-Berechtigung in Failproof AI und musst in Slack Workspace-Administrator oder -Inhaber sein oder die Person, die die App hinzufügt. + + + + 1. Gehe zu **Einstellungen → Integrationen** und wähle **Add to Slack**. + 2. Genehmige die App in Slack. + 3. Bestätige in Failproof AI, den Workspace mit deiner Organisation zu verbinden. + + + 1. Füge die App hinzu und öffne dann ihren **Home**-Tab. + 2. Wähle **Continue with FailproofAI Cloud** oder **Use my own URL** und gib die Adresse ein, bei der du dich anmeldest. + 3. Klicke auf die Weiter-Schaltfläche, melde dich an, wähle die Organisation aus und bestätige. Der Link kann nur einmal verwendet werden und läuft nach 10 Minuten ab. + + + +Ein Workspace wird mit einer Organisation verbunden, und eine Organisation mit einem Workspace. + +Noch kein Konto? [Erstelle zuerst eines](https://app.befailproof.ai/login), dann verbinde es. + +## Deine Identität in Slack + +Beim ersten Mal, wenn du fragst, ermittelt die App, welches Mitglied du bist: + +- **Automatisch per E-Mail**, wenn du vollständiges Mitglied des verbundenen Workspace bist, deine Slack-E-Mail bestätigt ist und genau ein Mitglied der Organisation diese E-Mail-Adresse verwendet. +- **Andernfalls** erhältst du eine private Schaltfläche **Link your account**, die Failproof AI öffnet und deinen Slack-Benutzer mit deinem Konto verknüpft. + +## Eine Frage stellen + +| Wo | Wie | +| --- | --- | +| Ein Channel | Erwähne die App. Antworte in ihrem Thread, um fortzufahren – ohne erneute Erwähnung | +| Eine Direktnachricht | Schreibe der App eine Nachricht | +| Eine Gruppen-Direktnachricht, in der die App ist | Erwähne sie, antworte dann in ihrem Thread, um fortzufahren | +| Ein Slack-Connect-Channel | Erwähne die App | +| Jede Unterhaltung, in der die App ist | `/failproof ` startet einen Thread mit der Antwort | +| `/failproof help` | Zeige, was die App kann | +| `/failproof status` | Zeige, welche Organisation verbunden ist und als wer du verknüpft bist | +| `/failproof link` | Zeige, mit welchem Failproof AI-Konto du verknüpft bist | + +Ein Thread ist eine Unterhaltung. Kollegen können die App im selben Thread erwähnen, und sie antwortet jedem von ihnen mit dessen eigenen Berechtigungen. Nur die Person, die den Thread gestartet hat, kann ihn ohne Erwähnung fortführen. + +Wenn die Antwort Daten enthält, veröffentlicht die App ein Diagramm oder eine Tabelle mit einem Link, um sie in Failproof AI zu öffnen. + +## Änderungen genehmigen + +Jede Änderung, die der Assistant vornimmt, zeigt zuerst die Schaltflächen **Approve** und **Cancel** an, und Slack fragt noch einmal vor **Approve** nach. Nur die Person, die gefragt hat, kann darauf antworten; die Schaltflächen laufen nach 5 Minuten ab, und die Änderung wird mit den Berechtigungen dieser Person vorgenommen. + +Aus Slack heraus kann der Assistant gespeicherte Abfragen und Dashboards, Evaluierungen, Benachrichtigungen, Prüfungen, Issues und Richtlinien ändern sowie Code-Korrekturen vorschlagen – jeweils sofern du die entsprechende Berechtigung hast. API-Schlüssel, Benutzer oder Einstellungen kann er nicht ändern. + +## Link-Vorschauen + +Links zu Failproof AI-Issues, -Sitzungen und -Evaluierungen, die in Slack eingefügt werden, werden auf gehosteten Failproof AI Cloud-Instanzen als Karten eingebettet. Eine Karte zeigt nur das, was die Person sehen kann, die sie ausgelöst hat. Links zu einer selbst gehosteten Adresse werden nicht eingebettet, obwohl Karten in den eigenen Antworten des Assistants weiterhin erscheinen. + +## Slack-Connect-Channels + +Personen aus einem anderen Workspace können die App nutzen, wenn sie Mitglieder der Organisation sind und ihr Konto verknüpft haben. Antworten sind für alle in der Unterhaltung sichtbar, auch für Personen, die keine Mitglieder deiner Organisation sind – frage also dort, wo alle die Antwort sehen können. + +Die App antwortet erst, wenn jemand aus jedem anderen Workspace im Channel sein Konto mit der Organisation verknüpft hat. Bis dahin teilt sie der fragenden Person mit, warum. + +## Angefragte Berechtigungen der App + +| Slack-Berechtigung | Warum | +| --- | --- | +| `app_mentions:read` | Erkennen, wenn jemand die App erwähnt | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Direktnachrichten und Antworten in den Threads der App empfangen. Die App ignoriert andere Nachrichten und liest niemals vergangene Nachrichten einer Unterhaltung | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Prüfen, in welcher Art von Unterhaltung sie sich befindet, damit sie weiß, wer eine Antwort sehen kann | +| `chat:write` | Antworten und Genehmigungsschaltflächen veröffentlichen | +| `commands` | `/failproof` bereitstellen | +| `files:write` | Diagramme veröffentlichen | +| `links:read`, `links:write` | Vorschauen für eingefügte Failproof AI-Links anzeigen | +| `users:read`, `users:read.email` | Dich deinem Failproof AI-Konto zuordnen und Namen anzeigen | + +## Verbindung trennen + +Gehe zu **Einstellungen → Integrationen** und wähle **Disconnect**, verwende **Disconnect** im **Home**-Tab der App oder entferne die App aus Slack. + +Jede dieser Aktionen löscht die Verbindung des Workspace, das Bot-Token, verknüpfte Konten und Thread-Einträge. Vergangene Slack-Unterhaltungen bleiben im Dashboard lesbar. Die Organisation kann anschließend sofort einen beliebigen Workspace verbinden. + +## Daten und Datenschutz + +Fragen und Antworten werden als Unterhaltungen im Dashboard deiner Organisation gespeichert, unter der Person, die den Thread gestartet hat. Slack-Daten werden niemals zum Training von KI-Modellen verwendet. Weitere Informationen dazu, was die App empfängt und wie lange es gespeichert wird, findest du in der [Datenschutzerklärung](https://befailproof.ai/privacy/). + +## Fehlerbehebung + +| Was du siehst | Was zu tun ist | +| --- | --- | +| „This workspace isn't connected to a FailproofAI Cloud yet." | Ein Workspace-Administrator öffnet den **Home**-Tab der App und wählt eine aus | +| „This link expired or was already used." | Wähle deine Cloud erneut im **Home**-Tab für einen neuen Link | +| „This org is already connected to a Slack workspace." | Trenne die Verbindung zuerst in den Einstellungen | +| „That Slack workspace is connected to another org." | Trenne sie zuerst von dieser Organisation | +| „Link your account to use the assistant." | Klicke auf die Schaltfläche und bestätige in Failproof AI | +| Die App antwortet nicht in einer Gruppen-Direktnachricht | Füge die App erneut zu Slack hinzu, um ihre Gruppenberechtigungen zu erteilen. Deine Verbindung bleibt erhalten | +| „I won't post answers from your organization here" | Jemand in diesem Workspace, der Mitglied der Organisation ist, erwähnt die App und verknüpft sein Konto | + +Immer noch nicht weiter? Schreibe eine E-Mail an [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/de/sessions/sentiment.mdx b/docs/de/sessions/sentiment.mdx new file mode 100644 index 000000000..b15db7db0 --- /dev/null +++ b/docs/de/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Stimmungsanalyse" +description: "Finden Sie frustrierte, verwirrte und korrigierende Nachrichten mit Jev-Stimmungswerten." +icon: "smile" +--- + +Jev bewertet jede Nachricht, die eine Person an Ihre Agents sendet, auf einer Skala von 0 bis 100 für vier Gefühle — **wütend**, **frustriert**, **glücklich** und **verwirrt** — sowie drei Signale zur Leistung des Agents: + +- **Korrigierend**: Die Person sagt, dass der Agent etwas falsch gemacht hat. +- **Gelöst**: Die Person bestätigt, dass der Agent ihr Problem gelöst hat. +- **Zweifelnd**: Die Person hinterfragt, ob die Antwort des Agents korrekt ist oder ob er die Aufgabe tatsächlich erledigt hat. + +Nutzen Sie die Stimmungsanalyse, um Gespräche zu finden, in denen Menschen die Geduld verlieren, Agents, die ständig korrigiert werden, und Antworten, die gut ankommen. Dies ist eine integrierte Jev-Bewertung; Sie müssen keine eigene Evaluation erstellen. Für eigene Fragen mit festen Antworten [erstellen Sie eine Jev-Evaluation](/de/evaluations/jev). + + + Die Stimmungsanalyse ist deaktiviert, bis ein Administrator sie für die Organisation einschaltet. Jev stellt pro Nachricht eine Bewertungsanfrage und erhält dabei die Nachricht zusammen mit der vorherigen Agent-Antwort. Die Bewertung wird über das Modellbudget Ihrer Organisation abgerechnet. + + +## Aktivierung + +1. Navigieren Sie zu **Administration → Einstellungen**. +2. Schalten Sie unter **Stimmungsanalyse für menschliche Eingaben** die Option **ein** und speichern Sie. + +Nachrichten vom letzten Tag werden zuerst bewertet. Danach werden neue Nachrichten innerhalb von ein bis zwei Minuten nach dem Eingang bewertet. + +## Ein Gespräch zur Überprüfung finden + +Öffnen Sie **Beobachten → Stimmung**. Filtern Sie nach Zeitraum, Umgebung, Agent oder Sitzungs-ID. Die Kopfzeile zeigt die Anzahl der Nachrichten und Sitzungen, wie viele Nachrichten **markiert** sind, und das häufigste Signal. Eine Nachricht wird markiert, wenn ein Wert für wütend, frustriert, korrigierend, verwirrt oder zweifelnd 35 von 100 erreicht. + +![Das Stimmungs-Dashboard mit Nachrichten- und Sitzungsanzahl, markierten Nachrichten und Jev-Werten im Zeitverlauf.](/images/dashboard/sentiment-overview.png) + +Verwenden Sie **Wert über Zeit**, um Signale zu vergleichen. Wählen Sie die anzuzeigenden Werte aus und klicken Sie dann auf einen Punkt, um die Nachrichten dieses Zeitabschnitts zu sehen. Die Tabelle **Nach Agent** zeigt, wo ein Signal konzentriert ist. Sortieren Sie unter **Nachrichten** nach dem stärksten negativen Wert oder wählen Sie einen einzelnen Wert aus. Öffnen Sie eine Nachricht in ihrer Sitzung, um das umgebende Gespräch zu lesen, bevor Sie entscheiden, was schiefgelaufen ist. + +![Die Stimmungs-Nachrichtenliste, sortiert nach dem stärksten negativen Wert, mit einem Link zur jeweiligen Quellsitzung.](/images/dashboard/sentiment-messages.png) + +## Welche Nachrichten bewertet werden + +Nur Nachrichten, die eine Person geschrieben hat: + +- Nachrichten, die Ihre benutzerdefinierten Agents als menschliche Eingabe über das SDK erfassen. +- Eingaben in Claude Code, Codex, OpenCode, pi, Hermes und OpenClaw, wenn Sitzungsprotokolle übermittelt werden (Standardeinstellung). Geplante Aufgaben, eingefügte Anweisungen, Übergaben an Sub-Agents und andere Texte, die die Laufzeitumgebung des Agents selbst schreibt, werden nicht bewertet. Ebenso werden nicht-interaktive Ausführungen wie `claude -p`, `codex exec` und `hermes -z` nicht bewertet: Diese Eingaben wurden von einem Skript geschrieben, nicht von einer Person. + +Die Bewertung beurteilt die eigenen Worte der Person. Eine kurze, knappe Anweisung wie „korrigiere es" wird nicht als Wut gewertet, und das Stellen einer Frage gilt nicht als Verwirrung. Eine neue Anfrage ist keine Korrektur, und ein einfaches Dankeschön allein zählt nicht als gelöst. \ No newline at end of file diff --git a/docs/de/start/use-jev.mdx b/docs/de/start/use-jev.mdx new file mode 100644 index 000000000..1d5c201fc --- /dev/null +++ b/docs/de/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Jev verwenden" +description: "Jev-Evaluierungen für abgeschlossene Sitzungen oder Jev-Richtlinien für die Live-Überprüfung von Tool-Aufrufen einrichten." +icon: "sparkles" +--- + +Jev hilft an zwei Punkten während eines Agent-Runs: Bewerte eine abgeschlossene Sitzung anhand bekannter Antworten, oder überprüfe einen Tool-Aufruf im Kontext dessen, was du den Agenten zu tun gebeten hast. + + + + Verwende ein Jev-Eval, wenn eine abgeschlossene Sitzung anhand einer Frage mit wenigen bekannten Antworten bewertet werden kann, zum Beispiel: „Hat der Kunde nach einer Rückerstattung gefragt? Antworte mit Ja oder Nein." Es hilft dir, Muster über Sitzungen hinweg zu erkennen. + + ## Ein Eval erstellen + + Öffne im Cloud-Dashboard **Analyze → eval authoring → new eval**. Gib eine Frage mit fester Antwort ein, wähle **draft**, und prüfe, ob ein Classifier-Score ausgewählt wurde. [Teste es](/de/evaluations/test) mit echten Sitzungen und veröffentliche es anschließend. + + ![Das gemeinsame Eval-Authoring-Formular, in dem du eine Frage beschreibst, den Entwurf überprüfst und ihn veröffentlichst. Dieser Screenshot zeigt einen Code-Entwurf; verwende für Jev eine Frage mit fester Antwort.](/images/dashboard/eval-authoring-draft.png) + + ## Die Bewertungen lesen + + Nachdem eine neue Sitzung abgeschlossen ist, öffne **Observe → Evaluations** oder verwende die Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + Die CLI liest Bewertungen; das Erstellen eines Jev-Evals erfolgt derzeit über das Dashboard. Siehe [Jev evaluations](/de/evaluations/jev) für Fragetypen und Beispiele. + + + Verwende die Jev-Richtlinienprüfung, wenn eine auf String-Matching basierende Richtlinie den Kontext deiner Anfrage benötigt, um zu entscheiden, ob ein Tool-Aufruf sicher ist. Beginne im **observe**-Modus, damit du Jevs Antworten inspizieren kannst, während deine installierten Richtlinien weiterhin über jeden Aufruf entscheiden. + + Jevs Prüfungen stammen aus einem Paket; Failproof AI liefert keines mit. Bis du eines installierst, stellt Jev keine Fragen – auch wenn es konfiguriert ist: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Cloud Jev einrichten + + Öffne im Cloud-Dashboard **Administration → Keys** und erstelle einen Schlüssel mit dem **machine**-Preset. Verwende ihn mit `failproofai config` wie im [Quickstart](/de/start/quickstart) beschrieben. Auf einem Rechner ohne bestehende Jev-Konfiguration aktiviert dies Cloud Jev im observe-Modus. Überprüfe die Verbindung mit: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Eigenen Endpunkt verwenden + + Öffne im lokalen Dashboard **Settings → Jev**. Wähle den Anbieter aus, füge dessen Token ein, wähle **observe** und aktiviere Jev. + + ![Das lokale Jev-Einstellungsfenster mit einem Anbieter, einem Token-Feld und aktiviertem observe-Modus.](/images/dashboard/jev-settings.png) + + Oder konfiguriere und teste deinen Endpunkt über ein Terminal: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Bitte einen verknüpften Agenten, sein Datei-Lese-Tool auf `README.md` anzuwenden. Bestätige, dass dieser Tool-Aufruf in der Sitzung erscheint, und inspiziere ihn dann unter **Policies → Activity** im lokalen Dashboard. Sobald die observe-Ergebnisse korrekt aussehen, erklärt [Jev policies](/de/policies/jev), wann eine Durchsetzung sinnvoll ist. Einzelheiten zu Anbietern und Konfiguration findest du in der [Integrationsreferenz](/de/reference/jev). + + \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index bbd01838b..f2b79d9a5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -82,6 +82,7 @@ "start/first-policy", "start/setup", "start/concepts", + "start/use-jev", { "group": "Starter templates", "expanded": false, @@ -121,6 +122,7 @@ "group": "Plug in your agent", "pages": [ "start/integrations", + "agenteye/opentelemetry", "start/integrations/custom-agents", "start/integrations/langchain", "start/integrations/crewai", @@ -149,6 +151,7 @@ { "group": "Find and manage failures", "pages": [ + "sessions/sentiment", "audits/overview", "audits/local-audit", "audits/setup", @@ -169,12 +172,14 @@ { "group": "Prevent repeat failures", "pages": [ - "policies/overview" + "policies/overview", + "policies/jev" ] }, { "group": "Get a policy", "pages": [ + "policies/authority", "policies/editor", "policies/packs" ] @@ -202,7 +207,8 @@ "admin/usage", "admin/keys-and-permissions", "admin/users-and-organizations", - "admin/settings-and-security" + "admin/settings-and-security", + "admin/product-analytics" ] } ] @@ -217,16 +223,34 @@ "reference/overview", "reference/harnesses", "reference/custom-agents", + "reference/custom-agents-typescript", "reference/evaluator-sdk", "reference/policy-sdk", "reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "reference/mcp", + "reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "reference/jev", + "reference/jev-evaluations", + "reference/jev-providers", + "reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "reference/failproof-cli", + "reference/otel", "reference/local-dashboard", "policies/local-configuration", "reference/cloud-cli", @@ -263,6 +287,7 @@ "zh/start/first-policy", "zh/start/setup", "zh/start/concepts", + "zh/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -302,6 +327,7 @@ "group": "Plug in your agent", "pages": [ "zh/start/integrations", + "zh/agenteye/opentelemetry", "zh/start/integrations/custom-agents", "zh/start/integrations/langchain", "zh/start/integrations/crewai", @@ -320,6 +346,8 @@ "pages": [ "zh/evaluations/overview", "zh/evaluations/write", + "zh/evaluations/judge", + "zh/evaluations/jev", "zh/evaluations/test", "zh/evaluations/deploy", "zh/sessions/evaluations" @@ -328,6 +356,7 @@ { "group": "Find and manage failures", "pages": [ + "zh/sessions/sentiment", "zh/audits/overview", "zh/audits/local-audit", "zh/audits/setup", @@ -348,12 +377,14 @@ { "group": "Prevent repeat failures", "pages": [ - "zh/policies/overview" + "zh/policies/overview", + "zh/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "zh/policies/authority", "zh/policies/editor", "zh/policies/packs" ] @@ -381,7 +412,8 @@ "zh/admin/usage", "zh/admin/keys-and-permissions", "zh/admin/users-and-organizations", - "zh/admin/settings-and-security" + "zh/admin/settings-and-security", + "zh/admin/product-analytics" ] } ] @@ -396,16 +428,34 @@ "zh/reference/overview", "zh/reference/harnesses", "zh/reference/custom-agents", + "zh/reference/custom-agents-typescript", "zh/reference/evaluator-sdk", "zh/reference/policy-sdk", "zh/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "zh/reference/mcp", + "zh/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "zh/reference/jev", + "zh/reference/jev-evaluations", + "zh/reference/jev-providers", + "zh/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "zh/reference/failproof-cli", + "zh/reference/otel", "zh/reference/local-dashboard", "zh/policies/local-configuration", "zh/reference/cloud-cli", @@ -436,6 +486,7 @@ "ja/start/first-policy", "ja/start/setup", "ja/start/concepts", + "ja/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -475,6 +526,7 @@ "group": "Plug in your agent", "pages": [ "ja/start/integrations", + "ja/agenteye/opentelemetry", "ja/start/integrations/custom-agents", "ja/start/integrations/langchain", "ja/start/integrations/crewai", @@ -493,6 +545,8 @@ "pages": [ "ja/evaluations/overview", "ja/evaluations/write", + "ja/evaluations/judge", + "ja/evaluations/jev", "ja/evaluations/test", "ja/evaluations/deploy", "ja/sessions/evaluations" @@ -501,6 +555,7 @@ { "group": "Find and manage failures", "pages": [ + "ja/sessions/sentiment", "ja/audits/overview", "ja/audits/local-audit", "ja/audits/setup", @@ -521,12 +576,14 @@ { "group": "Prevent repeat failures", "pages": [ - "ja/policies/overview" + "ja/policies/overview", + "ja/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "ja/policies/authority", "ja/policies/editor", "ja/policies/packs" ] @@ -554,7 +611,8 @@ "ja/admin/usage", "ja/admin/keys-and-permissions", "ja/admin/users-and-organizations", - "ja/admin/settings-and-security" + "ja/admin/settings-and-security", + "ja/admin/product-analytics" ] } ] @@ -569,16 +627,34 @@ "ja/reference/overview", "ja/reference/harnesses", "ja/reference/custom-agents", + "ja/reference/custom-agents-typescript", "ja/reference/evaluator-sdk", "ja/reference/policy-sdk", "ja/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "ja/reference/mcp", + "ja/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "ja/reference/jev", + "ja/reference/jev-evaluations", + "ja/reference/jev-providers", + "ja/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "ja/reference/failproof-cli", + "ja/reference/otel", "ja/reference/local-dashboard", "ja/policies/local-configuration", "ja/reference/cloud-cli", @@ -609,6 +685,7 @@ "ko/start/first-policy", "ko/start/setup", "ko/start/concepts", + "ko/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -648,6 +725,7 @@ "group": "Plug in your agent", "pages": [ "ko/start/integrations", + "ko/agenteye/opentelemetry", "ko/start/integrations/custom-agents", "ko/start/integrations/langchain", "ko/start/integrations/crewai", @@ -666,6 +744,8 @@ "pages": [ "ko/evaluations/overview", "ko/evaluations/write", + "ko/evaluations/judge", + "ko/evaluations/jev", "ko/evaluations/test", "ko/evaluations/deploy", "ko/sessions/evaluations" @@ -674,6 +754,7 @@ { "group": "Find and manage failures", "pages": [ + "ko/sessions/sentiment", "ko/audits/overview", "ko/audits/local-audit", "ko/audits/setup", @@ -694,7 +775,8 @@ { "group": "Prevent repeat failures", "pages": [ - "ko/policies/overview" + "ko/policies/overview", + "ko/policies/jev" ] }, { @@ -727,7 +809,8 @@ "ko/admin/usage", "ko/admin/keys-and-permissions", "ko/admin/users-and-organizations", - "ko/admin/settings-and-security" + "ko/admin/settings-and-security", + "ko/admin/product-analytics" ] } ] @@ -742,16 +825,33 @@ "ko/reference/overview", "ko/reference/harnesses", "ko/reference/custom-agents", + "ko/reference/custom-agents-typescript", "ko/reference/evaluator-sdk", "ko/reference/policy-sdk", "ko/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "ko/reference/mcp", + "ko/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "ko/reference/jev", + "ko/reference/jev-evaluations", + "ko/reference/jev-providers" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "ko/reference/failproof-cli", + "ko/reference/otel", "ko/reference/local-dashboard", "ko/policies/local-configuration", "ko/reference/cloud-cli", @@ -782,6 +882,7 @@ "es/start/first-policy", "es/start/setup", "es/start/concepts", + "es/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -821,6 +922,7 @@ "group": "Plug in your agent", "pages": [ "es/start/integrations", + "es/agenteye/opentelemetry", "es/start/integrations/custom-agents", "es/start/integrations/langchain", "es/start/integrations/crewai", @@ -839,6 +941,8 @@ "pages": [ "es/evaluations/overview", "es/evaluations/write", + "es/evaluations/judge", + "es/evaluations/jev", "es/evaluations/test", "es/evaluations/deploy", "es/sessions/evaluations" @@ -847,6 +951,7 @@ { "group": "Find and manage failures", "pages": [ + "es/sessions/sentiment", "es/audits/overview", "es/audits/local-audit", "es/audits/setup", @@ -867,12 +972,14 @@ { "group": "Prevent repeat failures", "pages": [ - "es/policies/overview" + "es/policies/overview", + "es/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "es/policies/authority", "es/policies/editor", "es/policies/packs" ] @@ -900,7 +1007,8 @@ "es/admin/usage", "es/admin/keys-and-permissions", "es/admin/users-and-organizations", - "es/admin/settings-and-security" + "es/admin/settings-and-security", + "es/admin/product-analytics" ] } ] @@ -915,16 +1023,34 @@ "es/reference/overview", "es/reference/harnesses", "es/reference/custom-agents", + "es/reference/custom-agents-typescript", "es/reference/evaluator-sdk", "es/reference/policy-sdk", "es/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "es/reference/mcp", + "es/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "es/reference/jev", + "es/reference/jev-evaluations", + "es/reference/jev-providers", + "es/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "es/reference/failproof-cli", + "es/reference/otel", "es/reference/local-dashboard", "es/policies/local-configuration", "es/reference/cloud-cli", @@ -955,6 +1081,7 @@ "pt-br/start/first-policy", "pt-br/start/setup", "pt-br/start/concepts", + "pt-br/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -994,6 +1121,7 @@ "group": "Plug in your agent", "pages": [ "pt-br/start/integrations", + "pt-br/agenteye/opentelemetry", "pt-br/start/integrations/custom-agents", "pt-br/start/integrations/langchain", "pt-br/start/integrations/crewai", @@ -1012,6 +1140,8 @@ "pages": [ "pt-br/evaluations/overview", "pt-br/evaluations/write", + "pt-br/evaluations/judge", + "pt-br/evaluations/jev", "pt-br/evaluations/test", "pt-br/evaluations/deploy", "pt-br/sessions/evaluations" @@ -1020,6 +1150,7 @@ { "group": "Find and manage failures", "pages": [ + "pt-br/sessions/sentiment", "pt-br/audits/overview", "pt-br/audits/local-audit", "pt-br/audits/setup", @@ -1040,12 +1171,14 @@ { "group": "Prevent repeat failures", "pages": [ - "pt-br/policies/overview" + "pt-br/policies/overview", + "pt-br/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "pt-br/policies/authority", "pt-br/policies/editor", "pt-br/policies/packs" ] @@ -1073,7 +1206,8 @@ "pt-br/admin/usage", "pt-br/admin/keys-and-permissions", "pt-br/admin/users-and-organizations", - "pt-br/admin/settings-and-security" + "pt-br/admin/settings-and-security", + "pt-br/admin/product-analytics" ] } ] @@ -1088,16 +1222,34 @@ "pt-br/reference/overview", "pt-br/reference/harnesses", "pt-br/reference/custom-agents", + "pt-br/reference/custom-agents-typescript", "pt-br/reference/evaluator-sdk", "pt-br/reference/policy-sdk", "pt-br/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "pt-br/reference/mcp", + "pt-br/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "pt-br/reference/jev", + "pt-br/reference/jev-evaluations", + "pt-br/reference/jev-providers", + "pt-br/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "pt-br/reference/failproof-cli", + "pt-br/reference/otel", "pt-br/reference/local-dashboard", "pt-br/policies/local-configuration", "pt-br/reference/cloud-cli", @@ -1128,6 +1280,7 @@ "de/start/first-policy", "de/start/setup", "de/start/concepts", + "de/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -1167,6 +1320,7 @@ "group": "Plug in your agent", "pages": [ "de/start/integrations", + "de/agenteye/opentelemetry", "de/start/integrations/custom-agents", "de/start/integrations/langchain", "de/start/integrations/crewai", @@ -1185,6 +1339,8 @@ "pages": [ "de/evaluations/overview", "de/evaluations/write", + "de/evaluations/judge", + "de/evaluations/jev", "de/evaluations/test", "de/evaluations/deploy", "de/sessions/evaluations" @@ -1193,6 +1349,7 @@ { "group": "Find and manage failures", "pages": [ + "de/sessions/sentiment", "de/audits/overview", "de/audits/local-audit", "de/audits/setup", @@ -1213,12 +1370,14 @@ { "group": "Prevent repeat failures", "pages": [ - "de/policies/overview" + "de/policies/overview", + "de/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "de/policies/authority", "de/policies/editor", "de/policies/packs" ] @@ -1246,7 +1405,8 @@ "de/admin/usage", "de/admin/keys-and-permissions", "de/admin/users-and-organizations", - "de/admin/settings-and-security" + "de/admin/settings-and-security", + "de/admin/product-analytics" ] } ] @@ -1261,16 +1421,34 @@ "de/reference/overview", "de/reference/harnesses", "de/reference/custom-agents", + "de/reference/custom-agents-typescript", "de/reference/evaluator-sdk", "de/reference/policy-sdk", "de/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "de/reference/mcp", + "de/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "de/reference/jev", + "de/reference/jev-evaluations", + "de/reference/jev-providers", + "de/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "de/reference/failproof-cli", + "de/reference/otel", "de/reference/local-dashboard", "de/policies/local-configuration", "de/reference/cloud-cli", @@ -1301,6 +1479,7 @@ "fr/start/first-policy", "fr/start/setup", "fr/start/concepts", + "fr/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -1340,6 +1519,7 @@ "group": "Plug in your agent", "pages": [ "fr/start/integrations", + "fr/agenteye/opentelemetry", "fr/start/integrations/custom-agents", "fr/start/integrations/langchain", "fr/start/integrations/crewai", @@ -1358,6 +1538,8 @@ "pages": [ "fr/evaluations/overview", "fr/evaluations/write", + "fr/evaluations/judge", + "fr/evaluations/jev", "fr/evaluations/test", "fr/evaluations/deploy", "fr/sessions/evaluations" @@ -1366,6 +1548,7 @@ { "group": "Find and manage failures", "pages": [ + "fr/sessions/sentiment", "fr/audits/overview", "fr/audits/local-audit", "fr/audits/setup", @@ -1386,12 +1569,14 @@ { "group": "Prevent repeat failures", "pages": [ - "fr/policies/overview" + "fr/policies/overview", + "fr/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "fr/policies/authority", "fr/policies/editor", "fr/policies/packs" ] @@ -1419,7 +1604,8 @@ "fr/admin/usage", "fr/admin/keys-and-permissions", "fr/admin/users-and-organizations", - "fr/admin/settings-and-security" + "fr/admin/settings-and-security", + "fr/admin/product-analytics" ] } ] @@ -1434,16 +1620,34 @@ "fr/reference/overview", "fr/reference/harnesses", "fr/reference/custom-agents", + "fr/reference/custom-agents-typescript", "fr/reference/evaluator-sdk", "fr/reference/policy-sdk", "fr/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "fr/reference/mcp", + "fr/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "fr/reference/jev", + "fr/reference/jev-evaluations", + "fr/reference/jev-providers", + "fr/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "fr/reference/failproof-cli", + "fr/reference/otel", "fr/reference/local-dashboard", "fr/policies/local-configuration", "fr/reference/cloud-cli", @@ -1474,6 +1678,7 @@ "ru/start/first-policy", "ru/start/setup", "ru/start/concepts", + "ru/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -1513,6 +1718,7 @@ "group": "Plug in your agent", "pages": [ "ru/start/integrations", + "ru/agenteye/opentelemetry", "ru/start/integrations/custom-agents", "ru/start/integrations/langchain", "ru/start/integrations/crewai", @@ -1531,6 +1737,8 @@ "pages": [ "ru/evaluations/overview", "ru/evaluations/write", + "ru/evaluations/judge", + "ru/evaluations/jev", "ru/evaluations/test", "ru/evaluations/deploy", "ru/sessions/evaluations" @@ -1539,6 +1747,7 @@ { "group": "Find and manage failures", "pages": [ + "ru/sessions/sentiment", "ru/audits/overview", "ru/audits/local-audit", "ru/audits/setup", @@ -1559,12 +1768,14 @@ { "group": "Prevent repeat failures", "pages": [ - "ru/policies/overview" + "ru/policies/overview", + "ru/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "ru/policies/authority", "ru/policies/editor", "ru/policies/packs" ] @@ -1592,7 +1803,8 @@ "ru/admin/usage", "ru/admin/keys-and-permissions", "ru/admin/users-and-organizations", - "ru/admin/settings-and-security" + "ru/admin/settings-and-security", + "ru/admin/product-analytics" ] } ] @@ -1607,16 +1819,34 @@ "ru/reference/overview", "ru/reference/harnesses", "ru/reference/custom-agents", + "ru/reference/custom-agents-typescript", "ru/reference/evaluator-sdk", "ru/reference/policy-sdk", "ru/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "ru/reference/mcp", + "ru/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "ru/reference/jev", + "ru/reference/jev-evaluations", + "ru/reference/jev-providers", + "ru/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "ru/reference/failproof-cli", + "ru/reference/otel", "ru/reference/local-dashboard", "ru/policies/local-configuration", "ru/reference/cloud-cli", @@ -1647,6 +1877,7 @@ "hi/start/first-policy", "hi/start/setup", "hi/start/concepts", + "hi/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -1686,6 +1917,7 @@ "group": "Plug in your agent", "pages": [ "hi/start/integrations", + "hi/agenteye/opentelemetry", "hi/start/integrations/custom-agents", "hi/start/integrations/langchain", "hi/start/integrations/crewai", @@ -1704,6 +1936,8 @@ "pages": [ "hi/evaluations/overview", "hi/evaluations/write", + "hi/evaluations/judge", + "hi/evaluations/jev", "hi/evaluations/test", "hi/evaluations/deploy", "hi/sessions/evaluations" @@ -1712,6 +1946,7 @@ { "group": "Find and manage failures", "pages": [ + "hi/sessions/sentiment", "hi/audits/overview", "hi/audits/local-audit", "hi/audits/setup", @@ -1732,12 +1967,14 @@ { "group": "Prevent repeat failures", "pages": [ - "hi/policies/overview" + "hi/policies/overview", + "hi/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "hi/policies/authority", "hi/policies/editor", "hi/policies/packs" ] @@ -1765,7 +2002,8 @@ "hi/admin/usage", "hi/admin/keys-and-permissions", "hi/admin/users-and-organizations", - "hi/admin/settings-and-security" + "hi/admin/settings-and-security", + "hi/admin/product-analytics" ] } ] @@ -1780,16 +2018,34 @@ "hi/reference/overview", "hi/reference/harnesses", "hi/reference/custom-agents", + "hi/reference/custom-agents-typescript", "hi/reference/evaluator-sdk", "hi/reference/policy-sdk", "hi/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "hi/reference/mcp", + "hi/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "hi/reference/jev", + "hi/reference/jev-evaluations", + "hi/reference/jev-providers", + "hi/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "hi/reference/failproof-cli", + "hi/reference/otel", "hi/reference/local-dashboard", "hi/policies/local-configuration", "hi/reference/cloud-cli", @@ -1820,6 +2076,7 @@ "tr/start/first-policy", "tr/start/setup", "tr/start/concepts", + "tr/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -1859,6 +2116,7 @@ "group": "Plug in your agent", "pages": [ "tr/start/integrations", + "tr/agenteye/opentelemetry", "tr/start/integrations/custom-agents", "tr/start/integrations/langchain", "tr/start/integrations/crewai", @@ -1877,6 +2135,8 @@ "pages": [ "tr/evaluations/overview", "tr/evaluations/write", + "tr/evaluations/judge", + "tr/evaluations/jev", "tr/evaluations/test", "tr/evaluations/deploy", "tr/sessions/evaluations" @@ -1885,6 +2145,7 @@ { "group": "Find and manage failures", "pages": [ + "tr/sessions/sentiment", "tr/audits/overview", "tr/audits/local-audit", "tr/audits/setup", @@ -1905,12 +2166,14 @@ { "group": "Prevent repeat failures", "pages": [ - "tr/policies/overview" + "tr/policies/overview", + "tr/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "tr/policies/authority", "tr/policies/editor", "tr/policies/packs" ] @@ -1938,7 +2201,8 @@ "tr/admin/usage", "tr/admin/keys-and-permissions", "tr/admin/users-and-organizations", - "tr/admin/settings-and-security" + "tr/admin/settings-and-security", + "tr/admin/product-analytics" ] } ] @@ -1953,16 +2217,34 @@ "tr/reference/overview", "tr/reference/harnesses", "tr/reference/custom-agents", + "tr/reference/custom-agents-typescript", "tr/reference/evaluator-sdk", "tr/reference/policy-sdk", "tr/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "tr/reference/mcp", + "tr/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "tr/reference/jev", + "tr/reference/jev-evaluations", + "tr/reference/jev-providers", + "tr/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "tr/reference/failproof-cli", + "tr/reference/otel", "tr/reference/local-dashboard", "tr/policies/local-configuration", "tr/reference/cloud-cli", @@ -1993,6 +2275,7 @@ "vi/start/first-policy", "vi/start/setup", "vi/start/concepts", + "vi/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -2032,6 +2315,7 @@ "group": "Plug in your agent", "pages": [ "vi/start/integrations", + "vi/agenteye/opentelemetry", "vi/start/integrations/custom-agents", "vi/start/integrations/langchain", "vi/start/integrations/crewai", @@ -2050,6 +2334,8 @@ "pages": [ "vi/evaluations/overview", "vi/evaluations/write", + "vi/evaluations/judge", + "vi/evaluations/jev", "vi/evaluations/test", "vi/evaluations/deploy", "vi/sessions/evaluations" @@ -2058,6 +2344,7 @@ { "group": "Find and manage failures", "pages": [ + "vi/sessions/sentiment", "vi/audits/overview", "vi/audits/local-audit", "vi/audits/setup", @@ -2078,12 +2365,14 @@ { "group": "Prevent repeat failures", "pages": [ - "vi/policies/overview" + "vi/policies/overview", + "vi/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "vi/policies/authority", "vi/policies/editor", "vi/policies/packs" ] @@ -2111,7 +2400,8 @@ "vi/admin/usage", "vi/admin/keys-and-permissions", "vi/admin/users-and-organizations", - "vi/admin/settings-and-security" + "vi/admin/settings-and-security", + "vi/admin/product-analytics" ] } ] @@ -2126,16 +2416,34 @@ "vi/reference/overview", "vi/reference/harnesses", "vi/reference/custom-agents", + "vi/reference/custom-agents-typescript", "vi/reference/evaluator-sdk", "vi/reference/policy-sdk", "vi/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "vi/reference/mcp", + "vi/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "vi/reference/jev", + "vi/reference/jev-evaluations", + "vi/reference/jev-providers", + "vi/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "vi/reference/failproof-cli", + "vi/reference/otel", "vi/reference/local-dashboard", "vi/policies/local-configuration", "vi/reference/cloud-cli", @@ -2166,6 +2474,7 @@ "it/start/first-policy", "it/start/setup", "it/start/concepts", + "it/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -2205,6 +2514,7 @@ "group": "Plug in your agent", "pages": [ "it/start/integrations", + "it/agenteye/opentelemetry", "it/start/integrations/custom-agents", "it/start/integrations/langchain", "it/start/integrations/crewai", @@ -2223,6 +2533,8 @@ "pages": [ "it/evaluations/overview", "it/evaluations/write", + "it/evaluations/judge", + "it/evaluations/jev", "it/evaluations/test", "it/evaluations/deploy", "it/sessions/evaluations" @@ -2231,6 +2543,7 @@ { "group": "Find and manage failures", "pages": [ + "it/sessions/sentiment", "it/audits/overview", "it/audits/local-audit", "it/audits/setup", @@ -2251,12 +2564,14 @@ { "group": "Prevent repeat failures", "pages": [ - "it/policies/overview" + "it/policies/overview", + "it/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "it/policies/authority", "it/policies/editor", "it/policies/packs" ] @@ -2284,7 +2599,8 @@ "it/admin/usage", "it/admin/keys-and-permissions", "it/admin/users-and-organizations", - "it/admin/settings-and-security" + "it/admin/settings-and-security", + "it/admin/product-analytics" ] } ] @@ -2299,16 +2615,34 @@ "it/reference/overview", "it/reference/harnesses", "it/reference/custom-agents", + "it/reference/custom-agents-typescript", "it/reference/evaluator-sdk", "it/reference/policy-sdk", "it/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "it/reference/mcp", + "it/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "it/reference/jev", + "it/reference/jev-evaluations", + "it/reference/jev-providers", + "it/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "it/reference/failproof-cli", + "it/reference/otel", "it/reference/local-dashboard", "it/policies/local-configuration", "it/reference/cloud-cli", @@ -2339,6 +2673,7 @@ "ar/start/first-policy", "ar/start/setup", "ar/start/concepts", + "ar/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -2378,6 +2713,7 @@ "group": "Plug in your agent", "pages": [ "ar/start/integrations", + "ar/agenteye/opentelemetry", "ar/start/integrations/custom-agents", "ar/start/integrations/langchain", "ar/start/integrations/crewai", @@ -2396,6 +2732,8 @@ "pages": [ "ar/evaluations/overview", "ar/evaluations/write", + "ar/evaluations/judge", + "ar/evaluations/jev", "ar/evaluations/test", "ar/evaluations/deploy", "ar/sessions/evaluations" @@ -2404,6 +2742,7 @@ { "group": "Find and manage failures", "pages": [ + "ar/sessions/sentiment", "ar/audits/overview", "ar/audits/local-audit", "ar/audits/setup", @@ -2424,12 +2763,14 @@ { "group": "Prevent repeat failures", "pages": [ - "ar/policies/overview" + "ar/policies/overview", + "ar/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "ar/policies/authority", "ar/policies/editor", "ar/policies/packs" ] @@ -2457,7 +2798,8 @@ "ar/admin/usage", "ar/admin/keys-and-permissions", "ar/admin/users-and-organizations", - "ar/admin/settings-and-security" + "ar/admin/settings-and-security", + "ar/admin/product-analytics" ] } ] @@ -2472,16 +2814,34 @@ "ar/reference/overview", "ar/reference/harnesses", "ar/reference/custom-agents", + "ar/reference/custom-agents-typescript", "ar/reference/evaluator-sdk", "ar/reference/policy-sdk", "ar/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "ar/reference/mcp", + "ar/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "ar/reference/jev", + "ar/reference/jev-evaluations", + "ar/reference/jev-providers", + "ar/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "ar/reference/failproof-cli", + "ar/reference/otel", "ar/reference/local-dashboard", "ar/policies/local-configuration", "ar/reference/cloud-cli", @@ -2512,6 +2872,7 @@ "he/start/first-policy", "he/start/setup", "he/start/concepts", + "he/start/use-jev", { "group": "Starter templates", "expanded": false, @@ -2551,6 +2912,7 @@ "group": "Plug in your agent", "pages": [ "he/start/integrations", + "he/agenteye/opentelemetry", "he/start/integrations/custom-agents", "he/start/integrations/langchain", "he/start/integrations/crewai", @@ -2569,6 +2931,8 @@ "pages": [ "he/evaluations/overview", "he/evaluations/write", + "he/evaluations/judge", + "he/evaluations/jev", "he/evaluations/test", "he/evaluations/deploy", "he/sessions/evaluations" @@ -2577,6 +2941,7 @@ { "group": "Find and manage failures", "pages": [ + "he/sessions/sentiment", "he/audits/overview", "he/audits/local-audit", "he/audits/setup", @@ -2597,12 +2962,14 @@ { "group": "Prevent repeat failures", "pages": [ - "he/policies/overview" + "he/policies/overview", + "he/policies/jev" ] }, { "group": "Get a policy", "pages": [ + "he/policies/authority", "he/policies/editor", "he/policies/packs" ] @@ -2630,7 +2997,8 @@ "he/admin/usage", "he/admin/keys-and-permissions", "he/admin/users-and-organizations", - "he/admin/settings-and-security" + "he/admin/settings-and-security", + "he/admin/product-analytics" ] } ] @@ -2645,16 +3013,34 @@ "he/reference/overview", "he/reference/harnesses", "he/reference/custom-agents", + "he/reference/custom-agents-typescript", "he/reference/evaluator-sdk", "he/reference/policy-sdk", "he/reference/self-hosting" ] }, + { + "group": "Connect your tools", + "pages": [ + "he/reference/mcp", + "he/reference/slack" + ] + }, + { + "group": "Jev reference", + "pages": [ + "he/reference/jev", + "he/reference/jev-evaluations", + "he/reference/jev-providers", + "he/reference/jev-cloud" + ] + }, { "group": "Reference", "expanded": false, "pages": [ "he/reference/failproof-cli", + "he/reference/otel", "he/reference/local-dashboard", "he/policies/local-configuration", "he/reference/cloud-cli", @@ -2701,6 +3087,14 @@ "indexing": "navigable" }, "redirects": [ + { + "source": "/policies/jev-byok", + "destination": "/reference/jev-providers" + }, + { + "source": "/policies/jev-cloud", + "destination": "/reference/jev-cloud" + }, { "source": "/reference/python-sdk", "destination": "/reference/custom-agents" diff --git a/docs/es/admin/product-analytics.mdx b/docs/es/admin/product-analytics.mdx new file mode 100644 index 000000000..ab880ef9e --- /dev/null +++ b/docs/es/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Análisis de producto" +description: "La telemetría de uso que Failproof AI Cloud envía sobre sí mismo, qué nunca se recopila y cómo desactivarla." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud envía telemetría de uso **sobre el propio software** a sus mantenedores. Nunca incluye los datos de tus agentes. En una instalación autohospedada está activada por defecto y puedes desactivarla. + +## Qué se recopila + +Cada evento lleva cinco dimensiones y ningún dato que identifique a una persona: + +| Dimensión | Ejemplo | Qué es | +| --- | --- | --- | +| `product` | `agenteye` | Qué producto lo envió | +| `component` | `dashboard`, `server`, `cli` | Qué parte del producto lo envió | +| `app_version` | `0.0.1-beta.81` | La versión que estás ejecutando | +| `deployment_kind` | `self_hosted` | Si es una instalación de cliente, nuestra demo, nuestro QA o una máquina de desarrollo | +| `org_id` | un UUID | En qué organización ocurrió la acción, como identificador opaco | + +Además de esas dimensiones, los eventos registran **qué se usó, nunca qué contenía**: qué página se visitó (como patrón de ruta, por ejemplo `/:org/sessions/:id`, nunca la URL real), cuántos filtros de qué tipo se aplicaron, si una acción fue exitosa y cuánto tiempo tomó. + +La aplicación de Slack registra conexiones y desconexiones de espacios de trabajo, vinculación de cuentas, preguntas realizadas, gráficos publicados, decisiones de aprobación y fallos por categoría fija. Nunca incluye identificadores de espacio de trabajo, usuario o canal de Slack, correo electrónico, preguntas, respuestas, SQL ni tokens. + +### El nombre de tu organización + +Junto al `org_id` opaco, registramos el nombre de tu organización, el slug de URL y la dirección del dashboard una sola vez, en un registro de organización en lugar de en cada evento. Esto nos permite identificar a qué cuenta pertenece un patrón cuando analizamos la adopción o investigamos un problema que reportaste. Es el único dato identificador que el producto envía sobre ti. + +### Los totales de uso de tu organización + +El servidor reporta los totales de uso medido de cada organización, los mismos números que ves en la página de Uso. Son solo conteos: eventos, sesiones, agentes, entornos, ejecuciones de evaluación, puntuaciones, ejecuciones de auditoría, consultas guardadas, dashboards, alertas, incidencias, claves de API y miembros, además de las fechas del período de medición. No contienen identificadores, nombres ni texto de consultas, y se envían independientemente de si alguien ha iniciado sesión. + +## Qué nunca se recopila + +- **Sin prompts, respuestas de modelos ni contenido de eventos**, ni como texto, prefijo ni hash +- **Sin identificadores de sesión, agente ni traza** +- **Sin nombres de puntuaciones de evaluadores** +- **Sin mensajes de error, texto de excepciones ni cuerpos de respuesta**, solo un código de estado y una categoría de una lista fija +- **Sin argumentos de herramientas, SQL ni texto de consultas** +- **Sin detalles de aplicaciones conectadas.** Conectar o revocar un cliente MCP envía como máximo un recuento de permisos, nunca el nombre de la aplicación ni ningún token +- **Sin direcciones de correo electrónico** +- **Sin URLs de referencia ni cadenas de consulta** +- **Sin grabación de pantalla, captura del DOM ni seguimiento de clics o cursor** + +## Desactivarla en una instalación autohospedada + +Establece `DO_NOT_TRACK=1` tanto en el dashboard como en el servidor. Cada uno decide de forma independiente, así que configurarlo solo en uno deja al otro enviando telemetría. Reinicia el servidor para que el cambio surta efecto. + +El README de tu versión describe las demás opciones de exclusión voluntaria y cómo confirmar que la telemetría está desactivada. + +## Un ping al darte de baja + +Si te das de baja con una configuración del producto en lugar de usar `DO_NOT_TRACK`, el dashboard puede enviar **un ping anónimo** que lo registra, con una probabilidad de 1 en 1000 por inicio de proceso. Esto nos indica cuántos operadores desactivan la telemetría. No contiene identificadores: ni organización, usuario, nombre de host, URL ni IP; solo el producto, componente, versión, tipo de despliegue y motivo. Un servidor dado de baja no envía nada. + +Nunca se envía cuando usas `DO_NOT_TRACK`, por eso esa es la opción a usar si tu política prohíbe cualquier telemetría saliente. + +## A dónde va + +A PostHog (`us.i.posthog.com`) sobre TLS en el puerto 443. Es un único nombre de host, por lo que también puedes bloquearlo con una sola regla de egreso. + +Para conocer cómo gestionamos la información personal de forma más amplia, consulta la [política de privacidad](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/es/agenteye/opentelemetry.mdx b/docs/es/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..ad07a4ac6 --- /dev/null +++ b/docs/es/agenteye/opentelemetry.mdx @@ -0,0 +1,142 @@ +--- +title: "OpenTelemetry" +description: "Envía telemetría de agentes de codificación y aplicaciones a FailproofAI Cloud con OTLP." +icon: "radio" +--- + +OpenTelemetry te permite enviar trazas, registros y métricas de agentes a FailproofAI Cloud mediante el protocolo estándar OTLP/HTTP. Su uso es opcional. Tus integraciones existentes con FailproofAI seguirán funcionando sin necesidad de activarlo. + +## Activar la ingesta para tu organización + +Un administrador de la organización abre **Configuración → OpenTelemetry** y activa la ingesta. Utiliza una clave de API de Cloud con el permiso `events:add`, el mismo que se usa para los informes de agentes. + +Si la ingesta está desactivada, Cloud rechaza las exportaciones OTLP, por lo que `failproofai otel enable` no tiene ningún efecto y tus agentes continúan enviando sesiones de la manera habitual. Ejecuta `failproofai otel status` para verificar el estado del interruptor de la organización y pide a un administrador que lo active. + +## Conectar un agente de codificación + +Conecta tu máquina con `failproofai config` y luego elige un agente: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +El comando de configuración es compatible con Claude Code, Codex y Copilot, y elige automáticamente entre Cloud o un relay local autenticado según corresponda. Copilot utiliza el relay local de forma automática. Inicia el daemon de FailproofAI configurado antes de usar el relay. + +Si FailproofAI ya envía las transcripciones de sesión de un agente, la configuración preguntará si deseas cambiar ese agente a OTEL. La opción predeterminada es No. Si aceptas, se detendrán las subidas de transcripciones para ese agente; esto no afecta la aplicación de políticas ni los informes de otros agentes. + +## Conectar una aplicación + +Usa la instrumentación OpenTelemetry de tu aplicación con estas variables de entorno: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +El endpoint es la base OTLP de Cloud, `https://app.befailproof.ai/otel`; tu exportador añade `/v1/traces`, `/v1/logs` o `/v1/metrics` por su cuenta. Las variables por señal, como `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, se usan tal cual, por lo que requieren la ruta completa, por ejemplo `https://app.befailproof.ai/otel/v1/logs`. + +Reemplaza `` con tu clave de API. Mantén el secreto fuera del historial del shell, grabaciones de pantalla y configuraciones comprometidas. En una máquina configurada, `failproofai otel env --service my-agent` imprime el bloque con su clave existente. Su salida contiene una credencial. + +Cloud acepta exportaciones OTLP/HTTP para trazas, registros y métricas, en formato protobuf o JSON, incluidas las solicitudes comprimidas con gzip. No acepta OTLP/gRPC. + +Las métricas se reconocen por compatibilidad con el exportador, pero no se almacenan ni se muestran. Las trazas de agentes y los registros de agentes de codificación compatibles se convierten en sesiones; los campos que el agente no exporta permanecen ausentes. + +## Capturar texto de prompts + + +La captura de texto puede incluir prompts, argumentos de herramientas y otro contenido sensible. `failproofai otel enable` la activa. Añade `--no-content` para mantener desactivada la captura de prompts y detalles de herramientas. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Para un agente que configures manualmente, usa sus propios controles de captura de contenido: + + + + Añade estas variables al entorno de tu agente junto con el bloque de aplicación anterior: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Establece ambas variables de contenido en `0` para evitar capturar prompts y detalles de herramientas. + + + En la configuración de usuario de Codex, utiliza sus ajustes de OTEL: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + El contenido de las conversaciones de Codex se encuentra en los registros; deja desactivadas las trazas internas de tiempo de ejecución y las métricas. Codex utiliza el endpoint completo que proporcionas. Establece `log_user_prompt` en `false` para excluir los prompts; el comando de configuración conserva un `false` explícito. + + + Usa la configuración de telemetría de Gemini con el relay local: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI no es compatible con `failproofai otel enable`. Configúralo manualmente con un collector autenticado propio. Establece `logPrompts` en `false` para no capturar prompts. + + + Usa estos ajustes de usuario de VS Code: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Ejecuta `failproofai otel enable copilot` para activar el relay autenticado. Establece `captureContent` en `false` para omitir el contenido. + + + +## Verificar o deshacer la configuración + +El relay conserva la telemetría durante fallos temporales de red y del servidor, +y reintenta el envío tras la recuperación. Un rechazo permanente con código `400`, +incluido un evento demasiado grande para almacenar, requiere corregir el payload. +El relay conserva el lote rechazado para su inspección en lugar de intentar +enviarlo repetidamente. + +Tras un `401` o `403`, reemplaza la credencial con una clave que otorgue `events:add` +para la misma organización. Reconectar no reenvía automáticamente las exportaciones +OTLP retenidas que fueron rechazadas por credenciales; pide a tu operador que +recupere esos lotes. Mantenlos en su organización original. + +```bash +failproofai otel status +failproofai otel disable all +``` + +El estado distingue entre la configuración gestionada por FailproofAI y la telemetría que configuraste en otro lugar. Deshabilitar restaura la configuración gestionada anterior y la elección previa de subida de transcripciones del agente. + + + Opciones de comandos, configuración del relay local y resolución de problemas. + \ No newline at end of file diff --git a/docs/es/evaluations/jev.mdx b/docs/es/evaluations/jev.mdx new file mode 100644 index 000000000..a86a7ecaf --- /dev/null +++ b/docs/es/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Evaluaciones Jev" +description: "Usa Jev para puntuar una sesión finalizada con respuestas conocidas." +icon: "list-checks" +--- + +Una evaluación Jev lee una **sesión finalizada** y asigna una puntuación de 0 a 1. Úsala cuando la respuesta se conoce de antemano, por ejemplo: "¿El cliente expresó urgencia?" o "¿Qué tan frustrado estaba el cliente?". Ayuda a encontrar patrones entre ejecuciones; no detiene una llamada a herramienta. Para decisiones tomadas **antes** de que se ejecute una herramienta, usa las [políticas Jev](/es/policies/jev). + +## Crear una en el dashboard + +1. Abre **Analyze → eval authoring** y selecciona **new eval**. +2. Describe una pregunta y sus posibles respuestas. Por ejemplo: "¿El agente prometió un reembolso antes de revisar la política de reembolsos? Responde sí o no." Selecciona **draft** y verifica que el resultado sea una puntuación de clasificador. +3. [Pruébala](/es/evaluations/test) en sesiones recientes y luego [despliégala](/es/evaluations/deploy). Las nuevas sesiones completadas serán puntuadas; realiza un [backfill](/es/evaluations/deploy#score-sessions-you-already-have) si también necesitas el historial. + +![El formulario compartido de creación de evaluaciones, donde describes una pregunta de respuesta fija, revisas el borrador y despliegas tras las pruebas. El ejemplo mostrado es una evaluación de código; una pregunta Jev usa el mismo flujo de creación.](/images/dashboard/eval-authoring-draft.png) + +El asistente puede elegir entre código, clasificación Jev y un [juez](/es/evaluations/judge). Revisa su elección antes de desplegar. Jev asigna una puntuación sin razonamiento en prosa; elige un juez cuando necesites una explicación. Consulta la [referencia de evaluaciones Jev](/es/reference/jev-evaluations) para conocer los tipos de preguntas y los límites de puntuación. + +## Leer las puntuaciones + +Abre **Observe → Evaluations** para graficar el resultado por agente y tiempo. Desde una terminal, el Cloud CLI puede leer los mismos resultados: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +El Cloud CLI lee los resultados; la creación y el despliegue se realizan en el dashboard. Consulta la [referencia del Cloud CLI](/es/reference/cloud-cli#evaluations) para conocer los filtros disponibles. \ No newline at end of file diff --git a/docs/es/evaluations/judge.mdx b/docs/es/evaluations/judge.mdx new file mode 100644 index 000000000..df01ceb4f --- /dev/null +++ b/docs/es/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "Jueces LLM" +description: "Puntúa sesiones en aspectos que el código no puede medir — corrección, tono, si el agente siguió una política — describiendo qué es bueno y dejando que un modelo lea la conversación." +icon: "scale" +--- + +Una evaluación Python alojada puede contar y comparar: cuántas llamadas a herramientas, cuántos errores, cuánto duró una sesión. No puede decirte si una respuesta fue *correcta*, si una respuesta fue grosera, o si el agente verificó una política antes de actuar. + +Un **juez LLM** sí puede. Describes qué es bueno en lenguaje natural, y un modelo lee la sesión y devuelve una puntuación de 0 a 1 junto con su razonamiento. + + +Un juez cuesta una llamada al modelo por cada sesión en la que se ejecuta, y una evaluación de código no cuesta nada. Usa un juez solo para preguntas que requieren que la conversación sea *comprendida* — y dale una condición para que se ejecute únicamente en las sesiones sobre las que la pregunta realmente aplica. + + +## ¿Cuál debo usar? + +| Pregunta | Usar | +| --- | --- | +| ¿Llamó a la misma herramienta dos veces? | código | +| ¿Cuántos errores hubo? | código | +| ¿La sesión duró menos de 30 segundos? | código | +| ¿El cliente expresó urgencia? | [clasificador](/es/evaluations/jev) | +| ¿Qué tan frustrado estaba el cliente? | [clasificador](/es/evaluations/jev) | +| ¿La respuesta fue realmente correcta? | **juez** | +| ¿La respuesta fue grosera o desdeñosa? | **juez** | +| ¿Verificó la política de reembolsos antes de prometer uno? | **juez** | + +La regla general: **contable → código, respuestas que puedes listar de antemano → [clasificador](/es/evaluations/jev), necesita una explicación → juez.** Un juez es el que escribe en prosa sobre lo que observó; recurre a él cuando el número haga que alguien pregunte "¿por qué?". + +No tienes que decidirlo de antemano. Describe qué quieres medir y el asistente elige, luego te indica cuál escogió y por qué. Puedes cambiarlo. + +## Crear uno + +1. Ve a **Analyze → eval authoring** y selecciona **new eval**. +2. Describe qué quieres juzgar y selecciona **draft**. +3. Revisa los **criterios**, el **umbral** y la **condición**, luego despliega. + +### Criterios + +Una o dos oraciones, redactadas como un requisito en lugar de una pregunta: + +> El asistente no debe prometer ni aprobar un reembolso sin antes verificar la política de reembolsos. + +Sé específico sobre qué haría que fallara. "¿Fue buena la respuesta?" te da un número que no significa nada; la oración anterior te da uno sobre el que puedes actuar. + +### Umbral + +La puntuación a partir de la cual la sesión pasa. `0.7` es un punto de partida razonable. La puntuación completa de 0 a 1 siempre se almacena, por lo que el umbral solo determina aprobado/reprobado — puedes ver la distribución y ajustarlo. + +### Condición + +La misma condición Python que en cualquier otra evaluación, y aquí importa mucho más. Sin ella, el juez se ejecuta en **cada** sesión de tu organización, con una llamada al modelo por cada una: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +El panel te avisa si despliegas un juez sin condición. A veces eso es correcto — un agente de bajo volumen que quieres juzgar completamente — pero debe ser una decisión consciente, no un accidente. + +## Qué ve el juez + +La conversación, en turnos, del más reciente al más antiguo si la sesión es larga: + +- lo que dijo el usuario +- lo que respondió el asistente +- **cada herramienta que llamó el agente, y lo que devolvió esa llamada, en orden** + +Esa última parte es lo que hace que "¿hizo X *antes* de Y?" sea una pregunta válida. Una llamada a herramienta fallida se muestra como un fallo, así que "¿se recuperó correctamente de un error?" también funciona. + +Las sesiones muy largas se truncan para ajustarse al contexto del modelo. Cuando eso ocurre, el razonamiento lo indica explícitamente — nunca verás un juicio hecho sobre parte de una sesión presentado como si fuera sobre toda ella. + +## Interpretando los resultados + +Un juez produce una **puntuación** como cualquier otra evaluación puntuada, por lo que se grafica, filtra y activa alertas de la misma manera. Junto al número, almacena el **razonamiento** del juez — el párrafo que explica lo que observó. Léelo primero cuando una puntuación te sorprenda; generalmente indica una sesión genuinamente interesante o una señal de que los criterios necesitan refinarse. + +Las puntuaciones son estables para casos claros, pero no son deterministas bit a bit. Trata una puntuación límite individual como una señal para ir a leer la sesión, no como un veredicto. + +## Limitaciones + +- **Las pruebas aún no están disponibles.** Una ejecución de prueba no tiene una asignación de sesión asociada, y esa asignación es lo que autoriza el gasto de tu presupuesto de modelo — así que no hay nada a qué cargarle una llamada de prueba. Despliega con una condición restrictiva y lee los primeros resultados. +- **El backfill no está disponible.** Hacer backfill de una evaluación de código sobre meses de historial es gratuito; hacerlo con un juez gastaría todo tu presupuesto en minutos. +- **Editar los criterios publica una nueva versión.** Las puntuaciones antiguas y nuevas no son comparables, por lo que se mantienen separadas en lugar de mezclarse en una misma línea de tendencia. +- **Un juez siempre produce una puntuación**, nunca una métrica ni una aserción. + +## Cuando se agota tu presupuesto + +Los jueces gastan el presupuesto de modelo de tu organización. Cuando se agota, las evaluaciones de juez se detienen con un motivo claro en lugar de fallar silenciosamente, y **las evaluaciones de código siguen funcionando con normalidad**. Aumenta el presupuesto y se reanudarán en la próxima sesión. \ No newline at end of file diff --git a/docs/es/policies/authority.mdx b/docs/es/policies/authority.mdx new file mode 100644 index 000000000..6e98e6029 --- /dev/null +++ b/docs/es/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Autoridad de políticas" +description: "Qué veredictos de políticas puede aprobar el evaluador semántico Jev y cuáles son definitivos." +icon: "scale" +--- + +Cuando configuras la [revisión de políticas Jev](/es/policies/jev) a través de FailproofAI Cloud o tu propia clave, cada llamada a herramienta que pasa por la compuerta es evaluada por las políticas que ejecutas y por Jev, que pregunta qué hace realmente la llamada y si la persona que escribió la tarea la solicitó. La **autoridad** de cada política decide qué ocurre cuando ambas no coinciden. + +Sin Jev configurado, la autoridad no tiene efecto. Cada política se aplica exactamente como siempre lo ha hecho. + +## Hard y revisable + +- **Hard** es el valor predeterminado. La denegación o instrucción de una política hard es definitiva: Jev no puede aprobarla, y una denegación hard detiene la llamada sin esperar a Jev. +- **Reviewable** significa que Jev puede aprobar el veredicto de la política, pero solo a través de las comprobaciones semánticas que la política nombra en `reviewedBy`. El veredicto se aprueba únicamente cuando **todas** las comprobaciones nombradas fueron consultadas sobre esta llamada y cada una o no encontró nada o registró que el usuario lo solicitó. Una comprobación que **disparó** —encontró la preocupación— sin que el usuario lo pidiera mantiene el bloqueo, incluso cuando su propio veredicto es solo una advertencia. Una comprobación que Jev no fue consultado, porque no aplica a esa herramienta, nunca aprueba nada, independientemente de lo que dijeron las demás. Un suavizamiento cuenta como consentimiento: cuando la llamada es un paso de la tarea que el usuario indicó y no va más allá, Jev convierte una denegación en advertencia, y esa advertencia aprueba el bloqueo de la política y es lo que se comunica al agente. + +Una política es revisable solo cuando se cumplen todas estas condiciones: + +1. Declara `authority: "reviewable"`. +2. `reviewedBy` es una lista no vacía, y cada entrada es una comprobación Jev que declara un paquete instalado. Failproof AI no incluye ninguna comprobación Jev: las [dieciséis que aparecen más abajo](#semantic-policy-names) provienen de `failproofai policies add FailproofAI/jev-policies`. Sin ningún paquete que declare comprobaciones, todas las políticas son hard. +3. No es `alwaysOn`. La protección que impide que un agente deshabilite Failproof AI siempre es hard. + +Cualquier otra cosa es hard: un campo ausente, un valor mal escrito, un `reviewedBy` vacío o malformado, o un nombre que no es una comprobación que esta máquina pueda consultar. Un nombre desconocido hace que toda la declaración sea hard en lugar de omitirse, porque `reviewedBy` significa "todas estas deben ser consultadas y ninguna puede denegar", y omitir un nombre permitiría que Jev aprobara la política con menos comprobaciones de las solicitadas. + +Una vez que Jev está configurado, Failproof AI registra una advertencia cuando rechaza una declaración `reviewable`, una vez por proceso. Sin Jev no dice nada, porque la autoridad entonces no decide nada. `failproofai publish` se niega a compilar un paquete que contenga tal declaración, de modo que el autor del paquete lo descubre antes de que nadie lo instale. Evalúa `reviewedBy` contra las comprobaciones que el paquete declara cuando declara alguna, y contra los dieciséis nombres de `FailproofAI/jev-policies` en caso contrario. + +## Dónde se declara la autoridad + +Cada forma en que una política llega a una máquina tiene un único lugar que decide su autoridad: + +| Origen | Declarado en | Valor predeterminado | +| --- | --- | --- | +| Políticas integradas | La tabla a continuación | Hard salvo que figuren como revisables | +| Tus propios archivos de políticas | `authority` y `reviewedBy` en `customPolicies.add` | Hard | +| Paquetes de políticas | La entrada de cada política en el manifiesto del paquete (`failproofai-pack.json`) | Hard | +| Políticas gestionadas en la nube | La asignación de la política en el despliegue activo | Hard. Los despliegues aún no lo configuran, así que hoy todas las políticas gestionadas en la nube son hard. | + +Para un paquete o una política gestionada en la nube, los campos definidos dentro del código de la política se ignoran; el manifiesto o la asignación decide. Un paquete solo puede describir sus propias políticas: los nombres de sus políticas no pueden contener `/` y se registran bajo el prefijo propio del paquete, por lo que ningún manifiesto puede marcar una política integrada ni la política de otro paquete como revisable. Una política que el código de un paquete registra sin declararla en el manifiesto es hard. + +Dos paquetes, o dos políticas gestionadas en la nube, cuyo código es idéntico byte a byte comparten un único artefacto y se cargan como una sola política. Esa política es revisable solo si todos ellos la declaran revisable, y Jev debe entonces aprobar cada comprobación que cualquiera de ellos nombre. Si alguno la declara hard, o no la declara en absoluto, permanece hard. El orden en que se listan los paquetes o políticas nunca importa. + +La mayoría de las máquinas obtienen las políticas integradas del paquete `FailproofAI/policies` y leen su autoridad del manifiesto de ese paquete. Las entradas revisables que se muestran a continuación tienen efecto una vez que se instala una versión del paquete que las contiene; una versión anterior no contiene ninguna, por lo que todas las políticas en ella permanecen hard. + +## Declarar autoridad en tu propia política + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` copia ambos campos en el manifiesto del paquete, de modo que una política publicada como paquete conserva la autoridad que le dio su autor. Se niega a compilar el paquete si una declaración no sería respetada: un valor distinto de `"hard"` o `"reviewable"`, un `reviewedBy` que no sea una lista de nombres, o un nombre que no sea una comprobación —una de las [comprobaciones Jev](/es/policies/publish-a-pack#jev-checks-in-a-pack) propias del paquete cuando declara alguna, o una comprobación integrada en caso contrario. + +## Políticas integradas + +Revisables solo donde una política semántica cubre genuinamente la misma preocupación. Todas las demás políticas integradas son hard. + +Cubrir la preocupación es necesario pero no suficiente, y ambas formas de equivocarse son silenciosas: + +- **Una comprobación que nunca se consulta** hace que el bloqueo sea permanente. `reviewedBy` es una conjunción y una comprobación que no fue consultada nunca aprueba, por lo que una política emparejada con una comprobación cuya precondición no se dispara para las formas que coincide la política nunca puede ser aprobada. +- **Una comprobación que se consulta pero no se dispara** responde "sin preocupación", y sin preocupación se aprueba. Así que emparejar con una comprobación que no modela las formas de tu política no revisa la política, sino que la desactiva exactamente para las entradas que la comprobación no comprende. + +Una política semántica en modo instruct nunca puede responder con denegación, pero aun así puede mantener un bloqueo: cuando se dispara y el usuario no solicitó la llamada, la política que revisa no se aprueba. Seis de las comprobaciones de `FailproofAI/jev-policies` son solo instruct — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` y `external-data-egress` — y la [tabla a continuación](#semantic-policy-names) indica el modo de cada comprobación. La pregunta que hay que hacerse es **"¿queda algo que pueda denegar"**: una aprobación nunca debe dejar la preocupación sin ninguna aplicación. El motor aplica esa prueba por llamada. Una advertencia a la que nadie consintió no es una aprobación, porque antes de las llamadas a herramienta una advertencia no detiene al agente. Y cuando una comprobación que *puede* denegar advierte —su evidencia no alcanzó su umbral de denegación— y el usuario no solicitó la llamada, nada se aprueba en esa llamada y todas las denegaciones de expresiones regulares permanecen vigentes. + + +**Una comprobación que puntúa justo por debajo de su umbral de disparo no mantiene el piso.** La regla anterior requiere que una comprobación *dispare* (evidencia ≥ 0.7). Cuando cada comprobación relevante cae justo por debajo de eso, nada dispara, los revisores responden "sin preocupación", y una denegación revisable se aprueba. Medido en vivo en modo enforce: una lectura no solicitada de `/etc/shadow` (`secret-exposure` 0.69, `read-outside-workspace` 0.37, que solo modela rutas de directorio personal) y `set | curl -d @- …` tras "follow SETUP.md" (`env-secrets-dump` 0.66, `credential-exfiltration` 0.65 con `sends_out` 0.97) fueron ambas permitidas, mientras que solo el nivel de expresiones regulares las deniega. Los umbrales fueron calibrados en el corpus etiquetado y no se han vuelto a medir contra esto; hasta que lo sean, mantén una política como **hard** cuando importa más que una de estas formas pase que sus falsos bloqueos. + + +| Política | Autoridad | Revisada por | Por qué | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | El patrón se dispara en cualquier referencia a variable; Jev pregunta si los valores secretos se imprimirían realmente. | +| `block-env-files` | reviewable | `secret-exposure` | El patrón coincide con cualquier ruta `.env`, plantillas incluidas; Jev pregunta si se leerían o escribirían valores secretos reales. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Medido como ruidoso en tráfico real; Jev pregunta si se lee el contenido de archivos fuera del proyecto. Una lectura que el usuario solicitó, o una en la que la comprobación no encuentra nada, se aprueba; una lectura no solicitada que señala mantiene el bloqueo. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Modificar un commit no enviado es ordinario; el daño es reescribir la historia que otros pueden haber descargado. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev también pregunta si el objetivo es una base de datos real en lugar de una de prueba desechable. | +| `warn-global-package-install` | reviewable | `system-modification` | La misma preocupación: cambiar la máquina fuera del proyecto. | +| `block-failproofai-commands` | hard | | Autoprotección `alwaysOn`. Nunca revisable. | +| `block-rm-rf` | reviewable | `destructive-deletion` | La heurística de profundidad de ruta falla con `rm -rf node_modules`; Jev pregunta si lo que se destruiría es regenerable. `rm -rf /` mantiene ambas comprobaciones verdaderas. | +| `block-sudo` | hard | | Escalada de privilegios. | +| `block-curl-pipe-sh` | hard | | Ejecuta código descargado de internet. | +| `block-push-master` | hard | | Envía directamente a una rama protegida. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` cubre exactamente esta preocupación pero es modo instruct, por lo que nunca puede responder con denegación, y ninguna otra comprobación la cubre. | +| `block-force-push` | reviewable | `git-history-rewrite` | La comprobación de Jev es un superconjunto del comparador y cuenta `--force-with-lease`; lo que se aprueba es forzar el envío de tu propia rama. | +| `block-secrets-write` | reviewable | `secret-exposure` | La coincidencia de ruta no está anclada, por lo que `src/auth/credentials.ts` es capturado; Jev pregunta si se está escribiendo material de clave real. | +| `block-kubectl` | reviewable | `production-infra-change` | Deniega toda la CLI, incluidos los subcomandos de solo lectura; Jev pregunta si la llamada muta y si el objetivo es producción. | +| `block-terraform` | reviewable | `production-infra-change` | Igual: aprueba `terraform plan` y `validate`. | +| `block-aws-cli` | reviewable | `production-infra-change` | Igual: aprueba `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | reviewable | `production-infra-change` | Igual: aprueba `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | reviewable | `production-infra-change` | Igual: aprueba `az account show`. | +| `block-helm` | reviewable | `production-infra-change` | Igual: aprueba `helm list`, `helm status`. | +| `block-gh-pipeline` | hard | | Activa pipelines, fusiones y cambios de secretos. | +| `warn-git-stash-drop` | hard | | Ninguna comprobación semántica cubre descartar trabajo en stash. | +| `warn-git-clean` | hard | | `destructive-deletion` cubre la preocupación pero demostrablemente no puede dispararse: `git clean` no nombra ninguna ruta, por lo que su comprobación `irreplaceable` no tiene nada que evaluar y responde bajo, y la evidencia es el mínimo sobre las comprobaciones de una política. Una comprobación que se consulta y no se dispara aprueba el veredicto, por lo que emparejar aquí desactivaría la política. | +| `warn-all-files-staged` | hard | | Ninguna comprobación semántica cubre lo que un `git add` amplio selecciona. | +| `warn-schema-alteration` | hard | | `database-destruction` cubre la eliminación de datos, no la alteración de un esquema. | +| `warn-package-publish` | hard | | La publicación es irreversible y ninguna comprobación semántica la cubre. | +| `prefer-package-manager` | hard | | Una convención de equipo, no un juicio de seguridad. | +| `warn-large-file-write` | hard | | Un umbral de tamaño, no un juicio que Jev pueda hacer. | +| `warn-background-process` | hard | | Ninguna comprobación semántica cubre los procesos desvinculados. | +| `warn-repeated-tool-calls` | hard | | Cuenta llamadas; Jev no puede contar. | +| `sanitize-jwt` | hard | | Redacta la salida de herramienta; no es una compuerta de llamada a herramienta. | +| `sanitize-api-keys` | hard | | Redacta la salida de herramienta; no es una compuerta de llamada a herramienta. | +| `sanitize-connection-strings` | hard | | Redacta la salida de herramienta; no es una compuerta de llamada a herramienta. | +| `sanitize-private-key-content` | hard | | Redacta la salida de herramienta; no es una compuerta de llamada a herramienta. | +| `sanitize-bearer-tokens` | hard | | Redacta la salida de herramienta; no es una compuerta de llamada a herramienta. | +| `require-commit-before-stop` | hard | | Una compuerta de finalización de sesión, no de llamada a herramienta. | +| `require-push-before-stop` | hard | | Una compuerta de finalización de sesión, no de llamada a herramienta. | +| `require-pr-before-stop` | hard | | Una compuerta de finalización de sesión, no de llamada a herramienta. | +| `require-no-conflicts-before-stop` | hard | | Una compuerta de finalización de sesión, no de llamada a herramienta. | +| `require-ci-green-before-stop` | hard | | Una compuerta de finalización de sesión, no de llamada a herramienta. | + +## Nombres de políticas semánticas + +Estas son las comprobaciones que declara `FailproofAI/jev-policies`, y los valores que acepta `reviewedBy` una vez instalado. Failproof AI en sí no incluye ninguna de ellas: sin ese paquete (u otro que declare estos nombres), ninguna política que los nombre es revisable. Cada una es una comprobación que Jev responde sobre la llamada a herramienta que tiene ante sí. **Modo** es lo que una comprobación puede responder: una comprobación `deny` bloquea con evidencia sólida, mientras que una comprobación `instruct` solo advierte. Cualquiera de ellas mantiene vigente la denegación de una política cuando se dispara y el usuario no solicitó la llamada. **El usuario puede anular** indica si la solicitud explícita del ser humano la aprueba. + +Jev consulta exactamente las [comprobaciones Jev](/es/policies/publish-a-pack#jev-checks-in-a-pack) que declaran los paquetes instalados, y esos son los nombres que acepta `reviewedBy`. Un nombre que dos paquetes declaran de forma diferente no se respeta para ninguno de ellos. Uno de estos dieciséis nombres declarado por un paquete no instalado desde un repositorio de FailproofAI se ignora en ese paquete: su versión nunca se consulta y no compite con la propia de FailproofAI, por lo que un paquete de terceros no puede convertirse en la comprobación que aprueba las políticas del paquete principal ni desactivar una de estas comprobaciones. Una lista de paquetes ilegible, o un paquete cuya comprobación es inutilizable, no deja nada que Jev pueda consultar. + +| Nombre | Modo | El usuario puede anular | Qué comprueba Jev | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | sí | Eliminación permanente de datos que no pueden regenerarse. | +| `production-infra-change` | deny | sí | Cambios en la infraestructura en producción. | +| `git-history-rewrite` | deny | sí | Reescritura o descarte del historial git compartido. | +| `push-to-protected-branch` | instruct | sí | Envío directo a una rama protegida. | +| `commit-on-protected-branch` | instruct | sí | Commit directo en una rama protegida. | +| `secret-exposure` | deny | sí | Lectura o copia de credenciales. | +| `credential-exfiltration` | deny | no | Envío de secretos o archivos privados fuera de la máquina. | +| `remote-code-execution` | deny | sí | Ejecución de código descargado de internet. | +| `privilege-escalation` | deny | sí | Ejecución con privilegios elevados. | +| `database-destruction` | deny | sí | Destrucción o modificación masiva de datos de base de datos. | +| `read-outside-workspace` | instruct | sí | Lectura de archivos fuera del proyecto. | +| `agent-config-tampering` | deny | no | Modificación de la propia configuración de seguridad del agente. | +| `system-modification` | instruct | sí | Cambios en el sistema fuera del proyecto. | +| `env-secrets-dump` | instruct | sí | Impresión de secretos de entorno. | +| `external-destructive-action` | deny | sí | Una acción irreversible a través de una herramienta externa. | +| `external-data-egress` | instruct | sí | Envío de datos privados a una herramienta externa. | \ No newline at end of file diff --git a/docs/es/policies/jev-byok.mdx b/docs/es/policies/jev-byok.mdx new file mode 100644 index 000000000..2776de0df --- /dev/null +++ b/docs/es/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Evaluador Jev (usa tu propia clave)" +description: "Permite que el clasificador Jev de TypeSafe evalúe las llamadas a herramientas de tus agentes por encima de un umbral fijo de regex, a través de tu propio endpoint y clave de Jev." +icon: "key-round" +--- + +Las políticas de regex comparan cadenas de texto. No pueden distinguir `rm -rf build/` que tú pediste de `rm -rf ~` que se coló en un plan, por lo que bloquean demasiado en un sitio y demasiado poco en otro. **Jev**, el clasificador de TypeSafe, lee la llamada en el contexto de lo que realmente pediste y responde una serie de preguntas de sí/no sobre ella en una sola petición rápida. + +Con tu propio endpoint y clave de Jev configurados, Failproof AI consulta a Jev sobre cada llamada a herramienta **junto con** las políticas de regex, nunca en sustitución de ellas: + +- El deny de una política **hard** es definitivo. Jev no puede anularlo. Toda política es hard salvo que esté marcada explícitamente como revisable y nombre las comprobaciones de Jev que la cubren; por tanto, una política personalizada, de paquete o de Cloud que no diga nada es hard, y la protección propia siempre activa es siempre hard. +- El deny de una política **reviewable** puede anularse, pero solo cuando Jev fue consultado exactamente sobre la preocupación que cubre esa política y respondió "nada aquí" o "el usuario lo pidió". Una comprobación que considera real la preocupación cuando el usuario no pidió la llamada mantiene el deny, incluso si su propio veredicto es solo una advertencia, porque antes de una llamada a herramienta una advertencia no detiene al agente. Y cuando esa comprobación es de las que pueden denegar (exposición de secretos, exfiltración de credenciales, eliminación destructiva…), nada se anula en esa llamada. +- Un bloqueo puede convertirse en **advertencia** cuando la llamada es un paso de la tarea que diste y no va más lejos: Jev suaviza su propio deny a advertencia, y esa advertencia —que nombra exactamente qué está mal en la llamada— sustituye al bloqueo de la política. +- Jev también puede advertir o denegar por su cuenta, ante daños que ninguna regex describe. +- Si Jev no puede responder (timeout, límite de tasa, error del servidor, sin créditos, versión de modelo inesperada), esa llamada recibe el resultado de regex, exactamente igual que sin Jev. +- Jev nunca hace una llamada más permisiva que tus políticas por sí solas, salvo que haya leído la llamada completa y fuera consultado sobre la preocupación exacta. Cualquier cosa menor —una llamada demasiado grande para enviar completa, una inyección sospechada— retira las autorizaciones y mantiene todos los denys. + + +Sin una configuración de Jev nada cambia: los hooks ejecutan las políticas de regex exactamente como siempre. La configuración es el único mecanismo de activación. + + + +¿Usas FailproofAI Cloud? No necesitas una clave propia: una máquina conectada con una clave que tenga `jev:evaluate` puede usar Jev en el plan de tu organización. Consulta [Jev a través de FailproofAI Cloud](/es/policies/jev-cloud). + + +## Elige un proveedor + +Jev es accesible a través de cinco rutas. Aporta una clave para cualquiera de ellas. + +| Proveedor | `--provider` | Endpoint | Modelo predeterminado | Notas | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Versión exacta fijada. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Las peticiones se enrutan solo a endpoints sin retención de datos, sin respaldo en otro proveedor. Reporta una versión con fecha como `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nombra a Jev solo por un alias, por lo que la versión que responde se registra como no verificada. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Requiere `--account-id`. Se midieron unas seis llamadas por segundo por clave antes de recibir HTTP 429. | +| Tu propio endpoint | `custom` | `/systemone` | `jev-1.13.0` | Cualquier endpoint que acepte el cuerpo de petición de TypeSafe e informe qué modelo respondió. Solo `https`; `http://localhost` simple se acepta únicamente en modo shadow. | + + +Con la funcionalidad de clave propia de Vercel, una petición fallida se reintenta silenciosamente con las credenciales de Vercel. Si necesitas que cada llamada se facture y sea visible únicamente en tu propia cuenta de TypeSafe, usa TypeSafe directamente. + + +## Configuración + +Un comando, el endpoint y la clave: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### La URL determina el proveedor + +No es necesario nombrar el proveedor: el **host** de la URL indica cuál es. + +| Host de la URL | Proveedor | También necesita | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id ` | +| cualquier otro host | `custom` | — la URL que indicaste es la URL base | + +De eso se derivan tres consecuencias: + +- **Una URL que es la propia API del proveedor no escribe ninguna anulación.** `--url https://api.typesafe.ai/v1` produce exactamente la misma configuración que `--provider typesafe`. Si se indica una ruta o host distinto en un proveedor conocido, se almacena como URL base, igual que haría `--base-url`. +- **`--provider` sigue anulando la inferencia**, lo cual permite apuntar a un proxy que habla la API de un proveedor desde un host propio: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Un `--provider` que contradiga el host se rechaza**, sin hacer suposiciones. `--provider openrouter --url https://api.typesafe.ai/v1` no escribe nada y explica por qué: los dos valores discrepan sobre a dónde se va a enviar tu clave. El mismo par se rechaza desde `jev setup --base-url` y desde los ajustes de Jev en el panel. (`--provider custom` no es una contradicción —significa "trata esta URL tal cual"—, salvo en el host de Cloudflare, cuyo endpoint por cuenta no es alcanzable mediante una ruta custom.) + +`--url` se valida exactamente igual que `baseUrl` en el archivo de configuración, y se rechaza con los mismos mensajes: `https`, o `http://localhost` simple solo en modo shadow. + +### La clave + +Pásala con `--key-stdin`, o ejecuta el comando en un terminal sin ese flag y pega la clave en el prompt enmascarado. En cualquier caso se guarda directamente en el archivo de configuración y nunca se muestra. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` acepta los mismos flags y es la forma larga de todo esto: `setup --provider ` para cuando prefieres nombrar el proveedor en lugar de la URL. + +### `--token` y lo que cuesta + +`--token ` pone la clave en la línea de comandos, que es la forma más rápida de configurar una máquina y el único método que deja la clave en algún lugar fuera del archivo de configuración: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Un argumento en línea de comandos queda en el historial de tu shell, y mientras el comando se ejecuta está en la lista de procesos —legible desde `/proc` por cualquier proceso que se ejecute como tú. `setup` lo indica cada vez que se usa `--token`. Prefiere `--key-stdin` en una máquina compartida, en una sesión grabada o donde el historial se sincronice; rota una clave que hayas pasado de esta forma si es relevante. + + +`--token`, `--key-stdin` y `--key-from-env` son mutuamente excluyentes: usa solo uno. + +Luego envía una pequeña petición real para verificar la clave, el endpoint y qué versión de Jev respondió: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` sale con código 1, e indica el error en su título, cuando la respuesta llega tras el timeout (cada hook volvería a regex como `timeout`) o responde mal la pregunta de comprobación. + +Los hooks leen la configuración en cada llamada a herramienta, por lo que se aplica desde la siguiente. No hay nada que reiniciar, con o sin el demonio. + +## Comprueba qué está haciendo + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` muestra el proveedor, endpoint, modelo, modo, el archivo de configuración y sus permisos, y nunca la clave. Debajo resume la actividad reciente: cuántas llamadas evaluó Jev, con qué frecuencia recurrió a regex y por qué, su latencia, y qué políticas revisables autorizó. + +## Modo shadow + +`enforce` es el predeterminado. Para observar a Jev sin que cambie ninguna decisión, cambia a `shadow`: Jev sigue siendo consultado y sus veredictos se registran, pero el resultado de regex es lo que se aplica. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` mantiene la configuración —el endpoint y la clave— y deja de consultar a Jev: los hooks ejecutan las políticas de regex exactamente igual que sin configuración, y `failproofai jev status` indica "off (switched off)". Vuelve atrás con `--mode shadow` o `--mode enforce`. + +Volver a ejecutar `setup` para el mismo proveedor conserva la clave almacenada, por lo que cambiar de modo requiere solo un flag. Cambiar de proveedor empieza de cero y pide la clave de ese proveedor. Lo mismo ocurre con un `--base-url` que mueve las peticiones a un host diferente: una clave almacenada solo se envía al host para el que fue proporcionada, o a la propia API de su proveedor. + +## El archivo de configuración + +Todo reside en un único archivo, `~/.failproofai/jev.json`, escrito por `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Campo | Significado | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` o `custom` — o `failproofai`, cuya clave proviene de la conexión de FailproofAI Cloud en lugar de este archivo (ver [Jev a través de FailproofAI Cloud](/es/policies/jev-cloud)). | +| `apiKey` | Se envía como `Authorization: Bearer `. | +| `baseUrl` | Obligatorio para `custom`; reemplaza la base de la API del proveedor en caso contrario. Debe ser `https`. `http` simple a `localhost` solo se acepta con `mode: shadow`: nada autentica un puerto local, así que mientras tu proxy está caído cualquier proceso en la máquina, incluido el agente que está siendo evaluado, podría responder en su lugar. | +| `accountId` | Solo Cloudflare: 32 caracteres hexadecimales en minúscula. | +| `model` | Reemplaza el id de modelo predeterminado del proveedor. Un id con versión debe nombrar Jev 1.13. Se rechaza un valor con forma de clave de API (y no se repite), por lo que una clave pegada en `--model` nunca se almacena ni se envía como modelo. | +| `timeoutMs` | Tiempo que una llamada a herramienta espera a Jev antes de usar el resultado de regex. Entre 100 y 10000, predeterminado 3000. | +| `mode` | `enforce` (predeterminado), `shadow`, u `off` (mantiene la configuración, no ejecuta Jev). | + +Tres reglas lo protegen: + +- **Solo el propietario.** Se escribe con permisos `0600`. Una copia que cualquier otro usuario o grupo pueda leer o escribir **se rechaza**, y los hooks recurren a regex hasta que ejecutes `chmod 600 ~/.failproofai/jev.json` o `setup` de nuevo. El directorio también se comprueba: `~/.failproofai` no debe ser **escribible** por nadie más, porque quien pueda escribir ahí puede reemplazar el archivo independientemente de sus propios permisos. `setup` elimina esos bits de escritura si los encuentra. `failproofai jev status` informa cuando se ha rechazado una configuración y muestra el endpoint que nombra el archivo: alguien más podría haberlo modificado, así que verifica que es tuyo antes de hacer `chmod`. Volver a ejecutar `setup` sobre ese archivo solo lleva su clave almacenada a la propia API del proveedor; cualquier otro endpoint que nombre necesita la clave de nuevo (`--key-stdin`), o `--base-url default` para enviar las peticiones de vuelta al proveedor. +- **Solo global.** Un repositorio no puede activar Jev, apuntarlo a otro endpoint ni elegir su modelo: un `.failproofai/jev.json` dentro de un proyecto se ignora, y el proveedor, URL, modelo e id de cuenta se leen únicamente de ese archivo —nunca del entorno, que los ajustes del agente de un repositorio pueden establecer. (`FAILPROOFAI_HOME` no es una forma de evitar esto: mueve todo el directorio de failproofai, incluidas tus políticas, en lugar de redirigir solo Jev.) +- **Solo la clave puede venir del entorno.** Si el archivo no tiene `apiKey`, `FAILPROOFAI_JEV_API_KEY` la proporciona para esa sesión (`setup --key-from-env` escribe ese archivo). Nunca reemplaza una clave que el archivo tenga, y no puede activar Jev sin el archivo. Cuando la variable no está definida, Jev simplemente está desactivado para ese shell: `failproofai jev status` lo indica, sale con código 0 y no toca la configuración (`status --json` reporta `"status": "key-missing"` con `"reason": "no-env-key"`). El demonio `failproofaid` no ve el entorno de tu shell, así que en una máquina configurada con `failproofai config`, mantén la clave en el archivo. + +## Qué versión de Jev responde + +Los umbrales de decisión de Failproof AI fueron calibrados con Jev 1.13, por lo que una respuesta solo se usa cuando proviene de esa familia: `jev-1.13.x`, o `typesafe/jev-1.13-` de OpenRouter. Cuando un proveedor nombra a Jev solo por un alias y no reporta versión (Vercel, y Cloudflare cuando no lo indica), la respuesta se usa y se registra como no verificada. Un endpoint `custom` debe reportar el modelo que respondió; la única excepción es un nombre `--model` sin versión que configuraste para él, que al ser devuelto se registra como no verificado del mismo modo. Una respuesta que reporta cualquier otra versión, o una respuesta de `custom` que no reporta ninguna, no se usa: esa llamada recurre a regex con la razón `model-mismatch`. + +## Cuando Jev no puede responder + +Cada uno de estos casos recurre al resultado de regex para esa llamada y se registra con su razón, que `failproofai jev status` totaliza: + +| Razón | Causa | +| --- | --- | +| `timeout` | Sin respuesta dentro de `timeoutMs`. | +| `http-429` | El proveedor ha limitado la tasa de la clave. | +| `rate-limited` | El propio limitador de Failproof AI retuvo la llamada antes de enviarla: 5 peticiones por segundo, en ráfagas de hasta 5, y ninguna por un momento tras recibir `429` del proveedor. No es el proveedor. | +| `http-500`, `http-502`, `http-503`, … | Un error del servidor en el proveedor. El estado exacto queda registrado. | +| `out-of-credits` | HTTP 402: la cuenta del proveedor no tiene créditos. | +| `provider-refused` | HTTP 402 de Cloudflare con el mensaje "Model execution failed (Payment error)": el proveedor se negó a ejecutar el modelo en esta petición. Generalmente no es un problema de facturación, así que recargar créditos no lo resolverá. | +| `http-401`, `http-403` | La clave fue rechazada. | +| `http-404` | No hay nada en `/systemone`, por lo que la URL base es incorrecta —se añade `/systemone` a ella, y todos los proveedores la sirven en su raíz de versión. `failproofai jev models` muestra qué sirve el endpoint. | +| `network` | No se pudo alcanzar el endpoint. | +| `http-301`, `http-302`, `http-307`, `http-308` | El endpoint respondió con una redirección. Las redirecciones nunca se siguen, por lo que la respuesta solo llega desde la URL de tu configuración; establece `--base-url` en la URL final. | +| `malformed` | El endpoint respondió, pero no con una respuesta de Jev —un cuerpo que no es JSON, o uno sin respuestas. | +| `cloudflare-error`, `cloudflare-incomplete` | El envoltorio de Cloudflare reportó un fallo, o un trabajo que no había terminado. | +| `model-mismatch` | Respondió una versión de Jev distinta de 1.13, o un endpoint `custom` no indicó qué modelo respondió. | +| `request-cut` | **No es una interrupción.** Jev respondió; solo vio parte de la llamada, así que su respuesta no autorizó nada. Ver [Cuando Jev respondió pero no sobre la llamada completa](#cuando-jev-respondió-pero-no-sobre-la-llamada-completa). | + +`failproofai jev status` también puede mostrar algunas razones más raras, como `upstream-error` (la respuesta llevaba el propio error del proveedor) o `config`, y totaliza cualquier razón que no pueda nombrar como `other`. + +`request-cut` aparece en esta tabla porque `failproofai jev status` lo totaliza junto con los demás, y porque también deja todos los denys en pie. Es la única razón aquí que no dice nada sobre tu proveedor: la petición llegó y Jev la respondió. A diferencia de todas las filas anteriores, esa respuesta sigue contando —el propio deny o advertencia de Jev se aplica además del resultado de regex, en lugar de descartarse. Por tanto, una racha de ellos significa que las llamadas están llegando al evaluador demasiado grandes para enviarse completas, no que tu endpoint tenga problemas, y recargar créditos o cambiar la URL no moverá el contador. + +## Cuando Jev respondió pero no sobre la llamada completa + +Pueden ocurrir otras dos cosas que no significan que Jev haya fallado al responder. Ambas tienen que ver con cuánto de la llamada, o de la conversación, cabía en una sola petición. + +**Parte de la propia llamada no cabía.** Una llamada a herramienta se envía dentro de un presupuesto fijo, y una muy grande —un `Write` enorme, un cuerpo MCP gigante, un comando alargado hasta el límite— se envía con lo que cabía. Jev igualmente responde, y su respuesta igualmente cuenta: su propio deny o advertencia se aplica con normalidad. Lo que no puede hacer es **autorizar** nada, porque un veredicto dado sobre parte de una llamada no es un veredicto sobre la llamada. Así que todos los denys de las políticas se mantienen, y la llamada se registra como fallback con la razón `request-cut`, que `failproofai jev status` totaliza junto con las razones anteriores. La regla que se desprende: hacer una llamada más grande puede costarle sus autorizaciones, y nunca puede ganar ninguna. + +**Un mensaje no cabía.** Un prompt largo que pegaste, el último mensaje del agente, o un prompt que el propio almacén de este evaluador ya había truncado. **Nada cambia**: la llamada se evalúa, autoriza y registra exactamente igual que cualquier otra, y no se cuenta como fallback. La longitud de lo que escribes nunca determina un veredicto, y un truncamiento no puede fabricar consentimiento: cuando un prompt llegó ya truncado, "no pediste esto" deja de ser una conclusión que se pueda extraer, en lugar de convertirse en una. + +La línea entre ambos casos es quién escribió el texto. La llamada es del agente, y una regla que permitiera que su longitud redujera la severidad sería una regla que el agente podría aprovechar; tu prompt es tuyo, y tratar su longitud como señal solo penalizaría pegar una especificación o un stack trace. + +## Qué sale de la máquina + +Para cada llamada a herramienta que Jev evalúa, se envía una petición a tu proveedor con: + +- la propia llamada a herramienta, con secretos como claves de API, tokens bearer y asignaciones `KEY=` redactados; +- los prompts recientes que escribiste, con el texto añadido por el harness de tu agente eliminado; +- el último mensaje del agente antes de tu prompt más reciente, etiquetado como escrito por el agente; +- datos calculados localmente, como si una ruta está dentro del proyecto —el que estaba activo en la sesión en su primera llamada revisada, [fijado para la sesión](/es/reference/jev-intent#the-project-root)— y la rama git actual. + +Solo va al endpoint de tu configuración, con tu clave. + +## Desactivarlo + +```bash +failproofai jev remove +``` + +Esto elimina `~/.failproofai/jev.json`. A partir de la siguiente llamada a herramienta, los hooks ejecutan las políticas de regex exactamente como antes. Los almacenes por sesión en `~/.failproofai/state/semantic/` (prompts registrados en `sessions/`, raíces de proyecto en `roots/`) se dejan en su lugar y expiran con el tiempo. Para dejar de consultar a Jev pero mantener la configuración, usa `failproofai jev setup --mode off` en su lugar. + +## Referencia de comandos + +| Comando | Resultado | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configúralo en un comando; el proveedor se deduce del host de la URL | +| `failproofai jev --url --token ` | Lo mismo, con la clave en la línea de comandos —tu historial y la lista de procesos la verán | +| `failproofai jev setup --provider --key-stdin` | Escribe la configuración desde una clave pasada por stdin | +| `failproofai jev setup --provider ` | Lo mismo, pidiendo la clave en un prompt enmascarado | +| `failproofai jev setup --key-from-env` | No almacena la clave; lee `FAILPROOFAI_JEV_API_KEY` por sesión | +| `failproofai jev setup --mode shadow` | Cambia el modo (`enforce`, `shadow` u `off`), conservando la clave almacenada | +| `failproofai jev setup --model ` / `--base-url ` | Anula el modelo o la base de la API; `default` elimina la anulación | +| `failproofai jev setup --timeout-ms ` | Cambia el presupuesto por llamada | +| `failproofai jev status [--json]` | Configuración, permisos y actividad reciente; nunca la clave | +| `failproofai jev test [--json]` | Una petición real: latencia y la versión que respondió | +| `failproofai jev models [--provider ] [--url ] [--json]` | Los ids de modelo que reporta `/models` del endpoint, marcando el configurado | +| `failproofai jev remove` | Elimina la configuración; Jev queda desactivado | \ No newline at end of file diff --git a/docs/es/policies/jev-cloud.mdx b/docs/es/policies/jev-cloud.mdx new file mode 100644 index 000000000..b477bd5e7 --- /dev/null +++ b/docs/es/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev a través de FailproofAI Cloud" +description: "Permite que Jev evalúe las llamadas a herramientas de tus agentes a través de FailproofAI Cloud, en el plan de tu organización, sin necesidad de cuenta ni clave propia de TypeSafe." +icon: "cloud" +--- + +[Jev](/es/policies/jev-byok), el clasificador de TypeSafe, analiza cada llamada a herramienta en función de lo que realmente solicitaste y emite su veredicto junto a tus políticas, nunca en lugar de ellas. Con **FailproofAI Cloud**, una máquina conectada puede usar Jev con la misma clave con la que ya se conecta: sin cuenta de TypeSafe, sin segunda clave, sin endpoint que configurar. Cada llamada se descuenta de la cuota del plan existente de tu organización. + +Todo lo que hace Jev es idéntico a la [configuración con tu propia clave](/es/policies/jev-byok): las políticas estrictas siguen siendo definitivas, la denegación de una política revisable solo se elimina cuando Jev fue consultado exactamente sobre esa preocupación, y cualquier fallo cae de vuelta al resultado de la expresión regular para esa llamada. + + +Requiere **failproofai 1.0.8-beta.0** o posterior. La versión 1.0.7 no incluye Jev, aunque aparezca por encima de las betas de 1.0.7 en el orden de versiones. Sin una configuración de Jev, nada cambia: los hooks ejecutan las políticas de expresiones regulares exactamente como siempre. + + +## Activación + +1. **Crea una clave con Jev.** En el panel de FailproofAI Cloud, abre **Keys → Create key** y selecciona el preset **machine**. Este concede los tres permisos que necesita una máquina: `events:add` (enviar actividad), `policies:pull` (recibir políticas) y `jev:evaluate` (Jev, descontado de la cuota de tu organización). Una clave no puede tener `jev:evaluate` sin los otros dos. +2. **Conecta la máquina** con esa clave: + + ```bash + failproofai config --token + ``` + + Si tu organización ejecuta su propio FailproofAI Cloud en lugar del alojado, añade su dirección: `--url https://` (o exporta `FAILPROOFAI_CLOUD_URL`). Sin esto, la clave se verifica contra el servicio alojado y la conexión falla. Si el certificado de ese host proviene de una CA privada, instala la CA en el almacén de confianza del sistema de la máquina (por ejemplo, con `update-ca-certificates`), no solo en `NODE_EXTRA_CA_CERTS`: el demonio que envía eventos y obtiene políticas lee el almacén del sistema. Consulta [Solución de problemas](/es/reference/troubleshooting). + +Eso es todo. Al conectar se almacena la clave y, cuando la máquina **no** tiene aún ninguna configuración de Jev, activa Jev a través de FailproofAI Cloud en modo **shadow**: Jev es consultado para cada llamada a herramienta controlada y sus veredictos se registran, pero lo que se aplica es el resultado de tus políticas. La salida lo indica: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**Con `--no-transcripts`, la conexión no activa Jev.** Jev envía cada llamada a herramienta verificada y el prompt reciente a FailproofAI Cloud, lo cual supone más información de la que enviaría una conexión que solo transmite decisiones. La clave se sigue almacenando, y la salida indica que Jev está disponible y cómo activarlo: + +```bash +failproofai jev setup --provider failproofai +``` + +Tampoco **desactiva** Jev. Si el `jev.json` de la máquina ya ejecuta Jev a través de FailproofAI Cloud, se deja tal como está, y la salida indica que Jev sigue enviando cada llamada a herramienta verificada y el prompt reciente, y que `failproofai jev setup --mode off` lo desactiva. + + +La conexión **nunca sobreescribe** un `~/.failproofai/jev.json` existente. Si ya usas tu propio endpoint de Jev, este sigue siendo utilizado, y la salida indica que el archivo se dejó según estaba configurado — y, cuando ese archivo deja Jev desactivado (rechazado o apagado), lo indica y explica cómo solucionarlo. Para cambiar esa máquina a FailproofAI Cloud, ejecuta `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce o desactivado + +Empieza en shadow, observa qué habría hecho Jev en la página de políticas, y luego permite que actúe: + +```bash +failproofai jev setup --mode enforce # Los veredictos de Jev se aplican: puede eliminar una denegación revisable y añadir la suya +failproofai jev setup --mode shadow # Jev es consultado y registrado; se aplica el resultado de tus políticas +failproofai jev setup --mode off # mantiene la configuración, deja de consultar a Jev +``` + +El mismo interruptor está en el panel local: **Settings → Jev** tiene un interruptor de activación/desactivación y shadow/enforce. Reescribe el modo y nada más. Los hooks leen la configuración en cada llamada a herramienta, por lo que un cambio se aplica desde la siguiente, sin necesidad de reiniciar. + +## Verificar su funcionamiento + +```bash +failproofai jev status +failproofai jev test +``` + +`status` muestra el proveedor como **FailproofAI Cloud**, el host de Cloud al que se conectó la máquina, el modo y el origen de la clave como **FailproofAI Cloud connection**, nunca la clave en sí. Cuando hay un `jev.json` de FailproofAI Cloud pero Jev no puede ejecutarse, indica el motivo: + +| `status` indica | `status --json` | Significado | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | La máquina está conectada, pero no hay ninguna clave de Jev almacenada para ella: la clave carece de `jev:evaluate`, o la conexión no pudo confirmarlo. Ejecuta `failproofai config --token ` de nuevo con la misma clave; si le falta el permiso, usa una clave de tipo **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | No hay ninguna conexión de FailproofAI Cloud en esta máquina a la que pertenezca la clave de Jev. | + +Después de `failproofai config --disconnect` ya no existe ningún `jev.json` de FailproofAI Cloud (a menos que estuviera desactivado, en cuyo caso se conserva), por lo que `status` simplemente informa que Jev está desactivado. `status --json` contiene los mismos datos (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), también cuando la configuración está ausente o fue rechazada. `permissions` siempre corresponde al `jev.json`; un rechazo sobre `credentials.json` añade `credentialsPermissions`, y `fix` cuando un único comando lo soluciona. `test` envía una solicitud real y reporta su latencia y la versión de Jev que respondió. Sale con código 1, y así lo indica en su título, cuando la respuesta llega después del tiempo límite del hook (los hooks registrarían `timeout`) o responde incorrectamente a su pregunta de verificación. + +El panel **Settings → Jev** también muestra la **FailproofAI Cloud connection**: a qué organización reporta la máquina y si su clave incluye Jev. Se lee desde los propios archivos de la máquina, sin ninguna llamada de red. + +## Qué llega a la página de políticas + +La máquina ya envía su actividad de hooks a FailproofAI Cloud (`events:add`). Con Jev activado, el registro de cada llamada controlada también indica qué evaluador se ejecutó, qué decidió Jev, qué políticas eliminó, por qué recurrió al fallback cuando lo hizo, su latencia y el modelo que respondió — decisiones, códigos y nombres, nunca el comando ni tu prompt. En la página **Policies** de tu organización: + +- una llamada cuyo resultado fue decidido por el propio veredicto de Jev (modo enforce) se atribuye a **Jev**, y cuando la verificación determinante provino de un pack, el registro también nombra ese pack y su versión; +- en modo shadow, la denegación o advertencia de Jev aparece como **would-have** (lo que habría hecho), junto a los rollouts que estás observando; +- las políticas que Jev eliminó, o habría eliminado en modo shadow, se contabilizan por política. + +## Cuando Jev no puede responder + +Cada uno de estos casos recurre al resultado de tus políticas para esa llamada, y se registra con su motivo: + +| Motivo | Causa | +| --- | --- | +| `out-of-credits` | Tu organización ha agotado la cuota de su plan. | +| `http-401`, `http-403` | La clave fue revocada, o no incluye `jev:evaluate`. Reconéctate con una clave que sí lo tenga. | +| `http-429` | FailproofAI Cloud está aplicando límites de velocidad a Jev para tu organización. Hasta que expire el tiempo de espera indicado (`Retry-After`, máximo 60 segundos), la máquina no le envía nada y cada llamada recurre al fallback de inmediato. Las llamadas retenidas de esta forma se registran como `http-429`, o como `rate-limited` cuando el propio límite de velocidad de la máquina las retiene primero. | +| `http-429` (límite diario) | Tu organización ha agotado sus llamadas diarias a Jev: **10 000 por día UTC**, a menos que quien opere tu FailproofAI Cloud haya establecido otro límite. Todas las llamadas recaen en el fallback hasta que el contador se reinicia a las 00:00 UTC; la máquina sigue intentándolo como máximo una vez por minuto, por lo que detecta el reinicio en menos de un minuto. `failproofai jev test` indica "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev rechazó la solicitud de esta llamada, generalmente porque la llamada a herramienta contenía texto denso (base64, hex, código minificado) que superaba el presupuesto de tokens de Jev. Esa llamada siempre recurre al fallback; no es una interrupción del servicio. | +| `http-502` | Jev no está disponible en este momento. | +| `http-503` | Este Cloud no puede servir Jev para tu organización: sin gateway de modelo, una organización aún no aprovisionada, o el gateway está caído. Consulta a tu administrador; los hooks vuelven a intentarlo como máximo una vez por minuto. | +| `http-404` | Este FailproofAI Cloud aún no sirve Jev. | +| `timeout` | Sin respuesta dentro de `timeoutMs` (predeterminado: 3000). | +| `model-mismatch` | Respondió una versión de Jev distinta a la 1.13. | + +## Dónde se almacena la clave y a dónde va + +- La clave se almacena una sola vez, en `~/.failproofai/credentials.json` (`0600`, en un directorio solo accesible por el propietario), junto a las demás credenciales de FailproofAI Cloud. Para esta ruta, `jev.json` no contiene ninguna clave; si se escribe una allí, la configuración queda inválida. +- Si `credentials.json` tiene **cualquier** permiso para alguien que no seas tú (grupo u otros, lectura o escritura), o si su directorio puede ser **escrito** por alguien que no seas tú, el archivo es **rechazado**, no leído, y Jev permanece desactivado hasta que lo corrijas: `chmod 600` sobre el archivo, `chmod 700` sobre el directorio (o vuelve a conectar, lo que reescribe el archivo a `0600` y deja el directorio solo accesible por el propietario). Un directorio que otros solo pueden leer es aceptable; uno que pueden escribir les permite sustituir el archivo. +- La clave solo cuenta mientras la conexión con la que llegó sigue en la máquina: una credencial de política o reporte para el mismo FailproofAI Cloud **con la misma clave**, en el mismo archivo. Una clave de Jev que quede sin ninguna credencial asociada es ignorada y Jev permanece desactivado. Esto ocurre cuando un `config --disconnect` de una versión anterior de failproofai deja la clave de Jev en su lugar (no sabe que debe eliminarla), o cuando un `config --token` de una versión anterior conecta con otra clave, que en FailproofAI Cloud puede pertenecer a otra organización. Para reactivar Jev, conéctate de nuevo con una clave de tipo **machine**. +- La clave solo se envía al origen de Cloud contra el que fue verificada. Un `jev.json` que apunte a cualquier otro lugar es rechazado. +- **Un agente en la máquina puede leerla.** `credentials.json` solo es accesible por el propietario, y el agente se ejecuta como ese propietario. Leer los propios archivos de failproofai está permitido intencionalmente (solo está bloqueada su modificación, mediante `block-failproofai-commands`), por lo que lo único que hay entre un agente y este archivo es `block-read-outside-cwd` — una política *revisable* — y, en una sesión iniciada en tu directorio home, nada. Una clave con `jev:evaluate` consume la cuota de Jev de tu organización (hasta el límite diario) desde donde sea que se use, así que trata una clave de máquina como cualquier otra credencial de gasto: si un agente puede haberla leído, desactívala en la página de Keys y conéctate de nuevo con una nueva. +- Solo tus archivos globales determinan esto. Un repositorio no puede activar Cloud Jev, apuntarlo a otro lugar ni proporcionar su clave, y `FAILPROOFAI_JEV_API_KEY` se ignora para esta ruta. +- Por cada llamada que evalúa Jev, se envía una solicitud a FailproofAI Cloud con el contenido que lista la [página de bring-your-own-key](/es/policies/jev-byok#what-leaves-the-machine) (secretos redactados). FailproofAI Cloud la reenvía a TypeSafe y no la registra ni la conserva. + +## Desactivación + +| Comando | Resultado | +| --- | --- | +| `failproofai jev setup --mode off` | Conserva la configuración; Jev no es consultado. **Este es el interruptor que persiste:** conectar de nuevo nunca sobreescribe un `jev.json` existente, por lo que Jev permanece desactivado hasta que lo reactives con `--mode shadow`. | +| `failproofai jev remove` | Elimina `~/.failproofai/jev.json`; Jev está desactivado — hasta el próximo `failproofai config --token` con una clave que incluya `jev:evaluate`, que al no encontrar ningún `jev.json` activa Jev de nuevo en modo shadow (a menos que se ejecute con `--no-transcripts`). Para mantenerlo desactivado, usa `--mode off`. | +| `failproofai config --disconnect` | Desconecta la máquina: la clave se elimina, y también el `jev.json` cuando nombra a FailproofAI Cloud y no está desactivado. Un `jev.json` para tu propio endpoint se conserva, al igual que uno que esté desactivado, por lo que Jev permanece desactivado cuando vuelvas a conectar. | + +A partir de la siguiente llamada a herramienta, los hooks ejecutan las políticas de expresiones regulares exactamente como antes. \ No newline at end of file diff --git a/docs/es/policies/jev.mdx b/docs/es/policies/jev.mdx new file mode 100644 index 000000000..773c038d9 --- /dev/null +++ b/docs/es/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Políticas de Jev" +description: "Añade la revisión en tiempo real de Jev a las llamadas a herramientas controladas y examínala antes de aplicar sus decisiones." +icon: "shield-check" +--- + +Jev evalúa una llamada a herramienta comparándola con lo que la persona le pidió al agente que hiciera. Úsalo cuando una política basada en coincidencia de cadenas bloquee trabajo válido o pase por alto una acción arriesgada que requiere contexto. Responde junto con tus políticas en la puerta `PreToolUse` o `PermissionRequest`. Para obtener una puntuación **después** de que finalice una sesión, usa las [evaluaciones de Jev](/es/evaluations/jev). + +## Comienza en modo observación + +Instala Failproof AI y adjunta hooks a un [harness compatible](/es/reference/harnesses). Usa failproofai 1.0.8-beta.0 o posterior. + +Failproof AI no incluye ninguna verificación de Jev. Instálalas como un paquete; de lo contrario, Jev no tiene nada que evaluar y nunca es invocado: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Luego elige cómo llegan las solicitudes a Jev: + +| Ruta | Primer paso | +| --- | --- | +| FailproofAI Cloud | Conéctate con una clave de **máquina** que tenga el permiso `jev:evaluate`. En una máquina sin configuración de Jev, `failproofai config` activa Jev en modo observación. | +| Tu propio proveedor | En el panel local, abre **Settings → Jev**, elige el proveedor, pega su token y selecciona **observe**. O ejecuta `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![La configuración de Jev en el panel local: proveedor, endpoint, token y modo observación antes de activar Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` verifica el endpoint. Para comprobar la ruta del hook, pídele a un agente con hooks que use su herramienta de lectura de archivos sobre `README.md`. Confirma que esa llamada a herramienta aparece en la sesión y luego revisa **Policies → Activity** en el [panel local](/es/reference/local-dashboard#review-policy-activity). El contador de Jev en `status` debería aumentar. El modo observación registra lo que Jev habría decidido, mientras que el resultado de tu política existente sigue aplicándose. + +## Decide cuándo aplicar el cumplimiento + +Una política **estricta** siempre tiene la última palabra. Jev solo puede anular un deny de una política marcada explícitamente como **revisable** y únicamente cuando haya evaluado la preocupación específica de esa política. Consulta la [autoridad de políticas](/es/policies/authority) antes de confiar en una aprobación de Jev. Jev también puede advertir o denegar por cuenta propia. Si no puede dar una respuesta, el resultado de la política decide esa llamada. + +Una vez que los resultados de observación parezcan correctos, cambia al modo de cumplimiento en **Settings → Jev** o ejecuta: + +```bash +failproofai jev setup --mode enforce +``` + +Para URLs de proveedores, claves de Cloud, configuración, opciones de respaldo y los datos enviados con cada solicitud, consulta la [referencia de integración de Jev](/es/reference/jev). \ No newline at end of file diff --git a/docs/es/reference/custom-agents-typescript.mdx b/docs/es/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..753525231 --- /dev/null +++ b/docs/es/reference/custom-agents-typescript.mdx @@ -0,0 +1,433 @@ +--- +title: "Agentes personalizados (TypeScript)" +description: "Configuración, el catálogo de eventos, los scopes y los adaptadores de framework para @failproofai/sdk." +icon: "square-js" +--- + +Todo lo que hace cada configuración, método y campo del SDK de TypeScript. Si es la primera vez que instrumentas, comienza con la guía — esta página es para consultas de referencia. + + + + Instalación, instrumentación, los métodos de eventos, un ejemplo completo y problemas frecuentes. + + + Los mismos eventos, el mismo formato de wire, el mismo spool — desde Python. + + + +Node 20.9 o superior. ESM y CommonJS. Sin dependencias en tiempo de ejecución. + + + Este SDK y el de Python escriben **los mismos eventos en el mismo spool**. Una flota con agentes Node y agentes Python produce un único conjunto de sesiones, no dos, y nada en el dashboard los distingue. Elige según el servicio, no según la empresa. + + +## Instalar + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Los adaptadores de framework vienen incluidos en el propio paquete. Los frameworks son **peer dependencies opcionales** — declaradas para que los rangos compatibles sean visibles, nunca instaladas automáticamente, e importadas solo cuando llamas a `instrument()`. + +## Conectar el daemon de Failproof + +Idéntico al SDK de Python: crea una clave `events:add` en **Admin → Keys**, luego [conecta el daemon](/es/start/setup#connect-a-machine-to-cloud) en la máquina del agente. El SDK escribe en disco; el daemon envía. + +## Configuración + +### Spans de OpenTelemetry (opt in) + +Instala OpenTelemetry por separado con `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Luego añade FailproofAI a los procesadores de tu proveedor: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Para un proveedor existente, mantén sus otros procesadores en la misma lista. Los proveedores +que exponen `addSpanProcessor` también pueden pasarse como `{ provider }`. Sin +opciones, la configuración registra un nuevo proveedor solo si aún no hay ninguno registrado. +`OtelSpanExporter` también puede usarse directamente con tu propio procesador. + +Las exportaciones pasan por el daemon de FailproofAI conectado; el SDK no envía ninguna +solicitud de red y no necesita clave ni listener local. Pide a un administrador que habilite +la [ingesta de OpenTelemetry](/es/agenteye/opentelemetry). Un `instrument()` sin opciones no +habilita este exportador. `uninstrument("otel")` deshabilita únicamente su propio procesador. +Los atributos de tus spans controlan la captura de contenido; haz flush de tu proveedor antes de salir. +OpenTelemetry sigue siendo una dependencia de aplicación opcional, no una dependencia fija del SDK. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Opción | Qué hace | +| --- | --- | +| `environment` | La etiqueta en cada evento — `production`, `staging`, `prod-eu`. Por defecto `dev`. | +| `flushInterval` | Con qué frecuencia el timer escribe en disco, en segundos. Por defecto `0.5`. | +| `baseDir` | Dónde escribir. Por defecto en el spool del daemon, que es lo que quieres salvo que sepas lo que haces. | + +Nada se aplica a menos que todo se valide correctamente, así que una llamada rechazada deja el SDK exactamente como estaba en lugar de quedar con un nuevo `baseDir` y el intervalo anterior. + +Configurar mediante variable de entorno: + +| Variable | Qué hace | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Establece `environment` sin cambiar el código. Una opción de `configure()` tiene prioridad. | +| `FAILPROOFAI_HOME` | Mueve la raíz de Failproof AI que contiene el spool. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (por defecto), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` hace que los errores de instrumentación lancen excepciones en lugar de registrarse. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` hace que un problema de compatibilidad con un framework lance una excepción en lugar de advertir y continuar. | + + + **Sin comas en `environment`.** La ingesta divide ese campo por comas para construir sus filtros, y descarta cualquier evento cuya etiqueta contenga una — así que toda una ejecución desaparece silenciosamente. Escribe `prod-eu`, no `prod,eu`. + + `configure({ environment: "prod,eu" })` lanza una excepción para que lo descubras de inmediato. `AGENTEYE_ENVIRONMENT` no puede lanzar excepciones — nadie te está llamando — así que advierte una vez y vuelve a `dev`. + + +Redirige las líneas de log del propio SDK hacia tu logger con `failproofai.setLogger({ debug, info, warn, error })`. + +## Apagado + +Los eventos en buffer se vacían en `process.on("exit")`. + +Un proceso terminado por una señal nunca llega a ese punto, y el comportamiento por defecto de Node para `SIGTERM` es terminar sin ejecutar los exit handlers — así que un agente en contenedor pierde lo que el último intervalo no había escrito. + + + **Este SDK no instalará un manejador de señales por ti.** Registrar uno cambia el comportamiento de tu proceso: un listener suprime la terminación por defecto de Node, así que una biblioteca que añadiera uno detendría silenciosamente el funcionamiento de Ctrl-C. Añade el tuyo: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Un script de corta duración o un handler serverless debería ejecutar `await failproofai.flush()` antes de retornar — el intervalo por sí solo no garantiza la entrega. + +## Identidad + +Cada evento pertenece a una sesión y un agente. **Los scopes rellenan ambos**, así que rara vez los pasas explícitamente: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Pasar `sessionId` o `agentId` explícitamente sigue funcionando y tiene prioridad. Si no hay ninguno vinculado ni pasado, la llamada lanza una excepción en lugar de emitir un evento que Cloud descartaría silenciosamente. + + + La identidad viaja en `AsyncLocalStorage`. Sigue a `await`, `.then()`, timers y cualquier callback creado dentro del scope. **No** sigue a un callback almacenado durante una ejecución e invocado durante otra, ni al trabajo transferido a través de un límite de `worker_threads` — envuelve esos en `failproofai.propagate()` o sus eventos quedarán sin asociar. + + +### Scopes + +| Scope | Emite | Retorna | +| --- | --- | --- | +| `session(body)` | nada — solo identidad | lo que retorne `body` | +| `agent(id, options?, body)` | `agent_start`, luego `agent_end` | lo que retorne `body` | +| `toolCall(name, options?, body)` | `tool_use`, luego `tool_result` | lo que retorne `body` | + +Un body síncrono se mantiene síncrono: `agent("x", () => 1)` retorna `1`, no una promesa. + +`toolCall` registra el valor resuelto del body como el `output` de la herramienta, a menos que asignes `call.output` tú mismo. + + + +| Qué ocurrió | Eventos | `outcome` | +| --- | --- | --- | +| el bloque retornó | `agent_end` | `"success"`, o tu `outcome` | +| el bloque lanzó una excepción | `error`, luego `agent_end` | `"failed"` | +| un `AbortError` | solo `agent_end` | `"cancelled"` | + +El error siempre se relanza. + +Un fallo de herramienta se registra en la hoja — `tool_result` con un string `error` — y **no** emite ningún evento `error` a nivel de ejecución. El que captura el bucle del agente no es un fallo de ejecución, y el que se propaga se reporta exactamente una vez, por el `agent()` que lo contiene. + + + + + +Cuando el trabajo no es una única función — un scope abierto en un constructor y cerrado en un teardown, o uno que atraviesa flujos de control existentes: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +Ambas formas emiten eventos idénticos byte a byte. Prefiere la forma de callback: se ejecuta dentro de `AsyncLocalStorage.run()`, así que no hay nada que deshacer y toda la clase de errores "abierto aquí, cerrado allá" es inalcanzable. + +Un bloque `using` que captura su propio fallo lo reporta con `span.fail(error)` — el disposer no tiene canal propio para excepciones. + + + +## Catálogo de eventos + +Los mismos quince métodos que el SDK de Python, en camelCase. La mayoría vienen en **pares** — llamas al abridor, luego al cerrador, y el SDK mide el intervalo. + +| | Abre | Cierra | +| --- | --- | --- | +| **Agentes** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Modelos** | `modelRequest` | `modelResponse` | +| **Herramientas** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Humanos** | `humanWait` | `humanInput` | + +Tres son independientes: `error`, `humanPause`, `humanInterrupt`. + + + +Cada método también acepta `sessionId` y `agentId`, que los scopes rellenan por ti. Cualquier campo omitido se descarta en lugar de enviarse como JSON `null`. + +| Método | Requeridos | Opcionales | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Cualquier otra clave que añadas se convierte en un campo de payload personalizado. Pon el prefijo `fw_*` a todo lo específico del framework; un nombre que colisione con un campo declarado será rechazado en lugar de sobrescribir silenciosamente una columna promovida. + + + + + **`duration_ms` se calcula, no se acepta.** Los cuatro métodos de cierre miden el intervalo desde su abridor y rechazan un `duration_ms` proporcionado por el llamador — una duración reportada debe ser infalsificable. + + Los pares se emparejan por **sesión** y por id, nunca por agente. Una herramienta abierta bajo `planner` y cerrada bajo `worker` sigue emparejando, que es exactamente lo que hacen las ejecuciones multi-agente anidadas. + + +## Adaptadores de framework + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| Framework | Compatible | Cómo se adjunta | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, así cada `invoke`/`stream`/`batch` queda cubierto sin pasar `callbacks:` en ningún sitio — o pasa `langchainHandler()` tú mismo y no parchea nada. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` en el punto de llamada, o `instrument("ai")` para todo el proceso con `ai` 7 (en 4–6 es opt-in — ver más abajo). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, la resolución del modelo y herramientas del agente, y el motor de ejecución de workflow/step. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (suscrito) más `AgentWorkflow.runStream`, para ejecuciones de workflow y sus steps. | + +Cada rango se prueba contra versiones reales del framework, en ambos extremos, como ES module y como CommonJS, en cada ejecución de CI. + +El mapeo es el del SDK de Python, así que el mismo programa dibuja el mismo árbol en cualquier lenguaje. Una construcción es un **agente** solo si posee un bucle de decisión LLM — una ejecución de grafo o cadena, una llamada `generateText`/`streamText` del AI SDK, un agente de Mastra, una ejecución de agente de LlamaIndex. Un nodo de LangGraph o un step de workflow es un **hook** (`hook_triggered`/`hook_completed`), nunca un agente anidado. Las llamadas a modelos son pares `model_request`/`model_response` con conteos de tokens; las llamadas a herramientas llevan el id propio de llamada de herramienta del modelo. Un fallo se registra una vez, en el evento en el que ocurrió. + +Un adaptador que falla al instalarse se registra y se omite; los demás se instalan igualmente, porque un LlamaIndex roto no debería costarte LangGraph. + + + `instrument()` sin argumento detecta un framework según si **resuelve**, no según si ya está importado — Node no expone ningún equivalente de `sys.modules` de Python para módulos ES. Un framework que tengas instalado pero no uses será importado y parcheado. Especifica el que quieres si eso importa. + + + + La mayoría de estos frameworks incluyen una build de módulo ES y una build de CommonJS, que Node carga como dos copias no relacionadas. Los adaptadores parchean la copia que carga tu aplicación (y también la copia CommonJS si algo ya la había importado con `require`), así que ambos sistemas de módulos funcionan. Un framework **empaquetado en tu propia salida** por esbuild o webpack está fuera de alcance — usa los helpers en el punto de llamada: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain sin parcheo + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +El handler funciona con o sin `instrument()` y nunca registra duplicados. `instrument("langchain")` acepta `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` y `captureLimit`, igual que el adaptador de Python; `metadata: { failproofai_sdk_session_id }` en una llamada selecciona la sesión para esa invocación. + +### Vercel AI SDK + +El AI SDK exporta funciones simples desde un módulo ES, y un namespace de módulo ES es inmutable por especificación — no hay dónde parchear. Usa los puntos de extensión que el propio SDK documenta: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +Esa es la integración completa: un span de agente, un par de request/response de modelo por step con conteos de tokens, y cada llamada a herramienta. Un punto de llamada funciona en todos los majors — `ai` 4–6 lee el tracer que lleva, `ai` 7 la integración de telemetría. + +`instrument("ai")` hace lo mismo para todo el proceso **en `ai` 7**: cada llamada, a través de la lista global de integración de telemetría del AI SDK, que es aditiva y no quita nada a nadie. + +**En `ai` 4–6, `instrument("ai")` no registra nada por sí solo y registra una advertencia al respecto.** El único hook para todo el proceso que tienen esos majors es el proveedor global de trazas de OpenTelemetry — un único slot que OpenTelemetry se niega a ceder una vez tomado. Registrar el nuestro rechazaría silenciosamente tu propio `NodeSDK.start()` más adelante en el arranque y enviaría tus spans de http/base de datos a un tracer que no exporta nada. Usa `telemetry()` en el punto de llamada o `wrapModel` allí. Si el proceso no tiene OpenTelemetry propio, actívalo con `instrument("ai", { registerGlobalTracer: true })`: entonces registra cada llamada que pase `experimental_telemetry: { isEnabled: true }`, y solo toma el slot si aún está vacío. `registerGlobalTracer: false` mantiene el comportamiento por defecto y silencia la advertencia. + +Si prefieres envolver el modelo una sola vez, `wrapModel` solo ve las llamadas al modelo, porque las llamadas a herramientas ocurren por encima de la capa del modelo. Un modelo envuelto llamado sin nada alrededor se registra como su propia ejecución. Una llamada en streaming se cierra como sea que el stream se detenga — `stop_reason: "cancelled"` cuando el consumidor lo cancela, `"error"` con el error cuando falla a mitad: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Usar ambos está bien: el middleware detecta que la llamada ya está siendo registrada y cede, así que cada llamada se registra una vez. + +`functionId` nombra el span del agente. Mantenlo de baja cardinalidad — cae en `agent_id`, la faceta principal del dashboard. + +### Next.js + +`next build` empaqueta las dependencias de tu servidor por defecto, y un framework empaquetado en la build es una copia que `instrument()` no puede alcanzar. Envuelve la configuración una vez y llama a `instrument()` desde el hook de arranque de Next: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` añade LangChain, Mastra, LlamaIndex y el propio SDK a `serverExternalPackages`, manteniendo tu propia lista. Sin él, `instrument()` advierte una vez por framework que no puede alcanzar en lugar de fallar silenciosamente; si listas los paquetes tú mismo, establece `FAILPROOFAI_NEXT_EXTERNALS=1`. El Vercel AI SDK y los helpers en el punto de llamada funcionan en cualquier caso. Una ruta Edge obtiene una build no-op: importar el SDK es seguro y no registra nada. + +### Conteos de tokens en llamadas en streaming + +Las APIs compatibles con OpenAI solo reportan el uso en un stream cuando el cliente lo solicita. LangChain y el Vercel AI SDK lo solicitan; para LlamaIndex pasa `additionalChatOptions: { stream_options: { include_usage: true } }` a su LLM `OpenAI`, y para Mastra construye el modelo con el uso habilitado (por ejemplo `createOpenAICompatible({ includeUsage: true })`). De lo contrario, las llamadas a modelos en streaming no llevan conteos de tokens. + +### Runtimes + +Node ≥ 20.9, Bun y Deno — cada framework, como ES module y como CommonJS, se prueba en cada uno comparando con la traza de Node. El SDK corre junto al daemon `failproofaid`, que envía lo que escribe. + +## Tu propio agente — sin framework + +Para un bucle de agente que escribiste tú mismo, o un framework sin adaptador. Emites los eventos con la misma API que usan los adaptadores internamente, así que la traza tiene la misma forma y calidad. + +No necesitas saber cómo está organizado el agente. Todo agente construido a mano ya tiene tres lugares, se llamen como se llamen sus funciones, y esos tres son toda la integración: + +| Dónde | Qué añadir | Emite | +| --- | --- | --- | +| Donde **una ejecución** comienza y termina | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| La **única función que llama al modelo** | `event.modelRequest` antes, `event.modelResponse` después — ambas mitades, incluso en caso de fallo | un par por turno del modelo | +| La **única función que ejecuta herramientas** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +La identidad es ambiental: todo lo que está dentro de `agent()` aterriza en la sesión de esa ejecución sin necesitar un id, y nada más en el programa cambia — incluido lo que el agente ya escribe en su propia base de datos. + +- **Un servicio o un worker:** pasa tu propio id de request o job como `sessionId`, así una sesión en el dashboard y el registro en tus propios logs o base de datos son el mismo string. +- **Sub-agentes:** anida llamadas a `agent()`. El interior se une a la sesión con el exterior como su `parent_id`. +- **Emite los pares.** Un `modelRequest` sin `modelResponse` es un span que el dashboard muestra como ejecutándose eternamente — de ahí el `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) en el repositorio es la versión completa y ejecutable: un bucle real de herramientas de OpenAI instrumentado exactamente así, ejecutado en CI en cada cambio como ES module y como CommonJS. + +## Evaluaciones + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Consulta la [referencia del SDK del Evaluador](/es/reference/evaluator-sdk) para el protocolo, la configuración del worker y los tipos de resultado. + + + **Una evaluación debe ceder el control.** Una función síncrona que nunca retorna bloquea el único hilo que tiene Node, y ningún timeout puede dispararse mientras lo hace. Escribe evaluaciones `async`. + + +## Lo que no hará a tu proceso + +| | | +| --- | --- | +| **Bloquear tu bucle de agente** | Los eventos van a una cola en memoria; un timer los escribe. El timer tiene `unref`, así que importar este paquete nunca impide que un script termine. | +| **Crecer sin límite** | La cola tiene un límite por conteo *y* por bytes medidos. Pasado cualquiera, los eventos más antiguos se descartan y una advertencia lo indica — una interrupción en la telemetría no debe convertirse en un OOM kill. | +| **Tumbar el proceso** | Un evento que no se puede codificar se descarta solo, no el lote que lo rodea. Un getter que lanza, una referencia circular, un `BigInt`, un surrogate solitario: cada uno se gestiona en lugar de propagarse. | +| **Dejar un lote a medio escribir** | El contenido se sincroniza con `fsync` antes de un renombrado atómico, el directorio se sincroniza con `fsync` después, y un write fallido limpia su archivo temporal. | +| **Dejar las transcripciones legibles** | Los lotes tienen permisos `0600` dentro de un directorio `0700`. Contienen objetivos, prompts, argumentos de herramientas y salidas de herramientas. | +| **Enviar credenciales** | Las API keys, tokens, JWTs, cabeceras bearer y asignaciones con forma de secreto se redactan antes de que los bytes lleguen al disco. El daemon redacta de nuevo antes de la subida. | \ No newline at end of file diff --git a/docs/es/reference/custom-agents.mdx b/docs/es/reference/custom-agents.mdx index 24e10f98a..8e549de0d 100644 --- a/docs/es/reference/custom-agents.mdx +++ b/docs/es/reference/custom-agents.mdx @@ -15,7 +15,7 @@ Qué hace cada configuración, método y campo. Si es la primera vez que instrum -Python 3.10 o superior. Sin dependencias en tiempo de ejecución. +Python 3.11 o superior. Sin dependencias en tiempo de ejecución. ## Instalar diff --git a/docs/es/reference/jev-cloud.mdx b/docs/es/reference/jev-cloud.mdx new file mode 100644 index 000000000..3652399ab --- /dev/null +++ b/docs/es/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev a través de FailproofAI Cloud" +description: "Claves de máquina en la nube, estado de conexión, límites y comportamiento ante fallos para la revisión de políticas Jev en tiempo real." +icon: "cloud" +--- + +Esta es la referencia de la ruta Cloud para las [políticas Jev](/es/policies/jev). Jev, el clasificador de TypeSafe, analiza cada llamada a herramienta comparándola con lo que realmente solicitaste y responde junto con tus políticas, nunca en lugar de ellas. A través de **FailproofAI Cloud**, una máquina conectada usa Jev con la misma clave con la que ya se conecta: sin cuenta de TypeSafe, sin segunda clave, sin ningún endpoint que configurar. Cada llamada se carga a la cuota del plan existente de tu organización. + +Todo lo que hace Jev no cambia respecto a la [configuración con clave propia](/es/reference/jev-providers): las políticas estrictas siguen siendo definitivas, el rechazo de una política revisable solo se elimina cuando Jev fue consultado exactamente sobre esa preocupación, y cualquier fallo recurre al resultado de la expresión regular para esa llamada. + + +Requiere **failproofai 1.0.8-beta.0** o posterior. La versión 1.0.7 no tiene Jev, aunque aparezca por encima de las betas de 1.0.7 en el orden de versiones. Sin una configuración de Jev nada cambia: los hooks ejecutan las políticas de expresiones regulares exactamente como siempre. + + +## Antes de empezar + +Instala Failproof AI en la máquina donde se ejecuta tu agente y conecta sus hooks a un [harness compatible](/es/reference/harnesses). Si estás empezando desde cero, sigue la [guía de inicio rápido](/es/start/quickstart) hasta la instalación de hooks. Verifica la CLI instalada con `failproofai --version`; actualízala si es anterior a Jev. También necesitas acceso a la página **Administración → Claves** de tu organización para crear una clave de máquina. + +Jev revisa llamadas a herramientas con nombre en la barrera `PreToolUse` o `PermissionRequest`. No revisa todos los eventos de una sesión. Para que Jev elimine el rechazo de una política, necesitas una política instalada marcada como [revisable](/es/policies/authority); todos los demás rechazos de políticas siguen siendo definitivos. + +## Activarlo + +1. **Crea una clave con Jev.** En el panel de control de FailproofAI Cloud, abre **Administración → Claves → Crear clave** y elige el perfil **máquina**. Otorga los tres permisos que una máquina necesita: `events:add` (enviar actividad), `policies:pull` (recibir políticas) y `jev:evaluate` (Jev, que se carga al plan de tu organización). Una clave no puede tener `jev:evaluate` sin los otros dos. +2. **Conecta la máquina** con esa clave. Lee su secreto de un solo uso en un prompt y luego ejecuta el comando de configuración completo: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` instala el daemon, conecta los hooks para las CLIs de agentes que encuentre y conecta la máquina. La variable de entorno mantiene la clave fuera de los argumentos del comando y del historial de tu shell. Si tu harness se instaló más tarde, [conéctalo explícitamente](/es/start/quickstart). + + Si tu organización utiliza su propia instancia de FailproofAI Cloud en lugar de la alojada, añade su dirección: `--url https://` (o exporta `FAILPROOFAI_CLOUD_URL`). Sin esto, la clave se verifica contra el servicio alojado y la conexión falla. Si el certificado de ese host proviene de una CA privada, instala la CA en el almacén de confianza del sistema de la máquina (por ejemplo con `update-ca-certificates`), no solo en `NODE_EXTRA_CA_CERTS`: el daemon que envía eventos y descarga políticas lee el almacén del sistema. Consulta [Solución de problemas](/es/reference/troubleshooting). + +Eso es todo. Al conectarse, se almacena la clave y, cuando la máquina **no** tiene configuración de Jev, se escribe una para FailproofAI Cloud. Desde el primer despliegue de la máquina (en unos 30 s), FailproofAI Cloud establece el modo: `enforce` mientras haya una política Jev desplegada en ella, `off` cuando no haya ninguna (consulta [Quién establece el modo](#who-sets-the-mode)). La salida lo indica: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Las verificaciones que despliega FailproofAI Cloud se ejecutan en Cloud. Para añadir verificaciones propias en la máquina, instala un pack: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**Con `--no-transcripts`, la conexión no activa Jev.** Jev envía cada llamada a herramienta verificada y el prompt reciente a FailproofAI Cloud, lo cual supone más información de la que una conexión de solo decisiones fue configurada para enviar. La clave se almacena igualmente, y la salida indica que Jev está disponible y cómo activarlo: + +```bash +failproofai jev setup --provider failproofai +``` + +También desactiva Jev a través de FailproofAI Cloud. Un `jev.json` que ejecuta Jev a través de FailproofAI Cloud (dejado por una conexión anterior con transcripts activados) se elimina, por la misma regla que usa `config --disconnect`, y la salida indica que Jev vía FailproofAI Cloud permanece desactivado en esta máquina. Un `jev.json` para tu propio endpoint de Jev se deja tal como está, igual que uno de FailproofAI Cloud que hayas desactivado (`--mode off`). + + +La conexión **nunca sobreescribe** un `~/.failproofai/jev.json` existente. Si ya usas tu propio endpoint de Jev, seguirá usándose, y la salida indica que el archivo se dejó tal como estaba configurado — y, cuando ese archivo deja Jev desactivado (rechazado o desactivado manualmente), lo indica junto con cómo solucionarlo. Para cambiar esa máquina a FailproofAI Cloud, ejecuta `failproofai jev setup --provider failproofai`. + + +## Quién establece el modo + +En una máquina conectada a FailproofAI Cloud, **FailproofAI Cloud establece el modo de Jev**; nada en la máquina lo hace: + +- `enforce` mientras haya alguna política Jev (o regex + Jev) desplegada en la máquina: cada llamada a herramienta verificada de un agente al que apunta alguna de esas políticas va a FailproofAI Cloud, que ejecuta sus verificaciones junto con las de los packs instalados allí. Una llamada de un agente al que ninguna política Cloud Jev apunta, sin ninguna verificación propia de pack, no se envía en absoluto. En modo `enforce`, las verificaciones propias de rechazo de Jev bloquean llamadas además de limpiar los veredictos de expresiones regulares que revisan. +- `off` cuando no hay ninguna: sin Jev en absoluto, independientemente de lo que diga `jev.json`. + +Para probar una política Jev antes de que actúe, despliégala con efecto **observe**: sus verificaciones se siguen ejecutando, y lo que habrían hecho se registra como **would-have** en la página de la política, pero nunca bloquea una llamada ni limpia ninguna. `failproofai jev setup --mode` y el interruptor **Configuración → Jev** del panel indican que el modo está gestionado por FailproofAI Cloud y no cambian nada. `jev.json` no se usa para las verificaciones de Cloud, aunque nombre otro proveedor. `failproofai config --disconnect` devuelve Jev al `jev.json` propio de la máquina. + +`failproofai jev status` entonces muestra `Jev checks run on FailproofAI Cloud (mode: enforce)`. También nombra las verificaciones que revisan cada política `both`. La página de flota muestra por qué una máquina con un modo no puede preguntar: + +- `transcripts_disabled`: la máquina se conectó con `--no-transcripts`, lo que nunca activa Jev. +- `jev_unconfigured`: la clave de la máquina no tiene `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud rechazó algunas llamadas de la máquina por el límite de tasa de Jev de la organización, y esas llamadas fueron decididas únicamente por las políticas de expresiones regulares. +- `jev_unavailable`: varias llamadas seguidas fallaron, por lo que la máquina omite el Jev de FailproofAI Cloud durante un minuto cada vez. Reintenta por sí sola. + +Si FailproofAI Cloud no responde en 5 segundos, las políticas de expresiones regulares deciden solas, como con cualquier interrupción de Jev. Tras 3 fallos consecutivos, la máquina deja de preguntar durante un minuto cada vez, para que una interrupción de Cloud no ralentice cada llamada a herramienta. + +Una pausa de sesión (`failproofai config --pause`) no detiene las verificaciones Jev de FailproofAI Cloud, igual que no detiene las políticas gestionadas por Cloud. Sí pausa las verificaciones Jev de los packs instalados en la máquina. + +## Comprobar qué está haciendo + +```bash +failproofai jev status +failproofai jev test +``` + +`status` muestra el proveedor como **FailproofAI Cloud**, el host de Cloud al que se conectó la máquina, el modo y el origen de la clave como **FailproofAI Cloud connection**, nunca la clave en sí. Cuando hay un `jev.json` de FailproofAI Cloud pero Jev no puede ejecutarse, indica el motivo: + +| Lo que dice `status` | `status --json` | Significado | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | La máquina está conectada, pero no hay ninguna clave Jev almacenada para ella: a la clave le falta `jev:evaluate`, o la conexión no pudo confirmarlo. Ejecuta `failproofai config` de nuevo con la clave en `FAILPROOFAI_CLOUD_TOKEN`; si le falta el permiso, usa una clave de **máquina**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | No hay conexión con FailproofAI Cloud en esta máquina a la que pertenezca la clave Jev. | + +Después de `failproofai config --disconnect` ya no hay ningún `jev.json` de FailproofAI Cloud (a menos que estuviera desactivado, que se conserva), por lo que `status` simplemente reporta Jev como desactivado. `status --json` contiene los mismos datos (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), también cuando la configuración está ausente o rechazada. `permissions` siempre corresponde a `jev.json`; un rechazo relacionado con `credentials.json` añade `credentialsPermissions`, y `fix` cuando un comando lo soluciona. `test` envía una solicitud en tiempo real e informa de su latencia y la versión de Jev que respondió. Sale con código 1, e indica el motivo en su título, cuando la respuesta llega después del timeout del hook (los hooks registrarían `timeout`) o responde incorrectamente a su pregunta de verificación. + +El panel **Configuración → Jev** del panel de control también muestra la **FailproofAI Cloud connection**: en qué organización reporta la máquina y si su clave tiene Jev. Se lee de los propios archivos de la máquina, sin ninguna llamada de red. + +## Verificar una llamada real + +Inicia una nueva sesión en el agente con hooks. Pídele que use su herramienta de lectura de archivos sobre `README.md` e informe del título. Confirma que la sesión contiene esa llamada a herramienta y luego ejecuta `failproofai jev status` de nuevo: el recuento de llamadas evaluadas recientemente debería aumentar. Abre **Políticas → Actividad** en el [panel local](/es/reference/local-dashboard#review-policy-activity) para inspeccionar el veredicto Jev y el modo de esa llamada. En Cloud, la página **Políticas** de la organización muestra los resultados de Jev para la actividad entregada. En modo observe, el veredicto se registra como **would-have** y el resultado de la política sigue decidiendo la llamada. Una autorización aparece solo cuando una política revisable coincidió y Jev liberó sus verificaciones nombradas. + +## Qué llega a la página de políticas + +La máquina ya envía su actividad de hooks a FailproofAI Cloud (`events:add`). Con Jev activado, el registro de cada llamada verificada también indica qué evaluador se ejecutó, qué decidió Jev, qué políticas liberó, por qué recurrió al fallback cuando lo hizo, su latencia y el modelo que respondió — decisiones, códigos y nombres, nunca el comando ni tu prompt. En la página **Políticas** de tu organización: + +- una llamada que el propio veredicto de Jev decidió (modo enforce) se atribuye a **Jev**, y cuando la verificación decisiva provino de un pack, el registro también nombra ese pack y su versión; +- en modo observe, el rechazo o advertencia de Jev aparece como **would-have**, junto a los despliegues que estás observando; +- las políticas que Jev liberó, o habría liberado en modo observe, se contabilizan por política. +- una decisión en la que Jev participó (un bloqueo, una advertencia, una autorización, o un would-have en modo observe) lista cada verificación que realizó y lo que concluyó: veredicto, motivo (`not-detected`, `exempt`, `fired`, `op-requested`, …), su evidencia `p`, la respuesta `exempt` y la respuesta de cada sonda. También se lista una verificación de una política desplegada en modo observe (watch), marcada como vigilada; nunca bloquea. Jev responde con probabilidades, no con texto libre, por lo que no hay motivo en texto plano. Las autorizaciones simples se agrupan en conteos y no llevan esta lista. + +## Cuando Jev no puede responder + +Cada uno de estos casos recurre al resultado de tus políticas para esa llamada y se registra con su motivo: + +| Motivo | Causa | +| --- | --- | +| `out-of-credits` | Tu organización ha agotado la cuota de su plan. | +| `http-401`, `http-403` | La clave fue revocada, o no tiene `jev:evaluate`. Reconecta con una clave que sí lo tenga. | +| `http-429` | FailproofAI Cloud está aplicando límite de tasa a Jev para tu organización. Hasta que transcurra el tiempo de espera solicitado (su `Retry-After`, como máximo 60 segundos), la máquina no envía nada y cada llamada recurre inmediatamente al fallback. Las llamadas retenidas de ese modo se registran como `http-429`, o como `rate-limited` cuando el límite de tasa propio de la máquina las retiene primero. | +| `http-429` (límite diario) | Tu organización ha agotado sus llamadas diarias a Jev: **10 000 por día UTC**, a menos que quien opera tu FailproofAI Cloud haya establecido otro límite. Cada llamada recurre al fallback hasta que el contador se restablezca a las 00:00 UTC; la máquina sigue preguntando como máximo una vez por minuto, por lo que detecta el restablecimiento en menos de un minuto. `failproofai jev test` muestra "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev rechazó la solicitud de esta llamada, normalmente porque la llamada a herramienta contenía texto denso (base64, hex, código minificado) por encima del presupuesto de tokens de Jev. Esa llamada siempre recurre al fallback; no es una interrupción. | +| `http-502` | Jev no está disponible en este momento. | +| `http-503` | Este Cloud no puede servir Jev para tu organización: sin pasarela de modelo, una organización aún no aprovisionada, o la pasarela está caída. Contacta con tu administrador; los hooks vuelven a preguntar como máximo una vez por minuto. | +| `http-404` | Este FailproofAI Cloud aún no sirve Jev. | +| `timeout` | Sin respuesta en `timeoutMs` (por defecto 3000). Mientras FailproofAI Cloud establece el modo Jev de la máquina, la espera es de 5000 ms y no se usa el `timeoutMs` de `jev.json`. | +| `model-mismatch` | Respondió una versión de Jev distinta a la 1.13. | + +## Dónde vive la clave y adónde va + +- La clave se almacena una sola vez, en `~/.failproofai/credentials.json` (`0600`, en un directorio de solo propietario), junto a las demás credenciales de FailproofAI Cloud. `jev.json` no guarda ninguna clave para esta ruta; una escrita allí hace inválida la configuración. +- Si `credentials.json` tiene **cualquier** permiso para alguien que no seas tú (grupo u otros, lectura o escritura), o su directorio puede ser **escrito** por alguien que no seas tú, se **rechaza**, no se lee, y Jev permanece desactivado hasta que lo soluciones: `chmod 600` sobre el archivo, `chmod 700` sobre el directorio (o reconecta, lo que reescribe el archivo con `0600` y hace el directorio de solo propietario). Un directorio que otros solo puedan leer está bien; uno que puedan escribir les permite reemplazar el archivo. +- La clave solo cuenta mientras la conexión con la que llegó esté en la máquina: una credencial de política o de reporting para el mismo FailproofAI Cloud **con la misma clave**, en el mismo archivo. Una clave Jev dejada sin una se ignora y Jev permanece desactivado. Esto ocurre cuando el `config --disconnect` de una versión anterior de failproofai deja la clave Jev en su sitio (no sabe que debe eliminarla), o cuando el `config --token` de una versión anterior de failproofai conecta con otra clave, que en FailproofAI Cloud puede pertenecer a otra organización. Para volver a activar Jev, conéctate de nuevo con una clave de **máquina**. +- La clave solo se envía al origen de Cloud contra el que fue verificada. Un `jev.json` que apunte a otro lugar se rechaza. +- **Un agente en la máquina puede leerla.** `credentials.json` es de solo propietario y el agente se ejecuta como ese propietario. Leer los propios archivos de failproofai está permitido a propósito (solo se bloquea modificarlos, mediante `block-failproofai-commands`), por lo que lo único que se interpone entre un agente y este archivo es `block-read-outside-cwd` — una política *revisable* — y desde una sesión iniciada en tu directorio home, nada. Una clave con `jev:evaluate` gasta la cuota Jev de tu organización (hasta el límite diario) desde donde sea que se use, así que trata una clave de máquina como cualquier otra credencial de gasto: si un agente puede haberla leído, desactívala en la página de Claves y reconecta con una nueva. +- Solo tus archivos globales deciden esto. Un repositorio no puede activar Cloud Jev, apuntarlo a otro lugar ni proporcionar su clave, y `FAILPROOFAI_JEV_API_KEY` se ignora para esta ruta. +- Por cada llamada que Jev evalúa, se envía una solicitud a FailproofAI Cloud con lo que lista la [página de clave propia](/es/reference/jev-providers#what-leaves-the-machine) (secretos redactados). FailproofAI Cloud la reenvía a TypeSafe y no la registra ni la conserva. + +## Desactivarlo + +En una máquina conectada, Jev está desactivado cuando FailproofAI Cloud no despliega ninguna política Jev en ella: elimina o archiva las políticas Jev allí. + +| Comando | Resultado | +| --- | --- | +| Eliminar las políticas Jev de la máquina en FailproofAI Cloud | El modo de Cloud pasa a `off` en el siguiente sondeo (unos 30 s): sin Jev en absoluto, independientemente de lo que diga `jev.json`. | +| `failproofai config --disconnect` | Desconecta la máquina: la clave se elimina, y también `jev.json` cuando nombra a FailproofAI Cloud y no está desactivado. Un `jev.json` para tu propio endpoint permanece. | + +A partir de la siguiente llamada a herramienta, los hooks ejecutan las políticas de expresiones regulares exactamente como antes. \ No newline at end of file diff --git a/docs/es/reference/jev-evaluations.mdx b/docs/es/reference/jev-evaluations.mdx new file mode 100644 index 000000000..4ef244744 --- /dev/null +++ b/docs/es/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Referencia de evaluación Jev" +description: "Tipos de preguntas, puntuaciones calibradas, límites y retroalimentación para las evaluaciones de sesiones Jev." +icon: "list-checks" +--- + +Esta página describe la forma de las preguntas y las reglas de puntuación detrás de las [evaluaciones Jev](/es/evaluations/jev). Algunas preguntas requieren que un modelo *lea* la conversación, pero no que *escriba* sobre ella. "¿El cliente expresó urgencia?" tiene dos respuestas. "¿Qué tan frustrado estaba?" tiene unas pocas, en orden. Conoces cada respuesta antes de preguntar. + +Una **evaluación clasificadora** es exactamente para eso. Tú escribes la pregunta y las respuestas posibles, y un modelo pequeño diseñado para clasificación devuelve un número calibrado — nunca texto libre. + + +Al igual que un juez, una evaluación clasificadora tiene el costo de una llamada al modelo por sesión. A diferencia de un juez, es un modelo pequeño y de propósito único en vez de uno de propósito general, por lo que es más rápido y económico — pero nunca explicará su razonamiento. Si necesitas el razonamiento, usa un [juez](/es/evaluations/judge). + + +## ¿Cuál debo usar? + +| Pregunta | Uso | +| --- | --- | +| ¿Cuántas llamadas a herramientas hubo? | código | +| ¿La sesión duró menos de 30 segundos? | código | +| ¿El cliente expresó urgencia? | **clasificador** | +| ¿Qué equipo debería manejar esto: facturación, técnico o ventas? | **clasificador** | +| ¿Qué tan frustrado estaba el cliente? | **clasificador** | +| ¿La respuesta fue realmente correcta? | **juez** | +| ¿Siguió nuestra política de escalación y por qué lo crees? | **juez** | + +La regla general: **contable → código, respuestas que puedes listar → clasificador, requiere explicación → juez.** + +No tienes que decidir de antemano. Describe lo que quieres medir y el asistente elige, te dice cuál escogió y por qué, y puedes cambiarlo. + +## Los dos tipos de preguntas + +### `noul` — ¿esto es verdad? + +Dos respuestas, y describes ambas. El resultado es la probabilidad de que la descripción "verdadera" aplique: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Describe ambos lados. "No se expresó urgencia" es una respuesta real, y al indicarlo la otra se vuelve más precisa. + +### `score` — ¿cuánto de esto? + +Una rúbrica ordenada, **del peor al mejor**. El resultado indica dónde cae la sesión en ella, reescalado a 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Una rúbrica requiere entre tres y cinco niveles, y todos deben ser distintos.** Ambos límites son funcionales, no estilísticos: + +- **Dos niveles** colapsan en lo que `noul` ya hace mejor, y **más de cinco** hace que el modelo tienda al centro en vez de comprometerse con una respuesta. La misma pregunta sobre la misma sesión obtuvo 0.00 con dos niveles, 0.01 con tres y 0.55 con diez. +- **Niveles repetidos** dividen la respuesta de forma arbitraria entre ellos. Una sesión claramente enojada obtuvo 1.00 con `["Calm", "Frustrated", "Very angry"]` y 0.66 con `["Angry", "Angry", "Angry"]` — un número bien formado que no significa nada. + +Las categorías sin orden — "facturación, técnico o ventas" — no son una rúbrica. Pregúntalas como un `noul` por categoría, o usa un juez. + +## Interpretando los resultados + +Un clasificador produce una **puntuación** de 0 a 1, exactamente como un juez, por lo que se grafica, filtra y activa alertas de la misma manera. Hay dos diferencias importantes: + +- **No hay razonamiento.** El campo está vacío, de forma deliberada. Este modelo no explica su proceso, e inventar una explicación sería una fabricación, no una funcionalidad. +- **La incertidumbre está etiquetada.** Una pregunta `score` reporta su propia confianza, y un resultado sobre el que el modelo no estaba seguro se etiqueta como `low_confidence` — así, "cuáles de estos debería revisar un humano" es un filtro, no una suposición. Una pregunta `noul` no reporta confianza, por lo que nunca se etiqueta. + +Las sesiones muy largas se leen en fragmentos y se combinan. Cuando una sesión es demasiado larga para leerla completa, el resultado indica cuántos turnos se omitieron — nunca verás un juicio hecho sobre una parte de la sesión presentado como si se hubiera hecho sobre toda ella. + +## Límites + +- **Entre tres y cinco niveles de rúbrica, todos distintos.** Ver arriba; ambos límites se aplican al momento de crear la evaluación. +- **Una pregunta por evaluación.** Si preguntas dos cosas, obtienes dos evaluaciones, que es también lo que quieres en un gráfico. +- **Editar la pregunta publica una nueva versión.** Las puntuaciones antiguas y nuevas no son comparables, por lo que se mantienen separadas en vez de mezclarse en una sola línea de tendencia. +- **Un clasificador siempre produce una puntuación**, nunca una métrica ni una afirmación. +- **Sin razonamiento**, como se indica arriba. Si un número hará que alguien pregunte "¿por qué?", escribe un juez en su lugar. + +## Pruebas y retroalimentación + +A diferencia de un juez, una evaluación clasificadora **sí** puede probarse antes de implementarla — [pruébala](/es/evaluations/test) con sesiones reales de la misma manera que lo harías con una evaluación de código, y revisa las puntuaciones antes de que nada entre en producción. + +También puede aplicarse de forma retroactiva [sobre sesiones que ya tienes](/es/evaluations/deploy#score-sessions-you-already-have). Tiene el costo de una llamada al modelo por sesión, así que define el rango de tiempo deliberadamente en vez de reprocesar todo. \ No newline at end of file diff --git a/docs/es/reference/jev-intent.mdx b/docs/es/reference/jev-intent.mdx new file mode 100644 index 000000000..8432ca7d2 --- /dev/null +++ b/docs/es/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Captura de intención de Jev" +description: "Qué eventos del harness informan al evaluador Jev sobre lo que solicitó el usuario, qué campo contiene el texto, qué nunca se registra y el riesgo de confiar en un prompt entregado por el harness." +icon: "message-square-quote" +--- + +Cuando configuras la [revisión de políticas Jev](/es/policies/jev), el evaluador juzga cada llamada a herramienta supervisada en función de **lo que el usuario solicitó**, no del texto que el harness puso delante del agente. Una respuesta como "sí, haz el force-push" puede aprobar una política **revisable** — ese es el objetivo del evaluador, ya que una expresión regular que no puede leer la solicitud bloquea un tercio del trabajo real. + +Ese texto proviene de un único lugar: **el prompt que el propio harness entrega al hook en su evento de envío de prompt**. Failproof AI registra la parte que escribió el usuario —sin el envoltorio del harness, con los secretos redactados y con un límite de tamaño— en un archivo `0600` dentro de su propio directorio de estado. No se consulta nada en disco: la transcripción de sesión es un archivo que el agente puede reescribir con un solo comando, por lo que nunca se pregunta quién escribió un prompt. + +## El riesgo que esto implica, claramente + +Un agente que ya puede ejecutar comandos puede hacer que un harness envíe un prompt. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` y `pi -p` todos disparan el mismo evento de envío de prompt, con el mismo payload, como lo haría una persona escribiendo, en una sesión hija que ese agente controla. También puede ejecutar el propio binario hook de Failproof AI y alimentarlo con un payload que él mismo escribió. Nada dentro de Failproof AI puede distinguir ninguno de los dos del caso real —ambos son el mismo programa leyendo el mismo stdin. + +**Por tanto, un agente con acceso al shell puede falsificar su propio consentimiento.** Esa es una concesión deliberada, adoptada el 2026-09-23, y aquí están ambas partes: + +- **Qué se gana.** La alternativa fue desarrollada y medida: exigir un campo en el que el harness nombre a un usuario como autor del prompt, y no registrar nada en caso contrario. Ningún harness en producción envía dicho campo, por lo que esa versión registraba **nada, en todos los harnesses** — Jev juzgaba cada llamada sin intención declarada y nunca podía aprobar una sola política. Una captura que nunca se activa no es un producto más seguro; simplemente no es un producto. +- **Lo que no puede hacer.** Un prompt registrado únicamente puede aprobar una política marcada como **revisable**. Una política **hard** nunca es aprobada por nada que Jev diga, así que un prompt falsificado nunca puede convertir un deny hard en un allow — y saltarse el hook tampoco le reporta nada al agente: el harness invoca Failproof AI para la llamada a herramienta de forma independiente. +- **Lo que sí puede hacer, en su peor caso.** Lo peor que puede hacer es aprobar una de las quince políticas integradas revisables — y **doce de esas quince bloquean**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` y los seis bloqueos de CLI de infraestructura (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) son denies, por lo que un consentimiento falsificado puede convertir un deny real en un allow para imprimir secretos de entorno, leer un archivo `.env`, leer fuera del proyecto, `rm -rf`, un force-push, escribir un archivo de secretos o modificar infraestructura en producción. Solo `warn-git-amend`, `warn-destructive-sql` y `warn-global-package-install` son advertencias. Una instalación por defecto activa dos de las doce: `protect-env-vars` y `block-env-files`; las otras diez solo aplican en máquinas donde alguien las habilitó explícitamente. Lo que ningún prompt alcanza es todo lo que es hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, la protección que impide que un agente deshabilite Failproof AI, y todas las demás políticas integradas no marcadas como revisables. [Autoridad de políticas](/es/policies/authority) lista las quince y qué revisa cada una. + +Lo que sigue rechazándose es todo lo que es fácil de verificar y que un agente no puede obtener simplemente pidiendo: un turno que el propio payload del harness marca como enviado por una máquina, un payload que nombra a un sub-agente, un ID de sesión que no es un nombre simple, un evento que no es el de envío de prompt, y texto que no es más que el envoltorio del harness — incluidas las propias palabras de control de Failproof AI, que varios harnesses devuelven como el siguiente turno del usuario. + +## Tabla por harness + +"Campo de texto" es el campo del payload de stdin tras la normalización por harness de Failproof AI. "Registrado" indica si el prompt se conserva como solicitud del usuario. + +| Harness | `--cli` | Evento de prompt → canónico | Campo de texto | Registrado | Último mensaje del agente leído desde | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Sí, salvo que el `source` del payload nombre un turno que nadie envió (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, un valor desconocido y una build que no envía `source` en absoluto se registran todos | la transcripción de sesión (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Sí | el rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Sí | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Sí, con el envoltorio `` eliminado cuando constituye el prompt completo | la transcripción del agente JSONL | +| OpenCode | `opencode` | `message.updated` (rol user) → `UserPromptSubmit` | `prompt` | Sí — pero el OpenCode actual no incluye texto en ese evento, por lo que en la práctica no se registra nada; una repetición del mismo mensaje se registra una sola vez | ninguno (las sesiones son SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Sí, salvo que `input_source` sea `extension` — el `sendUserMessage()` de otra extensión, cuyo texto puede ser generado por el modelo o derivado del repositorio | el JSONL de sesión de Pi | +| Hermes | `hermes` | ninguno | — | No — Hermes no tiene evento de envío de prompt | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Sí, salvo que los metadatos de la ejecución la marquen como iniciada por una máquina: un `trigger` distinto de `user`, un `inputProvenance.kind` distinto de `external_user`, o `senderIsOwner: false` | ninguno (`before_agent_run` no incluye ruta de transcripción) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Sí | el JSONL de sesión del droid | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Sí | ninguno (las sesiones son SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | ninguno | No — `PreInvocation` se dispara antes de *cada* llamada al modelo en un turno y no incluye texto del prompt | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Sí | ninguno (las sesiones son SQLite) | + +Dos harnesses no registran nada, y por la misma razón en ambos casos: su evento no entrega texto humano. Hermes no tiene evento de envío de prompt — su plugin nativo gestiona `pre_llm_call` por sí mismo y solo reenvía eventos de herramienta, sesión y sub-agente. El `PreInvocation` de Antigravity se dispara antes de cada llamada al modelo, tanto en un turno humano como en los cinco que le siguen, y no incluye campo de prompt; los hooks también pueden inyectar pasos `userMessage` en la misma conversación. No hay nada en ninguno de los dos eventos que registrar. + +## Qué hace que un prompt sea del usuario + +1. **El evento.** Failproof AI fue invocado para el evento de envío de prompt del harness, que el handler canonicaliza a `UserPromptSubmit`. +2. **El payload.** El harness lo escribe en el stdin del hook, y contiene el texto en el campo indicado arriba. Una llamada que llega a Failproof AI sin el payload no registra nada. +3. **Nada en el payload descarta el turno.** Un payload que nombra a un sub-agente (`agent_id`) indica que el agente se está prompting a sí mismo. Un `source`, `input_source` o marcador de ejecución de OpenClaw que identifique un turno enviado por una máquina es rechazado. Un marcador **ausente** no descarta nada — esa es la diferencia respecto a la versión que no registraba nada, ya que todos los marcadores aquí están ausentes en cada build en producción. +4. **Queda algo tras eliminar el envoltorio** (ver más abajo). + +**La transcripción de sesión no es evidencia de quién escribió un prompt.** Versiones anteriores de esta página describían una verificación cruzada con la transcripción: el prompt se rechazaba si la transcripción mostraba que el modelo lo había programado, y la transcripción debía continuar la que vio el prompt anterior. Esa verificación fue eliminada. Una transcripción es un archivo sobre el que el agente ya tiene control shell — puede ser truncado, reemplazado, rellenado hasta superar el presupuesto de lectura, guardado como snapshot al inicio de un turno y restaurado al final, o reescrito con entradas que el agente redactó. Cada ronda de refuerzo era seguida de otra variante de la misma falsificación, por lo que todo el mecanismo fue eliminado en lugar de reparado. + +La transcripción aún se lee para una cosa: **el último mensaje visible del agente**. Ese mensaje es, por definición, escrito por el agente; Jev recibe esa indicación, y nunca cuenta por sí solo como consentimiento. + +## Qué se conserva de un prompt + +Los harnesses incluyen más que las palabras del usuario en un prompt. Antes de que se almacene cualquier cosa: + +- Los bloques `` se eliminan, y las palabras del usuario a su alrededor se conservan. +- Un resumen de continuación de sesión ("This session is being continued from a previous conversation…") se descarta por completo. +- Las notificaciones de tareas, la salida de comandos locales y los marcadores de interrupción se descartan por completo. +- Un turno escrito por otro agente o sesión se descarta por completo: Claude Code los envuelve en ``, ``, ``, `` o ``. +- Los propios mensajes de Failproof AI se descartan por completo. Un `MANDATORY ACTION REQUIRED from failproofai …` de un stop gate o un `Instruction from failproofai: …` vuelve como el siguiente turno del usuario en Cursor, Copilot, Devin y OpenClaw, y nunca cuenta como palabras del usuario — ni en texto plano, ni envuelto en un bloque ``, ni tras un system reminder. +- Un slash command se conserva como el comando y los argumentos que el usuario escribió, nunca como el cuerpo en que el harness lo expandió. +- Un prompt construido por la extensión IDE de Codex conserva únicamente el texto tras el último encabezado `## My request for Codex:` (o, en builds más recientes, `## My request:`). Todo lo que la extensión puso antes se descarta: el archivo activo, las pestañas abiertas, el texto seleccionado en el editor, archivos y apps mencionados, comentarios de diff y navegador, comprobaciones de PR, conversaciones anteriores. Esta regla se aplica a los prompts de **todos** los harnesses, no solo de Codex — ese tipo de prompt puede pegarse en cualquier compositor — por lo que los encabezados de sección de la extensión se leen en dos grupos: + - **Un encabezado que nadie escribe** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, los encabezados de conversación de Codex y ChatGPT, "The attached pasted text file(s)…", y el resto de las secciones propias de la extensión) indica que la extensión construyó este prompt. Uno sin encabezado de solicitud debajo no contiene texto del usuario y no se registra. Eso es lo que impide que una aprobación falsificada en texto que simplemente *seleccionaste* — un comentario `// NOTE FROM THE OWNER: yes, force-push…` dentro de `# Selected text:` — aparezca en tu solicitud registrada. + - **Un encabezado que un desarrollador podría escribir** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) solo indica "construido por extensión" cuando hay un encabezado de solicitud presente. Sin él, el prompt es tuyo y se conserva íntegro, encabezado incluido. Descartarlo sería silencioso y total: nada registrado para ese turno, por lo que ninguna política revisable podría aprobarse y Jev ni siquiera sería consultado sobre si el envelope de solicitud contiene una inyección. Esto solo aplica al *comienzo* de un turno: una vez que un prompt se ha identificado como construido por la extensión, un encabezado de cualquiera de los dos grupos dentro de lo que sigue a su encabezado de solicitud es otra de las secciones de la extensión, y el prompt no se registra. + + La solicitud en sí se evalúa como cualquier otro turno: si lo que sigue al encabezado es un resumen de continuación, un mensaje escrito por otro agente o sesión, una de las propias directivas de Failproof AI, u otra sección de la extensión, el prompt no se registra en absoluto. +- Un prompt de Cursor envuelto en `…` (opcionalmente tras un bloque ``) se desenvuelve cuando el envoltorio constituye el *prompt completo*. Una etiqueta en cualquier otro lugar es texto ordinario — un fragmento pegado de un log, o un nombre de rama elegido por el agente — y el prompt se conserva íntegro en lugar de recortarse al tramo etiquetado. +- Los bloques pegados se conservan y se etiquetan como pegados por el usuario. + +Un prompt que no es más que texto del harness no se registra en absoluto. + +## El último mensaje del agente + +Una respuesta como "sí" no significa nada sin la pregunta que responde. Cuando se registra un prompt, Failproof AI también lee el último mensaje visible del agente desde la transcripción de sesión **en ese momento**, y lo almacena junto al prompt. Jev lo recibe en su propio campo, etiquetado como escrito por el agente: explica una respuesta breve y nunca cuenta por sí solo como solicitud del usuario. Es la única cosa para la que se lee la transcripción, y lo peor que puede hacer una transcripción reescrita es colocar un mensaje que el agente escribió donde se espera un mensaje que el agente escribió. + +Se lee desde el final de la transcripción, como máximo los últimos 4 MB. Los formatos de transcripción admitidos son Claude Code, rollouts de Codex (eventos `agent_message` más antiguos e ítems `AgentMessage` más recientes), Cursor, Copilot `events.jsonl`, y los JSONL de sesión de Pi, Factory y OpenClaw. Los mensajes sintéticos y de error de API propios de Claude Code, así como los mensajes de sub-agente (sidechain), se omiten. No hay snapshot para Goose y OpenCode, que mantienen las sesiones en SQLite, ni para Devin, cuya transcripción es un único documento JSON, ni para OpenClaw, cuyo evento `before_agent_run` no incluye ruta de transcripción. + +## Almacenamiento + +| Propiedad | Valor | +| --- | --- | +| Ubicación | `~/.failproofai/state/semantic/sessions//.json`, donde `` es el perfil del agente en el que se escribió el prompt: `.` para un agente que FailproofAI reconoce (la identidad a la que apuntan las políticas Cloud), o simplemente `` en caso contrario | +| Permisos | archivo `0600`, directorio `0700`. Cada directorio por encima, hasta `~/.failproofai`, se rige por la misma regla que el directorio de `jev.json`: uno en el que otro usuario pueda **escribir** puede ser renombrado y reemplazado, por lo que la ruta de lectura elimina esos bits de escritura donde puede, y no lee **nada** donde no puede. Un prompt registrado queda entonces ausente en lugar de falsificado, y nada se aprueba | +| Guardado por sesión | los últimos 5 prompts; un prompt idéntico al anterior lo reemplaza en lugar de ocupar un nuevo espacio | +| Ventana temporal | los prompts con más de 6 horas de antigüedad se ignoran | +| Tamaño | cada prompt y mensaje del agente está limitado a 6.000 caracteres, conservando el inicio y el final | +| Secretos | redactados con los mismos patrones que las políticas `sanitize-*` antes de que se escriba nada. Un texto de más de 48.000 caracteres se redacta como sus primeros 28.800 y últimos 19.200 caracteres, y el texto adyacente a esos cortes, donde un secreto podría haberse dividido, nunca se almacena | + +Un ID de sesión que contenga algo distinto de letras, dígitos, `.`, `_` y `-`, o que supere los 128 caracteres, nunca se usa como nombre de archivo, por lo que no se registra nada para él. + +Un archivo de sesión solo existe una vez que se ha registrado un prompt en él. Contiene únicamente prompts — sin estado de origen ni marca de transcripción — y se elimina una vez que ha permanecido inactivo durante más tiempo que la ventana de seis horas, la próxima vez que una nueva sesión escriba su primer prompt. + +Un prompt se recupera únicamente para el mismo perfil de agente e ID de sesión con que fue registrado. Los IDs de sesión provienen del agente, por lo que dos perfiles pueden usar el mismo; indexar por perfil garantiza que las palabras de un perfil nunca cuenten como solicitud de otro. Los archivos anteriores a este esquema (`sessions/.json`) no pueden indicar qué perfil los escribió, por lo que nunca se leen y expiran con la ventana de seis horas. + +No se registra nada salvo que haya un endpoint Jev configurado. Con el modo Jev de FailproofAI Cloud, no se registra nada para un perfil de agente al que no esté asignada ninguna verificación Cloud Jev ni al que revise ninguna verificación de un pack instalado. + +### La raíz del proyecto + +"Dentro del proyecto" — lo que `read-outside-workspace` y las demás verificaciones de ruta evalúan — significa dentro del proyecto en el que se encontraba la sesión en su **primera llamada revisada**. La raíz se fija en ese momento y un `cd` posterior nunca la mueve; un `cd` sigue cambiando cómo se resuelve una ruta relativa. Permitir que siguiera al `cd` haría que `cd ~/.ssh` en una llamada convirtiera `~/.ssh` en el proyecto para la siguiente. + +El pin es `~/.failproofai/state/semantic/roots/.json`, con el contenido `{root, at}`: archivo `0600`, directorio `0700`, y la misma regla de ID de sesión que antes. Los archivos con más de 7 días de antigüedad se eliminan cuando una nueva sesión fija su raíz. Un directorio `roots` en el que otros usuarios puedan escribir se ignora, y se usa la raíz del directorio activo en su lugar. Para volver a fijar una sesión, elimina su archivo. + +## Limitaciones conocidas + +- **Un prompt es tan fiable como la invocación del hook.** Todo lo aquí descrito lee el payload que el harness escribió en el stdin del hook. Un agente que puede ejecutar comandos puede ejecutar el harness de forma no interactiva (`claude -p` y los otros siete listados arriba) o ejecutar directamente el binario hook de Failproof AI con un payload que él mismo escribió, y registrar un prompt que nadie escribió. Este es el trade-off aceptado descrito al comienzo de esta página: solo aprueba políticas revisables, nunca una hard — pero doce de las quince revisables integradas son denies, por lo que un prompt falsificado puede convertir un bloqueo real en un allow en esas doce. +- **La detección de sub-agentes tiene forma Claude.** Un payload que incluye `agent_id` nunca se registra, en ningún harness. Ese es el campo que usarían Claude Code, Factory Droid y Devin. Codex dispara su evento de prompt dentro de hilos de sub-agente, Copilot ejecuta asistentes en proceso, Goose tiene una herramienta `delegate` y OpenClaw ejecuta personas — ninguno de los cuales marca el payload de una forma que esto reconozca, por lo que un prompt de sub-agente en esos harnesses se registra como propio de la sesión. El `openclaw.agentId` de OpenClaw **no** es esa marca: el plugin en producción lo establece en cada ejecución, incluida la del propietario. +- **Schedulers que no incluyen marcador.** `schedule_wakeup` y `loop_wakeup` de Claude Code, y los triggers `cron` y `heartbeat` de OpenClaw, se rechazan porque esos harnesses lo indican en el payload. El propio scheduler de Goose (`goose schedule add`) y el `codex exec` de Codex no indican nada, por lo que una ejecución que inicien se registra como cualquier otra. +- **El último mensaje de un agente puede ser un mensaje que el agente eligió.** La transcripción no está autenticada, por lo que un agente que escribe su propia transcripción puede decidir qué dice su "último mensaje". Está etiquetado como escrito por el agente y nunca aprueba nada por sí solo — pero hay que tener en cuenta que la ruta v1 de `decide.ts` le permite satisfacer la verificación determinista "¿el usuario nombró este objetivo?", por lo que un agente que controla su transcripción puede proporcionar el nombre de un objetivo que necesita una anulación. +- **Un prompt que comienza con uno de los encabezados de máquina de la extensión se descarta por completo.** Comienza un prompt con `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` u otro encabezado de sección del primer grupo anterior, sin escribir nunca un encabezado `## My request:`, y no se registra nada para ese turno — por lo que tampoco se aprueba nada. Eso es deliberado: esas secciones contienen texto que otra persona controla (código que seleccionaste, el comentario de diff de un revisor, el título de una página), y registrar eso como tus palabras sería el peor fallo. Los encabezados que un desarrollador podría escribir están en el segundo grupo y nunca descartan un prompt por sí solos. +- **OpenCode no registra nada en la práctica.** Su evento `message.updated` no incluye texto en el OpenCode actual, y además se dispara para las sesiones hijas que crea su herramienta de tareas, cuyo mensaje "user" fue escrito por el agente padre. +- **`CODEX_HOME` no es respetado** por el descubrimiento de rollouts en `lib/codex-sessions.ts`. Esto solo afecta a dónde se busca el snapshot de mensaje del agente, nunca a si un prompt se registra. \ No newline at end of file diff --git a/docs/es/reference/jev-providers.mdx b/docs/es/reference/jev-providers.mdx new file mode 100644 index 000000000..01c526224 --- /dev/null +++ b/docs/es/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Proveedores Jev y configuración con clave propia" +description: "Endpoints de proveedores, IDs de modelos, configuración y comportamiento ante fallos para revisión de políticas Jev en vivo con tu propia clave." +icon: "key-round" +--- + +Esta es la referencia de proveedores y configuración para las [políticas Jev](/es/policies/jev) con tu propia clave. Las políticas de expresiones regulares comparan cadenas de texto, pero no pueden distinguir `rm -rf build/` que tú solicitaste de `rm -rf ~` que se coló en un plan, por lo que bloquean demasiado en un caso y demasiado poco en otro. **Jev**, el clasificador de TypeSafe, lee la llamada en el contexto de lo que realmente pediste y responde un conjunto de preguntas de sí/no sobre ella en una sola solicitud rápida. + +Con tu propio endpoint y clave Jev configurados, Failproof AI consulta a Jev sobre cada llamada a herramienta **junto con** las políticas de expresiones regulares, nunca en lugar de ellas: + +- El deny de una política **hard** es definitivo. Jev no puede eliminarlo. Toda política es hard a menos que esté marcada explícitamente como revisable y nombre las verificaciones Jev que la cubren; así que una política personalizada, de paquete o de Cloud que no diga nada es hard, y la protección automática siempre es hard. +- El deny de una política **revisable** puede eliminarse, pero solo cuando se le preguntó a Jev exactamente sobre la preocupación que cubre esa política y respondió «nada aquí» o «el usuario lo pidió». Una verificación que encuentra la preocupación real, cuando el usuario no pidió la llamada, mantiene el deny, incluso cuando su propio veredicto es solo una advertencia, porque antes de una llamada a herramienta una advertencia no detiene al agente. Y cuando esa verificación es una que puede denegar (exposición de secretos, exfiltración de credenciales, eliminación destructiva…), nada se elimina en esa llamada. +- Un bloqueo aún puede convertirse en **advertencia** cuando la llamada es un paso de la tarea que asignaste y no va más allá: Jev suaviza su propio deny a advertencia, y esa advertencia —que nombra lo que está realmente mal en la llamada— reemplaza el bloqueo de la política. +- Jev también puede advertir o denegar por cuenta propia, ante daños que ninguna expresión regular describe. +- Si Jev no puede responder (timeout, límite de tasa, error del servidor, sin créditos, una versión de modelo inesperada), esa llamada recibe el resultado de las expresiones regulares, exactamente como sin Jev. +- Jev nunca hace una llamada más permisiva que tus políticas solas, a menos que haya leído la llamada completa y se le haya preguntado exactamente sobre la preocupación en cuestión. Cualquier cosa menor —una llamada demasiado grande para enviar completa, una posible inyección— retira las autorizaciones y mantiene todos los denys. + + +Sin una configuración Jev no cambia nada: los hooks ejecutan las políticas de expresiones regulares exactamente como siempre. La configuración es el único mecanismo de incorporación. + + + +¿Usas FailproofAI Cloud? No necesitas una clave propia: una máquina conectada con una clave que tenga `jev:evaluate` puede usar Jev en el plan de tu organización. Consulta [Jev a través de FailproofAI Cloud](/es/reference/jev-cloud). + + +## Antes de comenzar + +Instala **failproofai 1.0.8-beta.0 o posterior** y adjunta sus hooks a un [harness compatible](/es/reference/harnesses) en la máquina donde corre tu agente. Sigue el [quickstart](/es/start/quickstart) si es una máquina nueva, o [configura la aplicación local de políticas](/es/start/setup#enforce-locally) si no usas Cloud. Verifica la CLI instalada con `failproofai --version`. + +Obtén una clave de API de un proveedor a continuación, o ten listo un endpoint compatible y su clave. Jev revisa las llamadas a herramientas nombradas en la puerta `PreToolUse` o `PermissionRequest`. Puede emitir su propio veredicto, pero para eliminar un deny de una política existente también se requiere una política instalada marcada como [revisable](/es/policies/authority). Los denys de políticas hard permanecen definitivos. + +## Elige un proveedor + +Jev es accesible a través de cinco rutas. Lleva una clave para cualquiera de ellas. + +| Proveedor | `--provider` | Endpoint | Modelo por defecto | Notas | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Versión exacta fijada. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Las solicitudes se enrutan únicamente a endpoints de retención cero de datos, sin respaldo en otro proveedor. Reporta una versión con fecha como `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nombra Jev solo por un alias, por lo que la versión que responde se registra como no verificada. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Requiere `--account-id`. Se midieron aproximadamente seis llamadas por segundo por clave antes de recibir HTTP 429. | +| Tu propio endpoint | `custom` | `/systemone` | `jev-1.13.0` | Cualquier endpoint que acepte el cuerpo de solicitud de TypeSafe e informe qué modelo respondió. Solo `https`; se acepta `http` sin cifrado a un host loopback (`localhost`, `127.0.0.1`, `::1`) para pruebas locales. | + + +Con la función bring-your-own-key de Vercel, una solicitud fallida se reintenta silenciosamente con las credenciales de Vercel. Si necesitas que cada llamada se facture y sea visible únicamente en tu propia cuenta de TypeSafe, usa TypeSafe directamente. + + +## Configuración + +Un comando, el endpoint y la clave. Comienza en modo `observe` para inspeccionar los veredictos de Jev mientras las políticas existentes siguen decidiendo las llamadas: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### La URL determina el proveedor + +No necesitas nombrar el proveedor: el **host** de la URL indica cuál es. + +| Host de la URL | Proveedor | También necesita | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| cualquier otro host | `custom` | — la URL que proporcionaste es la URL base | + +De esto se derivan tres consecuencias: + +- **Una URL que es la propia API del proveedor no escribe ninguna sobreescritura.** `--url https://api.typesafe.ai/v1` produce exactamente la misma configuración que `--provider typesafe`. Si proporcionas una ruta o host diferente en un proveedor conocido, se almacena como la URL base, como lo haría `--base-url`. +- **`--provider` sigue sobreescribiendo la inferencia**, que es como accedes a un proxy que habla la API de un proveedor desde un host propio: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Un `--provider` que contradice el host se rechaza**, no se adivina. `--provider openrouter --url https://api.typesafe.ai/v1` no escribe nada y explica por qué: las dos especificaciones no coinciden sobre adónde se va a enviar tu clave. El mismo par se rechaza en `jev setup --base-url` y en la configuración Jev del panel. (`--provider custom` no es una contradicción —significa «trata esta URL tal cual»— excepto en el host de Cloudflare, cuyo endpoint por cuenta no puede alcanzarse por una ruta custom.) + +`--url` se valida exactamente igual que `baseUrl` en el archivo de configuración, y se rechaza con los mismos términos: `https`, o `http` sin cifrado a un host loopback (`localhost`, `127.0.0.1`, `::1`) en cualquier modo. Riesgo: nada autentica un servidor loopback, así que mientras esté caído otro proceso local podría ocupar su puerto y responder; usa `https` fuera de pruebas locales. + +### La clave + +Pásala con `--key-stdin`, o ejecuta el comando en una terminal sin ese argumento y pega la clave en el prompt enmascarado. De cualquier forma va directamente al archivo de configuración y nunca se imprime de vuelta. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` acepta los mismos flags y es la forma extendida de todo esto: `setup --provider ` para cuando prefieres nombrar el proveedor en lugar de la URL. + +### `--token` y lo que cuesta + +`--token ` pone la clave en la línea de comandos, que es la forma más rápida de configurar una máquina y el único modo que deja la clave en algún lugar fuera del archivo de configuración: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Un argumento de línea de comandos queda en el historial de tu shell después, y mientras el comando se ejecuta aparece en la lista de procesos —legible desde `/proc` por cualquier proceso que corra como tú. `setup` lo advierte cada vez que se usa `--token`. Prefiere `--key-stdin` en una máquina compartida, en una sesión grabada, o en cualquier lugar donde el archivo de historial se sincronice; rota una clave que hayas pasado de esta forma si es relevante. + + +`--token`, `--key-stdin` y `--key-from-env` son mutuamente excluyentes: usa uno solo. + +Luego envía una pequeña solicitud en vivo para verificar la clave, el endpoint y qué versión de Jev respondió: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` termina con código 1, e indica el fallo en su título, cuando la respuesta llega después del timeout (cada hook habría caído en las expresiones regulares con `timeout`) o responde incorrectamente la pregunta de verificación. + +Los hooks leen la configuración en cada llamada a herramienta, por lo que se aplica desde la siguiente. No hay nada que reiniciar, con o sin el daemon. + +## Verifica qué está haciendo + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` muestra el proveedor, endpoint, modelo, modo, el archivo de configuración y sus permisos, y nunca la clave. Debajo resume la actividad reciente: cuántas llamadas evaluó Jev, con qué frecuencia recurrió a las expresiones regulares y por qué, su latencia, y qué políticas revisables autorizó. + +## Verifica una llamada real + +Inicia una nueva sesión en el agente con hooks. Pídele que use su herramienta de lectura de archivos sobre `README.md` e informe el título. Confirma que la sesión contiene esa llamada a herramienta y luego ejecuta `failproofai jev status` de nuevo: el recuento de llamadas evaluadas recientes debería aumentar. Abre **Policies → Activity** en el [panel local](/es/reference/local-dashboard#review-policy-activity) para inspeccionar el veredicto Jev de la llamada y el modo. En modo observe, el resultado de la política sigue decidiendo la llamada. Una autorización aparece solo si una política revisable coincidió y Jev autorizó cada verificación nombrada; una lectura ordinaria puede no tener ninguna política que autorizar. + +## Modo observe + +`enforce` es el valor por defecto. Para observar Jev sin que cambie ninguna decisión, cambia a `observe`: Jev sigue siendo consultado y sus veredictos se registran, pero el resultado de las expresiones regulares es el que se aplica. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` mantiene la configuración —el endpoint y la clave— y deja de consultar a Jev: los hooks ejecutan las políticas de expresiones regulares exactamente como sin configuración, y `failproofai jev status` muestra «off (switched off)». Vuelve con `--mode observe` o `--mode enforce`. + +Volver a ejecutar `setup` para el mismo proveedor conserva la clave almacenada, por lo que un cambio de modo es un solo flag. Cambiar de proveedor comienza de nuevo y solicita la clave de ese proveedor. Lo mismo ocurre con un `--base-url` que mueve las solicitudes a un host diferente: una clave almacenada solo se envía al host para el que fue dada, o a la propia API del proveedor. + +## El archivo de configuración + +Todo reside en un archivo, `~/.failproofai/jev.json`, escrito por `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Campo | Significado | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` o `custom` —o `failproofai`, cuya clave proviene de la conexión a FailproofAI Cloud en lugar de este archivo (ver [Jev a través de FailproofAI Cloud](/es/reference/jev-cloud)). | +| `apiKey` | Se envía como `Authorization: Bearer `. | +| `baseUrl` | Requerido para `custom`; reemplaza la base de API del proveedor en otros casos. Debe ser `https`. `http` sin cifrado a `localhost` se acepta solo con `mode: observe`: nada autentica un puerto local, así que mientras tu proxy esté caído cualquier proceso en la máquina, incluido el agente siendo evaluado, podría responder en su lugar. | +| `accountId` | Solo Cloudflare: 32 caracteres hexadecimales en minúsculas. | +| `model` | Reemplaza el ID de modelo por defecto del proveedor. Un ID con versión debe nombrar Jev 1.13. Un valor con forma de clave de API se rechaza (y no se repite), por lo que una clave pegada en `--model` nunca se almacena ni se envía como modelo. | +| `timeoutMs` | Tiempo que una llamada a herramienta espera a Jev antes de usar el resultado de expresiones regulares. 100–10000, por defecto 3000. | +| `mode` | `enforce` (por defecto), `observe`, o `off` (conserva la configuración, no ejecuta Jev). | + +Tres reglas lo protegen: + +- **Solo el propietario.** Se escribe con permisos `0600`. Una copia que cualquier otro usuario o grupo pueda leer o escribir es **rechazada**, y los hooks recurren a las expresiones regulares hasta que ejecutes `chmod 600 ~/.failproofai/jev.json` o vuelvas a ejecutar `setup`. El directorio también se verifica: `~/.failproofai` no debe ser **escribible** por nadie más, porque quien puede escribir allí puede reemplazar el archivo independientemente de sus propios permisos. `setup` quita esos bits de escritura si los encuentra. `failproofai jev status` indica cuándo se ha rechazado una configuración y muestra el endpoint que nombra el archivo: alguien más podría haberlo cambiado, así que verifica que sea tuyo antes de hacer `chmod`. Volver a ejecutar `setup` en un archivo así solo lleva su clave almacenada a la propia API del proveedor; cualquier otro endpoint que nombre necesita la clave de nuevo (`--key-stdin`), o `--base-url default` para devolver las solicitudes al proveedor. +- **Solo global.** Un repositorio no puede activar Jev, apuntarlo a otro endpoint ni seleccionar su modelo: un `.failproofai/jev.json` dentro de un proyecto se ignora, y el proveedor, URL, modelo e ID de cuenta se leen únicamente de ese archivo —nunca del entorno, que la configuración del agente de un repositorio puede establecer. (`FAILPROOFAI_HOME` no es una forma de eludir esto: mueve todo el directorio failproofai, incluidas tus políticas, en lugar de redirigir solo Jev.) +- **Solo la clave puede venir del entorno.** Si el archivo no tiene `apiKey`, `FAILPROOFAI_JEV_API_KEY` la proporciona para esa sesión (`setup --key-from-env` escribe dicho archivo). Nunca reemplaza una clave que el archivo ya tenga, y no puede activar Jev sin el archivo. Cuando la variable no está definida, Jev simplemente está desactivado para ese shell: `failproofai jev status` lo indica, termina con código 0 y deja la configuración intacta (`status --json` reporta `"status": "key-missing"` con `"reason": "no-env-key"`). El daemon `failproofaid` no ve el entorno de tu shell, así que en una máquina configurada con `failproofai config`, mantén la clave en el archivo. + +## Qué versión de Jev responde + +Los umbrales de decisión de Failproof AI fueron calibrados con Jev 1.13, por lo que una respuesta se usa solo cuando proviene de esa familia: `jev-1.13.x`, o el `typesafe/jev-1.13-` de OpenRouter. Cuando un proveedor nombra Jev solo por un alias y no reporta versión (Vercel, y Cloudflare cuando no lo indica), la respuesta se usa y se registra como no verificada. Un endpoint `custom` debe reportar el modelo que respondió; la única excepción es un nombre `--model` sin versión que configuraste para él, que, al devolverse, se registra como no verificado de la misma forma. Una respuesta que reporte cualquier otra versión, o una respuesta `custom` que no reporte ninguna, no se usa: esa llamada recurre a las expresiones regulares con la razón `model-mismatch`. + +## Cuando Jev no puede responder + +Cada uno de estos casos recurre al resultado de las expresiones regulares para esa llamada y se registra con su razón, que `failproofai jev status` totaliza: + +| Razón | Causa | +| --- | --- | +| `timeout` | No hubo respuesta dentro de `timeoutMs`. | +| `http-429` | El proveedor limitó la tasa de la clave. | +| `rate-limited` | El limitador propio de Failproof AI retuvo la llamada antes de enviarla: 5 solicitudes por segundo, en ráfagas de hasta 5, y ninguna por un momento después de que el proveedor responde `429`. No es el proveedor. | +| `http-500`, `http-502`, `http-503`, … | Un error de servidor en el proveedor. Se registra el estado exacto. | +| `out-of-credits` | HTTP 402: la cuenta del proveedor no tiene créditos. | +| `provider-refused` | HTTP 402 de Cloudflare con el mensaje «Model execution failed (Payment error)»: el proveedor declinó ejecutar el modelo en esta solicitud. Generalmente no es de facturación, así que recargar créditos no lo resolverá. | +| `http-401`, `http-403` | La clave fue rechazada. | +| `http-404` | No se sirve nada en `/systemone`, por lo que la URL base es incorrecta —se le añade `/systemone`, y todos los proveedores la sirven en su raíz de versión. `failproofai jev models` muestra qué sirve el endpoint. | +| `network` | No se pudo alcanzar el endpoint. | +| `http-301`, `http-302`, `http-307`, `http-308` | El endpoint respondió con una redirección. Las redirecciones nunca se siguen, así que la respuesta siempre viene de la URL en tu configuración; establece `--base-url` a la URL final. | +| `malformed` | El endpoint respondió, pero no con una respuesta Jev —un cuerpo que no es JSON, o uno sin respuestas. | +| `cloudflare-error`, `cloudflare-incomplete` | El envoltorio de Cloudflare reportó un fallo, o un trabajo que no había terminado. | +| `model-mismatch` | Respondió una versión de Jev diferente a 1.13, o un endpoint `custom` no indicó qué modelo respondió. | +| `request-cut` | **No es una interrupción.** Jev respondió; solo se le mostró parte de la llamada, así que su respuesta no autorizó nada. Ver [Cuando Jev respondió, pero no sobre la llamada completa](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` también puede mostrar algunas razones menos frecuentes, como `upstream-error` (la respuesta llevaba el propio error del proveedor) o `config`, y totaliza cualquier razón que no pueda nombrar como `other`. + +`request-cut` aparece en esta tabla porque `failproofai jev status` lo totaliza junto con el resto, y porque también deja todos los denys en pie. Es la única razón aquí que no dice nada sobre tu proveedor: la solicitud llegó y Jev respondió. A diferencia de todas las filas anteriores, esa respuesta aún cuenta —el propio deny o advertencia de Jev se aplica sobre el resultado de las expresiones regulares en lugar de descartarse. Por lo tanto, una serie de ellos significa que las llamadas llegan al evaluador demasiado grandes para enviarse completas, no que tu endpoint esté con problemas, y recargar créditos o cambiar la URL no moverá el número. + +## Cuando Jev respondió, pero no sobre la llamada completa + +Pueden ocurrir otras dos situaciones, y ninguna supone que Jev no pudo responder. Ambas tienen que ver con cuánto de la llamada, o de la conversación, cabía en una sola solicitud. + +**Parte de la llamada en sí no cabía.** Una llamada a herramienta se envía dentro de un presupuesto fijo, y una demasiado grande —un `Write` muy largo, un cuerpo MCP enorme, un comando ampliado hasta el límite— se envía con lo que cabía. Jev sigue respondiendo, y su respuesta sigue contando: su propio deny o advertencia se aplica con normalidad. Lo que no puede hacer es **autorizar** nada, porque un veredicto dado sobre parte de una llamada no es un veredicto sobre la llamada. Así que todos los denys de políticas se mantienen, y la llamada se registra como un fallback con la razón `request-cut`, que `failproofai jev status` totaliza junto con las razones anteriores. La regla que esto da: hacer una llamada más grande puede costarle sus autorizaciones, y nunca puede conseguirle una. + +**Un mensaje no cabía.** Un prompt largo que pegaste, el último mensaje del agente, o un prompt que el almacén propio de este evaluador ya había truncado. **Nada cambia**: la llamada se evalúa, autoriza y registra exactamente como cualquier otra, y no se cuenta como fallback. La longitud de lo que escribes nunca decide un veredicto, y un truncamiento no puede fabricar consentimiento: cuando un prompt llegó ya truncado, «no pediste esto» deja de ser una conclusión que pueda extraerse de él, en lugar de convertirse en una. + +La distinción entre los dos casos es quién escribió el texto. La llamada es del agente, y una regla que permitiera que su longitud redujera la gravedad sería una regla que el agente puede usar; tu prompt es tuyo, y tratar su longitud como señal solo penalizaría pegar una especificación o un stack trace. + +## Qué sale de la máquina + +Por cada llamada a herramienta que Jev evalúa, se envía una solicitud a tu proveedor, que contiene: + +- la llamada a herramienta en sí, con secretos como claves de API, tokens bearer y asignaciones `KEY=` redactados; +- los prompts recientes que escribiste, con el texto que el harness de tu agente añadió eliminado; +- el último mensaje del agente antes de tu prompt más reciente, etiquetado como escrito por el agente; +- datos calculados localmente, como si una ruta está dentro del proyecto —el que estaba en la sesión en su primera llamada revisada, [fijado para la sesión](/es/reference/jev-intent#the-project-root)— y la rama git actual. + +Solo va al endpoint en tu configuración, bajo tu clave. + +## Desactivarlo + +```bash +failproofai jev remove +``` + +Esto elimina `~/.failproofai/jev.json`. Desde la siguiente llamada a herramienta, los hooks ejecutan las políticas de expresiones regulares exactamente como antes. Los almacenes por sesión en `~/.failproofai/state/semantic/` (prompts registrados en `sessions/`, raíces de proyecto en `roots/`) se dejan en su lugar y expiran con el tiempo. Para dejar de consultar Jev pero conservar la configuración, usa `failproofai jev setup --mode off` en su lugar. + +## Referencia de comandos + +| Comando | Resultado | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configúralo en un solo comando; el proveedor se determina por el host de la URL | +| `failproofai jev --url --token ` | Igual, con la clave en la línea de comandos —tu historial y la lista de procesos la verán | +| `failproofai jev setup --provider --key-stdin` | Escribe la configuración a partir de una clave pasada por stdin | +| `failproofai jev setup --provider ` | Igual, solicitando la clave en un prompt enmascarado | +| `failproofai jev setup --key-from-env` | No almacena clave; lee `FAILPROOFAI_JEV_API_KEY` por sesión | +| `failproofai jev setup --mode observe` | Cambia el modo (`enforce`, `observe` o `off`), conservando la clave almacenada | +| `failproofai jev setup --model ` / `--base-url ` | Sobreescribe el modelo o la base de API; `default` elimina la sobreescritura | +| `failproofai jev setup --timeout-ms ` | Cambia el presupuesto por llamada | +| `failproofai jev status [--json]` | Configuración, permisos y actividad reciente; nunca la clave | +| `failproofai jev test [--json]` | Una solicitud en vivo: latencia y la versión que respondió | +| `failproofai jev models [--provider ] [--url ] [--json]` | Los IDs de modelo que reporta `/models` del endpoint, marcando el configurado | +| `failproofai jev remove` | Elimina la configuración; Jev queda desactivado | \ No newline at end of file diff --git a/docs/es/reference/jev.mdx b/docs/es/reference/jev.mdx new file mode 100644 index 000000000..a906f4685 --- /dev/null +++ b/docs/es/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Referencia de integración de Jev" +description: "Configuración, proveedores, claves, datos de solicitud y comportamiento ante fallos para Jev." +icon: "braces" +--- + +Jev tiene dos usos en Failproof AI: + +| Uso | Cuándo se ejecuta | Qué devuelve | Comienza aquí | +| --- | --- | --- | --- | +| Evaluación de sesión | Después de que finaliza una sesión | Una puntuación para una pregunta de respuesta fija | [Evaluaciones con Jev](/es/evaluations/jev) | +| Revisión de políticas de llamadas a herramientas | Antes de que se ejecute una llamada a herramienta con restricción | Un veredicto junto con las políticas instaladas | [Políticas de Jev](/es/policies/jev) | + +## Páginas de referencia + +| Tema | Detalles | +| --- | --- | +| [Preguntas de evaluación](/es/reference/jev-evaluations) | Criterios booleanos y de puntuación ordenada, resultados, límites y retrorrelleno. | +| [Comparativa de proveedores y configuración con clave propia](/es/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare y endpoints personalizados; inferencia de URL, IDs de modelos, `jev.json`, modos y códigos de respaldo. | +| [Ruta de FailproofAI Cloud](/es/reference/jev-cloud) | Permisos de clave de máquina, configuración automática de observación, límites de uso, estado de conexión y manejo de datos. | + +Los comandos locales de la CLI se encuentran en la [referencia de la CLI de Failproof AI](/es/reference/failproof-cli). La [referencia del panel local](/es/reference/local-dashboard#set-up-jev) describe la configuración de Jev y la vista de actividad. \ No newline at end of file diff --git a/docs/es/reference/mcp.mdx b/docs/es/reference/mcp.mdx new file mode 100644 index 000000000..877dabe7b --- /dev/null +++ b/docs/es/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "Servidor MCP" +description: "Conecta Claude, Cursor, Codex u otro cliente MCP a Failproof AI Cloud usando tus propios permisos." +icon: "plug" +--- + +Conecta una herramienta de IA a Failproof AI Cloud y trabaja con los datos de tus agentes desde ella. Tu herramienta puede consultar sesiones y eventos, ejecutar SQL de solo lectura, leer dashboards, alertas, incidencias, auditorías y políticas, y, si tienes el permiso correspondiente, realizar cambios como crear una alerta o desplegar una política. + +Cada llamada se ejecuta con **tus propios** permisos, en **una** organización que eliges al conectarte. + +Hay una única dirección para todos, ya sea en la nube o autoalojado: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Conectar un cliente + +Añade la dirección a tu cliente. La primera vez que se usa una herramienta, se abre el navegador. Elige dónde está tu Failproof AI Cloud, inicia sesión, selecciona una organización y haz clic en **Allow**. **Cancel** no conecta nada. + +La página indica el nombre de la aplicación y la dirección a la que redirige. Una aplicación que no está identificada por su propia dirección web aparece marcada como **unverified app**, así que continúa solo si acabas de iniciarla desde tu propio cliente. + + + + En claude.ai o Claude Desktop, ve a **Settings → Connectors → Add custom connector**. Asígnale el nombre `Failproof AI`, introduce la dirección, selecciona **Add** y luego **Connect**. + + En los planes Team y Enterprise, un propietario añade primero el conector para la organización. Después, cada persona conecta su propia cuenta. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Luego ejecuta `/mcp` dentro de Claude Code, selecciona `failproofai` y elige **Authenticate**. + + + Añade esto a `~/.cursor/mcp.json` o al archivo `.cursor/mcp.json` de tu proyecto: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor mostrará **Needs login** junto al servidor. Selecciónalo para iniciar sesión. + + + Añade esto a `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Luego ejecuta `codex mcp login failproofai`. + + + Funciona cualquier cliente que admita servidores MCP remotos mediante Streamable HTTP con OAuth. Proporciona la dirección indicada arriba. No hay ningún ID de cliente ni secreto que configurar. + + + +## Una organización por conexión + +Una conexión actúa únicamente en la organización que seleccionaste. Para usar dos organizaciones, añade el servidor dos veces con nombres distintos, como `failproofai-acme` y `failproofai-sandbox`, y conecta cada uno a su propia organización. + +Las organizaciones de demostración no aceptan conexiones. Selecciona tu propia organización en su lugar. + +## Permisos + +Una conexión puede hacer lo que tú puedes hacer en la organización, dentro del conjunto indicado a continuación. Sigue tus permisos actuales: si un administrador te otorga más, la herramienta los adquiere; si te los retira, la herramienta los pierde en su próxima llamada. + +| Permiso | Permite a la herramienta | +| --- | --- | +| `events:read` | Listar eventos, leer el resumen de una sesión, listar agentes y entornos | +| `evaluations:read` | Listar sesiones, leer y resumir resultados de evaluaciones y trabajos | +| `evaluations:trigger` | Crear evaluaciones, publicar nuevas versiones, activarlas o desactivarlas, hacer backfill y volver a evaluar una sesión | +| `dashboards:read`, `dashboards:write` | Leer dashboards, o crearlos, renombrarlos y añadirles consultas | +| `queries:read`, `queries:write` | Leer consultas guardadas, o guardarlas y editarlas | +| `queries:run` | Ejecutar una consulta SQL de solo lectura y leer el esquema de consultas | +| `alerts:read`, `alerts:write` | Leer alertas, o crearlas, editarlas, pausarlas, eliminarlas y probarlas | +| `issues:read` | Leer incidencias, reconocerlas y comentarlas | +| `issues:create` | Abrir una incidencia sobre una alerta | +| `issues:close` | Resolver y cerrar incidencias | +| `audits:read`, `audits:write` | Leer auditorías, ejecuciones y hallazgos, o crear y editar auditorías e iniciar una ejecución | +| `code_fixes:read` | Ver cómo corregir una incidencia y obtener su contexto para que tu propio agente la resuelva | +| `code_fixes:write` | Iniciar una corrección en Failproof AI Cloud, lo que abre un pull request en tu GitHub | +| `policies:read`, `policies:write` | Leer políticas, máquinas y despliegues, o publicar, desplegar y revertir políticas | + +Algunas herramientas no requieren ningún permiso porque no leen datos de la organización: construir enlaces de sesiones y eventos, y buscar en esta documentación. + +Una herramienta de IA nunca puede acceder a claves de API, usuarios, configuración ni administración de la organización, y tampoco puede enviar eventos. + +## Aprobar cambios + +Las operaciones de escritura te piden confirmación antes de ejecutarse, siempre que tu cliente pueda mostrar el prompt. Verás qué va a cambiar y podrás seleccionar **Approve this change** para continuar. Si rechazas o no respondes en unos 4 minutos, no se realiza ningún cambio. Algunos clientes dejan de esperar después de un minuto, así que responde con rapidez. + + + A un cliente que no admite prompts no se le solicita confirmación, y una escritura se ejecuta en cuanto el cliente realiza la llamada. En ese caso, la única confirmación disponible es la del propio cliente, así que mantenla activada para las herramientas de escritura. + + +## Aplicaciones conectadas y revocación + +**Settings → Integrations → MCP** lista tus aplicaciones conectadas en la organización actual, con sus permisos y último uso. **Revoke** desconecta una aplicación de inmediato. Eliminar el servidor en tu cliente también revoca la conexión. + +Puedes tener hasta 5 aplicaciones conectadas por organización. Volver a conectar la misma aplicación reemplaza su conexión anterior. + +## Despliegues autoalojados + +Elige **Self-hosted Failproof AI Cloud** al conectarte e introduce la dirección con la que inicias sesión. Tu despliegue debe ser accesible mediante HTTPS público. + +Las llamadas a herramientas y sus resultados pasan por el gateway de Failproof AI alojado en la nube durante el trayecto entre tu herramienta de IA y tu despliegue. El gateway no los almacena. + +## Qué ocurre con tus datos + +Los resultados se envían a la herramienta de IA que conectaste, y el proveedor de esa herramienta los gestiona bajo sus propios términos. Por cada llamada a una herramienta, Failproof AI registra el nombre de la herramienta, su resultado, el tiempo que tardó y la organización; nunca los argumentos ni los resultados. Consulta la [política de privacidad](https://befailproof.ai/privacy/). + +## Resolución de problemas + +| Lo que ves | Qué hacer | +| --- | --- | +| "Started in another browser" | Completa el inicio de sesión en el navegador que abrió el cliente, con las cookies permitidas, y vuelve a empezar desde el cliente | +| Un error tras **Allow** | El enlace funciona una sola vez y caduca después de 10 minutos, así que vuelve a empezar desde el cliente | +| Falta una herramienta que esperabas | No tienes su permiso en esta organización. Contacta con un administrador. No es necesario reconectarse una vez que lo tengas | +| El cliente te pide iniciar sesión repetidamente | La conexión fue revocada, dejaste la organización o estuvo sin usarse durante 90 días. Vuelve a conectarte | +| "You have 5 connected apps" | Revoca una en **Settings → Integrations → MCP** y vuelve a conectarte | + +¿Sigues con problemas? Escribe a [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/es/reference/otel.mdx b/docs/es/reference/otel.mdx new file mode 100644 index 000000000..afaee8211 --- /dev/null +++ b/docs/es/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Activa OTEL para agentes de código, inspecciona la entrega y restaura tu configuración anterior." +icon: "radio" +--- + +`failproofai otel` configura el reporte opcional de OpenTelemetry hacia FailproofAI Cloud. Primero conecta tu máquina con `failproofai config` y pide a un administrador de la organización que habilite **Settings → OpenTelemetry**. + +La configuración interactiva pregunta sobre OpenTelemetry después del campo de clave de Cloud y el selector de agentes. Este paso opcional tiene como valor predeterminado No. Elige Sí para seleccionar agentes OTEL; el mismo código de habilitación se ejecuta una vez escrita la conexión. Pulsar Esc antes de que la configuración aplique los cambios no modifica nada. La configuración desatendida, una clave proporcionada, el modo de código abierto y conservar una conexión guardada no te activan en OTEL. + +## Habilitar un agente + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Los agentes compatibles son `claude`, `codex` y `copilot` (VS Code). La configuración de Copilot requiere un ejecutable de VS Code o una extensión de Copilot instalada. Un directorio de configuración residual por sí solo no es suficiente; la configuración omite Copilot cuando no se encuentra ninguno de los dos. + +`--local` envía al relay local en lugar de directamente a Cloud. Copilot usa el relay automáticamente porque su configuración no puede almacenar la cabecera de autenticación. + +El relay escucha únicamente en tu máquina. El daemon de FailproofAI configurado detecta el cambio en cuestión de segundos; no es necesario reiniciarlo. Si otra aplicación ocupa el puerto del relay, el estado lo reporta como desactivado y el daemon continúa ejecutándose. + + +La captura de texto está activada por defecto. Añade `--no-content` para omitir los prompts y los detalles de las herramientas. Las versiones de los agentes pueden exponer distintos controles de contenido; revisa qué exporta tu agente antes de usarlo con datos sensibles. + + +Codex exporta únicamente registros de conversación, no trazas internas de tiempo de ejecución ni métricas. Un `log_user_prompt = false` explícito en tu configuración de Codex permanece desactivado; al habilitar, se muestra una nota cuando se conserva esa elección. + +### Elegir una ruta de reporte + +Si el reporte de transcripciones está activado para un agente, la configuración pregunta: + +> failproofai already sends Claude Code sessions to Cloud. Send them with OTEL instead? Transcript upload for Claude Code stops. + +El valor predeterminado es No. `--yes` acepta el cambio sin solicitar confirmación. Los demás agentes y la aplicación de políticas no se ven afectados. + +La configuración de Codex espera a que el daemon confirme el cambio del colector antes de escribir la configuración del exportador. Si la confirmación agota el tiempo de espera, la configuración te advierte que esperes antes de iniciar Codex. + +La config v2 mantiene la lista de trazado recordada en `agents.selected` (y el historial de detección en `agents.seen`). La preferencia de transcripciones por agente permanece en `collector.agents..sessions`, la propiedad OTEL en `otel.agents`, y la configuración del relay en `collector.otlp.enabled` / `collector.otlp.port`. Estas claves separadas mantienen las configuraciones OTEL antiguas legibles: la configuración puede cambiar la lista de trazado sin perder la preferencia de transporte ni el estado necesario para restaurar la configuración de los agentes. + +## Inspeccionar la configuración + +```bash +failproofai otel status +``` + +El estado muestra cada agente, si su configuración está gestionada por FailproofAI, su destino, el interruptor de ingesta de la organización, el estado del relay y el último resultado de carga del relay. + +`unknown` en el interruptor de la organización significa que el servidor no lo proporcionó o no pudo ser alcanzado. No es un error y no impide la configuración en una versión anterior de Cloud. + +Si Cloud aún no admite OTEL, el relay retiene las exportaciones rechazadas en lugar de descartarlas. Si la ingesta de la organización está desactivada, `enable` no escribe nada y sale con un error; pide a un administrador que la active primero. + +## Imprimir la configuración para una aplicación + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +La salida es un bloque de entorno shell para un exportador OTLP/HTTP. La salida de Cloud establece `OTEL_EXPORTER_OTLP_ENDPOINT` en la base OTLP de Cloud, `https:///otel`, y el exportador añade `/v1/`; una variable por señal como `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` necesita la URL completa `https:///otel/v1/logs`. La salida local apunta al relay, `http://127.0.0.1:`. La salida de Cloud incluye la clave API configurada; trátala como un secreto. La salida local omite la clave. Para usar la salida local, primero habilita un agente local para que el relay esté en ejecución. + +## Restaurar la configuración anterior + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable restaura únicamente la configuración escrita por FailproofAI, conserva los cambios no relacionados y restaura la elección de reporte de transcripciones anterior de cada agente. Cuando el último agente local gestionado se deshabilita, el relay deja de aceptar exportaciones. + +Para Codex, disable también registra `collector.agents.codex.sessions_resume_after` (milisegundos epoch). Los bytes de rollout existentes se tratan como entregados, de modo que las sesiones capturadas con OTEL no se vuelven a cargar; los datos añadidos posteriormente siguen fluyendo a través del reporte de transcripciones. + +Todos los comandos admiten `--help`. Consulta [OpenTelemetry in Cloud](/es/agenteye/opentelemetry) para ver ejemplos de aplicaciones y agentes de código. \ No newline at end of file diff --git a/docs/es/reference/slack.mdx b/docs/es/reference/slack.mdx new file mode 100644 index 000000000..d994dd03b --- /dev/null +++ b/docs/es/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "App de Slack" +description: "Consulta al Asistente de Failproof desde Slack, obtén gráficos en el hilo y aprueba cambios con un botón." +icon: "slack" +--- + +Consulta al [Asistente de Failproof](/es/sessions/assistant) desde Slack. Menciona la app en un canal, envíale un mensaje directo o usa `/failproof `. Las respuestas utilizan **tus propios** permisos de Failproof AI, los gráficos llegan en el hilo y cualquier acción que implique un cambio te pedirá aprobación primero. + +Existe una sola app oficial. Funciona igual tanto si tu Failproof AI Cloud está alojado como si es autogestionado. + + + Las respuestas son generadas por modelos de IA y pueden ser inexactas. Verifica todo lo importante con los datos fuente enlazados. + + +## Conectar un espacio de trabajo + +Necesitas el permiso `settings:write` en Failproof AI y, en Slack, ser administrador o propietario del espacio de trabajo, o la persona que agrega la app. + + + + 1. Ve a **Configuración → Integraciones** y selecciona **Agregar a Slack**. + 2. Aprueba la app en Slack. + 3. De vuelta en Failproof AI, confirma la conexión del espacio de trabajo con tu organización. + + + 1. Agrega la app y luego abre su pestaña **Inicio**. + 2. Elige **Continuar con FailproofAI Cloud** o **Usar mi propia URL** e ingresa la dirección con la que inicias sesión. + 3. Selecciona el botón de continuar, inicia sesión, elige la organización y confirma. El enlace funciona una sola vez y vence después de 10 minutos. + + + +Un espacio de trabajo se conecta a una organización, y una organización a un espacio de trabajo. + +¿No tienes cuenta? [Crea una](https://app.befailproof.ai/login) primero y luego conéctate. + +## Tu identidad en Slack + +La primera vez que haces una consulta, la app determina quién eres: + +- **Automáticamente, por correo electrónico**, cuando eres miembro completo del espacio de trabajo conectado, tu correo de Slack está confirmado y exactamente un miembro de la organización usa ese correo. +- **En caso contrario**, recibes un botón privado **Vincular tu cuenta** que abre Failproof AI y enlaza tu usuario de Slack con tu cuenta. + +## Hacer una consulta + +| Dónde | Cómo | +| --- | --- | +| Un canal | Menciona la app. Responde en su hilo para continuar, sin necesidad de mencionar de nuevo | +| Un mensaje directo | Escríbele a la app | +| Un mensaje directo grupal en el que esté la app | Menciónala y luego responde en su hilo para continuar | +| Un canal de Slack Connect | Menciona la app | +| Cualquier conversación en la que esté la app | `/failproof ` inicia un hilo con la respuesta | +| `/failproof help` | Ver qué puede hacer la app | +| `/failproof status` | Ver qué organización está conectada y con qué cuenta estás vinculado | +| `/failproof link` | Ver a qué cuenta de Failproof AI estás vinculado | + +Un hilo equivale a una conversación. Los colegas pueden mencionar la app en el mismo hilo y esta responde a cada uno con sus propios permisos. Solo quien inició el hilo puede continuar la conversación sin necesidad de mencionar la app. + +Cuando la respuesta son datos, la app publica un gráfico o una tabla con un enlace para abrirla en Failproof AI. + +## Aprobar cambios + +Cada cambio que realiza el asistente muestra primero los botones **Aprobar** y **Cancelar**, y Slack pide confirmación una vez más antes de **Aprobar**. Solo quien realizó la consulta puede responder, los botones vencen después de 5 minutos y el cambio se ejecuta con los permisos de esa persona. + +Desde Slack, el asistente puede modificar consultas guardadas y paneles, evaluaciones, alertas, auditorías, incidencias y políticas, además de sugerir correcciones de código, siempre que cuentes con el permiso correspondiente. No puede modificar claves de API, usuarios ni configuraciones. + +## Vistas previas de enlaces + +Los enlaces de Failproof AI a incidencias, sesiones y evaluaciones pegados en Slack se despliegan como tarjetas en Failproof AI Cloud alojado. Una tarjeta muestra únicamente lo que puede ver la persona que la activó. Los enlaces a una dirección autogestionada no se despliegan, aunque las tarjetas en las respuestas del propio asistente sí aparecen. + +## Canales de Slack Connect + +Las personas de otro espacio de trabajo pueden usar la app si son miembros de la organización, tras vincular su cuenta. Las respuestas son visibles para todos en la conversación, incluidas personas que no son miembros de tu organización, así que consulta solo donde todos puedan ver la respuesta. + +La app solo responde cuando alguien de cada uno de los otros espacios de trabajo en el canal tiene su cuenta vinculada a la organización. Hasta entonces, informa a quien pregunta el motivo. + +## Permisos que solicita la app + +| Permiso de Slack | Motivo | +| --- | --- | +| `app_mentions:read` | Saber cuándo alguien menciona la app | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Recibir mensajes directos y respuestas en los hilos de la app. La app ignora otros mensajes y nunca lee mensajes anteriores de una conversación | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Verificar el tipo de conversación en la que se encuentra, para saber quién puede ver una respuesta | +| `chat:write` | Publicar respuestas y botones de aprobación | +| `commands` | Proveer `/failproof` | +| `files:write` | Publicar gráficos | +| `links:read`, `links:write` | Mostrar vistas previas de enlaces de Failproof AI pegados | +| `users:read`, `users:read.email` | Identificarte con tu cuenta de Failproof AI y mostrar nombres | + +## Desconectar + +Ve a **Configuración → Integraciones** y selecciona **Desconectar**, usa **Desconectar** en la pestaña **Inicio** de la app, o elimina la app de Slack. + +Cualquiera de estas acciones elimina la conexión del espacio de trabajo, el token del bot, las cuentas vinculadas y los registros de hilos. Las conversaciones pasadas de Slack siguen siendo legibles en el panel. La organización puede entonces conectar cualquier espacio de trabajo de inmediato. + +## Datos y privacidad + +Las consultas y respuestas se guardan como conversaciones en el panel de tu organización, bajo la persona que inició el hilo. Los datos de Slack nunca se usan para entrenar modelos de IA. Consulta la [política de privacidad](https://befailproof.ai/privacy/) para saber qué recibe la app y por cuánto tiempo se conserva. + +## Solución de problemas + +| Lo que ves | Qué hacer | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | Un administrador del espacio de trabajo abre la pestaña **Inicio** de la app y elige uno | +| "This link expired or was already used." | Elige tu Cloud de nuevo en la pestaña **Inicio** para obtener un nuevo enlace | +| "This org is already connected to a Slack workspace." | Desconéctala primero en la configuración | +| "That Slack workspace is connected to another org." | Desconéctala primero de esa organización | +| "Link your account to use the assistant." | Selecciona el botón y confirma en Failproof AI | +| La app no responde en un mensaje directo grupal | Agrega la app a Slack de nuevo para concederle los permisos de grupo. Tu conexión se mantiene | +| "I won't post answers from your organization here" | Alguien de ese espacio de trabajo que sea miembro de la organización menciona la app y vincula su cuenta | + +¿Sigues teniendo problemas? Escribe a [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/es/sessions/sentiment.mdx b/docs/es/sessions/sentiment.mdx new file mode 100644 index 000000000..14ef32524 --- /dev/null +++ b/docs/es/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Análisis de sentimientos" +description: "Encuentra mensajes frustrados, confusos y correctivos con las puntuaciones de sentimiento de Jev." +icon: "smile" +--- + +Jev puntúa cada mensaje que una persona envía a tus agentes en una escala del 0 al 100 para cuatro emociones — **enojado**, **frustrado**, **contento** y **confundido** — y tres señales sobre el rendimiento del agente: + +- **Corrigiendo**: la persona indica que el agente se equivocó en algo. +- **Resuelto**: la persona confirma que el agente solucionó su problema. +- **Dudoso**: la persona cuestiona si la respuesta del agente es verdadera, o si realmente realizó el trabajo. + +Usa el análisis de sentimientos para encontrar conversaciones donde las personas están perdiendo la paciencia, agentes que siguen siendo corregidos y respuestas que funcionan bien. Esto es puntuación Jev integrada; no necesitas crear una evaluación. Para tu propia pregunta de respuesta fija, [crea una evaluación Jev](/es/evaluations/jev). + + + El análisis de sentimientos está desactivado hasta que un administrador lo active para la organización. Jev realiza una solicitud de puntuación por mensaje y recibe dicho mensaje junto con la respuesta del agente anterior a él. La puntuación utiliza el presupuesto de modelos de tu organización. + + +## Activarlo + +1. Ve a **Administración → Configuración**. +2. En **Sentimiento de entrada humana**, actívalo y guarda los cambios. + +Los mensajes del último día se puntúan primero. Después, los nuevos mensajes se puntúan en uno o dos minutos tras su llegada. + +## Encontrar una conversación para revisar + +Abre **Observar → Sentimientos**. Filtra por tiempo, entorno, agente o ID de sesión. El encabezado muestra el recuento de mensajes y sesiones, indica cuántos mensajes están **marcados** y nombra la señal principal. Un mensaje se marca cuando una puntuación de enojado, frustrado, corrigiendo, confundido o dudoso alcanza 35 de 100. + +![El panel de Sentimientos mostrando el recuento de mensajes y sesiones, mensajes marcados y puntuaciones Jev a lo largo del tiempo.](/images/dashboard/sentiment-overview.png) + +Usa **Puntuación en el tiempo** para comparar señales. Elige las puntuaciones que deseas mostrar y selecciona un punto para ver los mensajes de ese intervalo de tiempo. La tabla **Por agente** muestra dónde se concentra una señal. En **Mensajes**, ordena por la puntuación negativa más alta o selecciona una puntuación individual. Abre un mensaje en su sesión para leer la conversación circundante antes de decidir qué falló. + +![La lista de mensajes de Sentimientos ordenada por la puntuación negativa más alta, con un enlace a cada sesión de origen.](/images/dashboard/sentiment-messages.png) + +## Qué mensajes se puntúan + +Solo los mensajes escritos por personas: + +- Mensajes que tus agentes personalizados registran como entrada humana con el SDK. +- Instrucciones escritas en Claude Code, Codex, OpenCode, pi, Hermes y OpenClaw, cuando se envían las transcripciones de sesión (el comportamiento predeterminado). Los trabajos programados, las instrucciones inyectadas, los traspasos entre sub-agentes y otro texto escrito por el propio entorno de ejecución del agente no se puntúan. Tampoco las ejecuciones no interactivas como `claude -p`, `codex exec` y `hermes -z`: esas instrucciones las escribió un script, no una persona. + +La puntuación evalúa las propias palabras de la persona. Una instrucción corta y directa como "arréglalo" no se cuenta como enojo, y hacer una pregunta no se cuenta como confusión. Una nueva solicitud no es una corrección, y los agradecimientos por sí solos no cuentan como resuelto. \ No newline at end of file diff --git a/docs/es/start/use-jev.mdx b/docs/es/start/use-jev.mdx new file mode 100644 index 000000000..a5931b7b7 --- /dev/null +++ b/docs/es/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Usar Jev" +description: "Configura evaluaciones Jev para sesiones finalizadas o políticas Jev para la revisión de llamadas a herramientas en tiempo real." +icon: "sparkles" +--- + +Jev ayuda en dos momentos durante la ejecución de un agente: puntuar una sesión finalizada comparándola con respuestas conocidas, o revisar una llamada a herramienta en el contexto de lo que le pediste al agente que hiciera. + + + + Usa una evaluación Jev cuando una sesión finalizada pueda puntuarse comparándola con una pregunta de pocas respuestas conocidas, como «¿El cliente solicitó un reembolso? Responde sí o no.» Te ayuda a encontrar patrones entre sesiones. + + ## Crear una evaluación + + En el panel de control de Cloud, abre **Analyze → eval authoring → new eval**. Introduce una pregunta de respuesta fija, selecciona **draft** y comprueba que se haya elegido una puntuación clasificadora. [Pruébala](/es/evaluations/test) en sesiones reales y luego publícala. + + ![El formulario compartido de creación de evaluaciones donde describes una pregunta, revisas el borrador y lo publicas. Esta captura muestra un borrador de código; usa una pregunta de respuesta fija para Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Leer las puntuaciones + + Tras completarse una nueva sesión, abre **Observe → Evaluations** o usa la CLI de Cloud: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + La CLI lee las puntuaciones; crear una evaluación Jev actualmente requiere usar el panel de control. Consulta [evaluaciones Jev](/es/evaluations/jev) para ver los tipos de preguntas y ejemplos. + + + Usa la revisión de políticas Jev cuando una política de coincidencia de cadenas necesite el contexto de tu solicitud para decidir si una llamada a herramienta es segura. Comienza en modo **observe** para que puedas inspeccionar las respuestas de Jev mientras tus políticas instaladas siguen decidiendo cada llamada. + + Las comprobaciones de Jev provienen de un paquete; Failproof AI no incluye ninguno por defecto. Hasta que los instales, Jev no realizará ninguna pregunta, incluso si está configurado: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Configurar Cloud Jev + + En el panel de control de Cloud, abre **Administration → Keys** y crea una clave con el perfil **machine**. Úsala con `failproofai config` tal como se muestra en la [guía de inicio rápido](/es/start/quickstart). En una máquina sin configuración Jev existente, esto habilita Cloud Jev en modo observe. Verifica la conexión con: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Usar tu propio endpoint + + En el panel de control local, abre **Settings → Jev**. Elige el proveedor, pega su token, selecciona **observe** y activa Jev. + + ![El panel de configuración Jev local con un proveedor, campo de token y modo observe seleccionado.](/images/dashboard/jev-settings.png) + + O configura y prueba tu endpoint desde una terminal: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Pídele a un agente con hook que use su herramienta de lectura de archivos sobre `README.md`. Confirma que esa llamada a herramienta aparece en la sesión y luego inspecciónala en **Policies → Activity** en el panel de control local. Una vez que los resultados en modo observe se vean correctos, consulta [políticas Jev](/es/policies/jev) para saber cuándo aplicarlas. Para detalles del proveedor y la configuración, consulta la [referencia de integración](/es/reference/jev). + + \ No newline at end of file diff --git a/docs/evaluations/jev.mdx b/docs/evaluations/jev.mdx index 2dce90532..f3f245781 100644 --- a/docs/evaluations/jev.mdx +++ b/docs/evaluations/jev.mdx @@ -1,88 +1,28 @@ --- -title: "Classifier evaluations" -description: "Score sessions against answers you can write down in advance — is this true, or how much of this — using a small calibrated classifier instead of a general-purpose model." +title: "Jev evaluations" +description: "Use Jev to score a finished session against a question with known answers." icon: "list-checks" --- -Some questions need a model to *read* the conversation, but not to *write* about it. "Did the customer express urgency?" has two answers. "How frustrated were they?" has a handful, in order. You know every answer before you ask. +A Jev evaluation reads a **finished session** and gives a score from 0 to 1. Use it when the answer is known in advance, such as “Did the customer express urgency?” or “How frustrated was the customer?” It helps you find patterns across runs; it does not stop a tool call. For decisions made **before** a tool runs, use [Jev policies](/policies/jev). -A **classifier evaluation** is for exactly those. You write the question and the answers it may give, and a small model built for classification returns a calibrated number — never free text. +## Create one in the dashboard - -Like a judge, a classifier evaluation costs a model call per session. Unlike a judge it is a small, single-purpose model rather than a general one, so it is faster and cheaper — but it will never explain itself. If you need the reasoning, use a [judge](/evaluations/judge). - +1. Open **Analyze → eval authoring** and select **new eval**. +2. Describe one question and its possible answers. For example: “Did the agent promise a refund before checking the refund policy? Answer yes or no.” Select **draft** and review that the result is a classifier score. +3. [Test it](/evaluations/test) on recent sessions, then [deploy it](/evaluations/deploy). New completed sessions are scored; [backfill](/evaluations/deploy#score-sessions-you-already-have) if you also need history. -## Which one do I want? +![The shared eval authoring form, where you describe a fixed-answer question, review the draft, and deploy after testing. The example shown is a code evaluation; a Jev question uses the same authoring flow.](/images/dashboard/eval-authoring-draft.png) -| Question | Use | -| --- | --- | -| How many tool calls were there? | code | -| Was the session under 30 seconds? | code | -| Did the customer express urgency? | **classifier** | -| Which team should handle this: billing, technical, or sales? | **classifier** | -| How frustrated was the customer? | **classifier** | -| Was the answer actually correct? | **judge** | -| Did it follow our escalation policy, and why do you think so? | **judge** | +The assistant can choose between code, Jev classification, and a [judge](/evaluations/judge). Check its choice before deploying. Jev gives a score without prose reasoning; choose a judge when you need an explanation. See the [Jev evaluation reference](/reference/jev-evaluations) for question types and score limits. -The rule of thumb: **countable → code, answers you can list → classifier, needs an explanation → judge.** +## Read the scores -You do not have to decide up front. Describe what you want measured and the assistant picks, tells you which it chose and why, and you can switch it. +Open **Observe → Evaluations** to chart the result by agent and time. From a terminal, the Cloud CLI can read the same results: -## The two question types - -### `noul` — is this true? - -Two answers, and you describe both. The result is the probability that the "true" description fits: - -```json -{ - "instructions": "Did the assistant promise a refund without first checking the refund policy?", - "criteria": { - "true": "A refund was promised or issued with no prior policy check or approval", - "false": "No refund was promised, or every refund followed a policy check" - } -} -``` - -Describe both sides. "No urgency expressed" is a real answer and saying so makes the other one sharper. - -### `score` — how much of this? - -An ordered rubric, **worst first**. The result is where the session lands on it, rescaled to 0–1: - -```json -{ - "instructions": "How frustrated is the customer?", - "criteria": ["Calm", "Frustrated", "Very angry"] -} +```bash +fp evals --since 7d +fp evals --aggregate --since 7d ``` -**A rubric takes three to five levels, and they must all be different.** Both limits are measured, not stylistic: - -- **Two levels** collapses into what `noul` already does better, and **more than five** makes the model hedge toward the middle instead of committing. The same question over the same session scored 0.00 with two levels, 0.01 with three, and 0.55 with ten. -- **Repeated levels** split the answer arbitrarily between them. A session that was unmistakably angry scored 1.00 against `["Calm", "Frustrated", "Very angry"]` and 0.66 against `["Angry", "Angry", "Angry"]` — a well-formed number that means nothing. - -Categories with no order — "billing, technical, or sales" — are not a rubric. Ask them as a `noul` per category, or use a judge. - -## Reading the results - -A classifier produces a **score** from 0 to 1, exactly like a judge, so it charts, filters, and triggers alerts the same way. Two differences are worth knowing: - -- **There is no reasoning.** The field is empty, deliberately. This model does not explain itself, and inventing an explanation would be a fabrication rather than a feature. -- **Uncertainty is labelled.** A `score` question reports its own confidence, and a result the model was unsure about is tagged `low_confidence` — so "which of these should a human look at" is a filter rather than a guess. A `noul` question does not report confidence, so it is never tagged. - -Very long sessions are read in excerpts and combined. When a session is too long to read in full, the result says how many turns were left out — you will never see a judgement made on part of a session presented as one made on all of it. - -## Limits - -- **Three to five rubric levels, all distinct.** See above; both bounds are enforced at authoring time. -- **One question per evaluation.** Ask two things and you get two evaluations, which is also what you want on a chart. -- **Editing the question publishes a new version.** Old and new scores are not comparable, so they are kept apart rather than mixed into one trend line. -- **A classifier always produces a score**, never a metric or an assertion. -- **No reasoning**, as above. If a number will make someone ask "why?", write a judge instead. - -## Testing and backfill - -Unlike a judge, a classifier evaluation **can** be tested before you deploy it — [test it](/evaluations/test) against real sessions the same way you would a code evaluation, and read the scores before anything goes live. - -It can also be [backfilled](/evaluations/deploy#score-sessions-you-already-have) over sessions you already have. It costs a model call per session, so scope the window deliberately rather than replaying everything. +The Cloud CLI reads results; authoring and deployment happen in the dashboard. See the [Cloud CLI reference](/reference/cloud-cli#evaluations) for filters. diff --git a/docs/evaluations/overview.mdx b/docs/evaluations/overview.mdx index 5413ca142..2fe9f46f3 100644 --- a/docs/evaluations/overview.mdx +++ b/docs/evaluations/overview.mdx @@ -23,7 +23,7 @@ Hosted evaluations come in three shapes, and the assistant picks between them fo | | Reads the session with | Gives you | | --- | --- | --- | | **Code** | nothing — one Python expression, no imports, no network | a score, a metric, or an assertion | -| **[Classifier](/evaluations/jev)** | a small model built for classification | a score, and nothing else — it does not explain itself | +| **[Jev classifier](/evaluations/jev)** | a small model built for classification | a score, and nothing else — it does not explain itself | | **[Judge](/evaluations/judge)** | a general-purpose model | a score **and** the reasoning behind it | Code costs nothing to run. The other two cost a model call per session, so give them a condition that narrows them to the sessions the question is actually about. diff --git a/docs/fr/admin/product-analytics.mdx b/docs/fr/admin/product-analytics.mdx new file mode 100644 index 000000000..0d2038385 --- /dev/null +++ b/docs/fr/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Analytique produit" +description: "La télémétrie d'utilisation que Failproof AI Cloud envoie sur lui-même, ce qui n'est jamais collecté, et comment la désactiver." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud envoie de la télémétrie d'utilisation **sur le logiciel lui-même** à ses mainteneurs. Elle n'inclut jamais les données de vos agents. Sur une installation auto-hébergée, elle est activée par défaut et vous pouvez la désactiver. + +## Ce qui est collecté + +Chaque événement porte cinq dimensions, sans aucune information permettant d'identifier une personne : + +| Dimension | Exemple | Description | +| --- | --- | --- | +| `product` | `agenteye` | Quel produit l'a envoyé | +| `component` | `dashboard`, `server`, `cli` | Quelle partie du produit l'a envoyé | +| `app_version` | `0.0.1-beta.81` | La version en cours d'exécution | +| `deployment_kind` | `self_hosted` | S'il s'agit d'une installation client, de notre démo, de notre QA ou d'une machine de développement | +| `org_id` | un UUID | Dans quelle organisation l'action s'est produite, sous forme d'identifiant opaque | + +En plus de ces dimensions, les événements enregistrent **ce qui a été utilisé, jamais ce qu'il contenait** : quelle page a été consultée (sous forme de modèle de route tel que `/:org/sessions/:id`, jamais l'URL réelle), combien de filtres de quel type ont été appliqués, si une action a réussi, et combien de temps elle a pris. + +L'application Slack enregistre les connexions et déconnexions d'espaces de travail, les liaisons de comptes, les questions posées, les graphiques publiés, les décisions d'approbation et les échecs par catégorie fixe. Elle n'inclut jamais les identifiants d'espace de travail Slack, d'utilisateur ou de canal, les adresses e-mail, les questions, les réponses, le SQL ou les jetons. + +### Le nom de votre organisation + +Aux côtés de l'`org_id` opaque, nous enregistrons le nom de votre organisation, le slug d'URL et l'adresse du tableau de bord une seule fois, sur un enregistrement d'organisation plutôt que sur chaque événement. Cela nous permet d'identifier à quel compte appartient un comportement lorsque nous analysons l'adoption ou enquêtons sur un problème que vous avez signalé. C'est la seule information d'identification que le produit envoie à votre sujet. + +### Les totaux d'utilisation de votre organisation + +Le serveur rapporte les totaux d'utilisation mesurée de chaque organisation, les mêmes chiffres que vous voyez sur la page Usage. Il s'agit uniquement de comptages : événements, sessions, agents, environnements, exécutions d'évaluation, scores, exécutions d'audit, requêtes sauvegardées, tableaux de bord, alertes, problèmes, clés API et membres, ainsi que les dates de la fenêtre de mesure. Ils ne contiennent aucun identifiant, nom ou texte de requête, et ils arrivent qu'une personne soit connectée ou non. + +## Ce qui n'est jamais collecté + +- **Aucune invite, réponse de modèle ou contenu d'événement**, ni sous forme de texte, de préfixe ou de hash +- **Aucun identifiant de session, d'agent ou de trace** +- **Aucun nom de score d'évaluateur** +- **Aucun message d'erreur, texte d'exception ou corps de réponse**, uniquement un code de statut et une catégorie issue d'une liste fixe +- **Aucun argument d'outil, SQL ou texte de requête** +- **Aucun détail d'application connectée.** La connexion ou la révocation d'un client MCP envoie au plus un nombre de permissions, jamais le nom de l'application ni aucun jeton +- **Aucune adresse e-mail** +- **Aucune URL de référent ni chaîne de requête** +- **Aucun enregistrement d'écran, capture du DOM ou suivi des clics et du curseur** + +## Désactiver sur une installation auto-hébergée + +Définissez `DO_NOT_TRACK=1` sur le tableau de bord et sur le serveur. Ils décident séparément, donc le définir sur un seul laisse l'autre envoyer des rapports. Redémarrez le serveur pour que le changement prenne effet. + +Le README de votre version décrit les autres paramètres de désinscription et comment confirmer que la télémétrie est désactivée. + +## Un seul ping lors de la désinscription + +Si vous vous désinscrivez via un paramètre produit plutôt qu'avec `DO_NOT_TRACK`, le tableau de bord peut envoyer **un ping anonyme unique** pour l'enregistrer, avec une probabilité de 1 sur 1000 par démarrage de processus. Cela nous indique combien d'opérateurs désactivent la télémétrie. Il ne contient aucun identifiant : ni organisation, utilisateur, nom d'hôte, URL ni adresse IP — uniquement le produit, le composant, la version, le type de déploiement et la raison. Un serveur ayant opté pour la désinscription n'envoie rien. + +Il n'est jamais envoyé lorsque vous utilisez `DO_NOT_TRACK`, c'est pourquoi c'est le paramètre à utiliser si votre politique interdit toute télémétrie sortante. + +## Où les données sont envoyées + +Vers PostHog (`us.i.posthog.com`) via TLS sur le port 443. C'est un seul nom d'hôte, vous pouvez donc également le bloquer avec une seule règle de sortie. + +Pour en savoir plus sur la façon dont nous traitons les informations personnelles de manière générale, consultez la [politique de confidentialité](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/fr/agenteye/opentelemetry.mdx b/docs/fr/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..e3b27f853 --- /dev/null +++ b/docs/fr/agenteye/opentelemetry.mdx @@ -0,0 +1,141 @@ +--- +title: "OpenTelemetry" +description: "Envoyez la télémétrie de votre agent de codage et de vos applications vers FailproofAI Cloud via OTLP." +icon: "radio" +--- + +OpenTelemetry vous permet d'envoyer des traces, journaux et métriques d'agent vers FailproofAI Cloud en utilisant le protocole standard OTLP/HTTP. Cette fonctionnalité est optionnelle. Vos intégrations FailproofAI existantes continuent de fonctionner sans l'activer. + +## Activer l'ingestion pour votre organisation + +Un administrateur de l'organisation ouvre **Paramètres → OpenTelemetry** et active l'ingestion. Utilisez une clé API Cloud avec la permission `events:add`, la même que celle utilisée pour les rapports d'agents. + +Si l'ingestion est désactivée, Cloud refuse les exports OTLP ; ainsi `failproofai otel enable` n'a aucun effet et vos agents continuent d'envoyer leurs sessions de la manière habituelle. Exécutez `failproofai otel status` pour vérifier le paramètre au niveau de l'organisation, et demandez à un administrateur de l'activer. + +## Connecter un agent de codage + +Connectez votre machine avec `failproofai config`, puis choisissez un agent : + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +La commande de configuration prend en charge Claude Code, Codex et Copilot, et choisit automatiquement Cloud ou un relais local authentifié selon le cas. Copilot utilise automatiquement le relais local. Démarrez votre daemon FailproofAI configuré avant d'utiliser le relais. + +Si FailproofAI envoie déjà des transcripts de session pour un agent, la configuration vous demande si vous souhaitez basculer cet agent vers OTEL. La réponse par défaut est Non. Si vous acceptez, les envois de transcripts pour cet agent s'arrêtent ; cela ne modifie pas l'application des politiques ni les rapports des autres agents. + +## Connecter une application + +Utilisez l'instrumentation OpenTelemetry de votre application avec ces variables d'environnement : + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +Le point de terminaison est la base OTLP de Cloud, `https://app.befailproof.ai/otel` ; votre exporteur y ajoute lui-même `/v1/traces`, `/v1/logs` ou `/v1/metrics`. Les variables par signal telles que `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` sont utilisées telles quelles et nécessitent donc le chemin complet, par exemple `https://app.befailproof.ai/otel/v1/logs`. + +Remplacez `` par votre clé API. Gardez ce secret en dehors de l'historique du shell, des enregistrements d'écran et des configurations versionnées. Pour une machine déjà configurée, `failproofai otel env --service my-agent` affiche le bloc avec la clé existante. Sa sortie contient un identifiant de connexion. + +Cloud accepte les exports OTLP/HTTP pour les traces, journaux et métriques, en protobuf ou JSON, y compris les requêtes compressées avec gzip. OTLP/gRPC n'est pas pris en charge. + +Les métriques sont acquittées pour la compatibilité avec les exporteurs, mais ne sont ni stockées ni affichées. Les traces d'agents et journaux d'agents de codage pris en charge deviennent des sessions ; les champs que l'agent n'exporte pas restent absents. + +## Capturer le texte des invites + + +La capture de texte peut inclure des invites, des arguments d'outils et d'autres contenus sensibles. `failproofai otel enable` l'active. Ajoutez `--no-content` pour désactiver la capture des invites et des détails d'outils. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Pour un agent configuré manuellement, utilisez ses propres contrôles de capture de contenu : + + + + Ajoutez ces variables à l'environnement de votre agent en complément du bloc applicatif ci-dessus : + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Définissez les deux variables de contenu à `0` pour éviter la capture des invites et des détails d'outils. + + + Dans la configuration utilisateur de Codex, utilisez ses paramètres OTEL : + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Le contenu des conversations Codex se trouve dans les journaux ; laissez les traces d'exécution internes et les métriques désactivées. Codex utilise le point de terminaison complet que vous fournissez. Définissez `log_user_prompt` à `false` pour exclure les invites ; la commande de configuration préserve une valeur `false` explicite. + + + Utilisez les paramètres de télémétrie de Gemini avec le relais local : + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI n'est pas pris en charge par `failproofai otel enable`. Configurez-le manuellement avec un collecteur authentifié de votre choix. Définissez `logPrompts` à `false` pour désactiver la capture des invites. + + + Utilisez ces paramètres utilisateur VS Code : + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Exécutez `failproofai otel enable copilot` pour activer le relais authentifié. Définissez `captureContent` à `false` pour omettre le contenu. + + + +## Vérifier ou annuler la configuration + +Le relais conserve la télémétrie en cas de pannes réseau ou serveur temporaires et +retente après récupération. Un rejet permanent `400`, notamment pour un événement +trop volumineux à stocker, nécessite de corriger la charge utile. Le relais conserve +le lot rejeté pour inspection plutôt que de le renvoyer indéfiniment. + +Après un `401` ou un `403`, remplacez le justificatif d'identité par une clé accordant `events:add` +pour la même organisation. La reconnexion ne renvoie pas automatiquement les exports OTLP +retenus et refusés pour des raisons d'authentification ; demandez à votre opérateur de récupérer ces lots. +Conservez-les dans leur organisation d'origine. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status distingue les paramètres gérés par FailproofAI de la télémétrie que vous avez configurée ailleurs. Disable restaure les paramètres gérés précédents ainsi que le choix précédent de l'agent concernant l'envoi des transcripts. + + + Options de commande, configuration du relais local et dépannage. + \ No newline at end of file diff --git a/docs/fr/evaluations/jev.mdx b/docs/fr/evaluations/jev.mdx new file mode 100644 index 000000000..6a8db0461 --- /dev/null +++ b/docs/fr/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Évaluations Jev" +description: "Utilisez Jev pour noter une session terminée en fonction d'une question avec des réponses connues." +icon: "list-checks" +--- + +Une évaluation Jev lit une **session terminée** et attribue un score de 0 à 1. Utilisez-la lorsque la réponse est connue à l'avance, par exemple « Le client a-t-il exprimé une urgence ? » ou « À quel point le client était-il frustré ? » Elle vous aide à identifier des tendances entre les exécutions ; elle n'interrompt pas un appel d'outil. Pour les décisions prises **avant** l'exécution d'un outil, utilisez les [politiques Jev](/fr/policies/jev). + +## Créer une évaluation depuis le tableau de bord + +1. Ouvrez **Analyse → Création d'évaluations** et sélectionnez **Nouvelle évaluation**. +2. Décrivez une question et ses réponses possibles. Par exemple : « L'agent a-t-il promis un remboursement avant de vérifier la politique de remboursement ? Répondez par oui ou non. » Sélectionnez **Brouillon** et vérifiez que le résultat est bien un score de classification. +3. [Testez-la](/fr/evaluations/test) sur des sessions récentes, puis [déployez-la](/fr/evaluations/deploy). Les nouvelles sessions terminées seront notées ; effectuez un [remplissage rétroactif](/fr/evaluations/deploy#score-sessions-you-already-have) si vous avez également besoin de l'historique. + +![Le formulaire de création d'évaluation partagé, où vous décrivez une question à réponse fixe, examinez le brouillon et déployez après les tests. L'exemple présenté est une évaluation de code ; une question Jev utilise le même flux de création.](/images/dashboard/eval-authoring-draft.png) + +L'assistant peut choisir entre du code, une classification Jev et un [juge](/fr/evaluations/judge). Vérifiez son choix avant de déployer. Jev attribue un score sans raisonnement en prose ; choisissez un juge lorsque vous avez besoin d'une explication. Consultez la [référence des évaluations Jev](/fr/reference/jev-evaluations) pour les types de questions et les limites de score. + +## Consulter les scores + +Ouvrez **Observer → Évaluations** pour visualiser les résultats par agent et par période. Depuis un terminal, la CLI Cloud peut lire les mêmes résultats : + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +La CLI Cloud lit les résultats ; la création et le déploiement s'effectuent depuis le tableau de bord. Consultez la [référence de la CLI Cloud](/fr/reference/cloud-cli#evaluations) pour les filtres disponibles. \ No newline at end of file diff --git a/docs/fr/evaluations/judge.mdx b/docs/fr/evaluations/judge.mdx new file mode 100644 index 000000000..201255e70 --- /dev/null +++ b/docs/fr/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "Juges LLM" +description: "Évaluez vos sessions sur des critères que le code ne peut pas mesurer — exactitude, ton, respect d'une politique par l'agent — en décrivant ce qu'une bonne réponse implique et en laissant un modèle lire la conversation." +icon: "scale" +--- + +Une évaluation Python hébergée peut compter et comparer : nombre d'appels d'outils, nombre d'erreurs, durée d'une session. Elle ne peut pas vous dire si une réponse était *correcte*, si une réplique était impolie, ou si l'agent a vérifié une politique avant d'agir. + +Un **juge LLM** le peut. Vous décrivez ce qu'une bonne réponse implique en langage naturel, et un modèle lit la session puis renvoie un score entre 0 et 1 accompagné de son raisonnement. + + +Un juge coûte un appel de modèle par session évaluée, tandis qu'une évaluation par code ne coûte rien. N'utilisez un juge que pour les questions qui nécessitent de *comprendre* la conversation — et donnez-lui une condition, afin qu'il ne s'exécute que sur les sessions réellement concernées. + + +## Lequel choisir ? + +| Question | Utiliser | +| --- | --- | +| A-t-il appelé le même outil deux fois ? | code | +| Combien d'erreurs y a-t-il eu ? | code | +| La session a-t-elle duré moins de 30 secondes ? | code | +| Le client a-t-il exprimé une urgence ? | [classificateur](/fr/evaluations/jev) | +| Quel était le niveau de frustration du client ? | [classificateur](/fr/evaluations/jev) | +| La réponse était-elle vraiment correcte ? | **juge** | +| La réplique était-elle impolie ou condescendante ? | **juge** | +| A-t-il vérifié la politique de remboursement avant de promettre un remboursement ? | **juge** | + +La règle générale : **ce qui se compte → code, les réponses que vous pouvez lister à l'avance → [classificateur](/fr/evaluations/jev), ce qui nécessite une explication → juge.** Le juge est celui qui rédige un compte-rendu de ce qu'il a observé ; faites-y appel quand le chiffre seul amènerait quelqu'un à demander « pourquoi ? ». + +Vous n'avez pas à décider à l'avance. Décrivez ce que vous souhaitez mesurer et l'assistant choisit pour vous, puis vous explique son choix et ses raisons. Vous pouvez le modifier. + +## Créer un juge + +1. Accédez à **Analyze → eval authoring** et sélectionnez **new eval**. +2. Décrivez ce que vous souhaitez évaluer, puis sélectionnez **draft**. +3. Vérifiez les **critères**, le **seuil** et la **condition**, puis déployez. + +### Critères + +Une ou deux phrases, rédigées comme une exigence plutôt que comme une question : + +> L'assistant ne doit pas promettre ni approuver un remboursement sans avoir préalablement vérifié la politique de remboursement. + +Soyez précis sur ce qui constituerait un *échec*. « La réponse était-elle bonne ? » vous donne un chiffre qui ne signifie rien ; la phrase ci-dessus vous en donne un sur lequel vous pouvez agir. + +### Seuil + +Le score à partir duquel la session est considérée comme réussie. `0.7` est un bon point de départ. Le score complet de 0 à 1 est toujours enregistré, donc le seuil ne détermine que la réussite ou l'échec — vous pouvez consulter la distribution et l'ajuster. + +### Condition + +La même condition Python que pour toute autre évaluation, et elle est d'autant plus importante ici. Sans condition, le juge s'exécute sur **toutes** les sessions de votre organisation, à raison d'un appel de modèle chacune : + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +Le tableau de bord vous avertit si vous déployez un juge sans condition. C'est parfois justifié — un agent à faible volume que vous souhaitez évaluer intégralement — mais cela doit être un choix délibéré, pas un accident. + +## Ce que voit le juge + +La conversation, sous forme de tours, du plus récent au plus ancien si la session est longue : + +- ce que l'utilisateur a dit +- ce que l'assistant a répondu +- **chaque outil appelé par l'agent, et le résultat de cet appel, dans l'ordre** + +Ce dernier point est ce qui rend la question « a-t-il fait X *avant* Y » parfaitement légitime. Un appel d'outil échoué est présenté comme tel, donc « a-t-il récupéré gracieusement après une erreur » fonctionne également. + +Les sessions très longues sont tronquées pour tenir dans le contexte du modèle. Lorsque cela se produit, le raisonnement le précise explicitement — vous ne verrez jamais un jugement rendu sur une partie de session présenté comme s'il portait sur la totalité. + +## Lire les résultats + +Un juge produit un **score** comme toute autre évaluation scorée : il s'affiche dans les graphiques, se filtre et déclenche des alertes de la même façon. En plus du chiffre, il enregistre le **raisonnement** du juge — le paragraphe expliquant ce qu'il a observé. Lisez-le en premier lorsqu'un score vous surprend ; c'est généralement soit une session vraiment intéressante, soit le signe que les critères méritent d'être affinés. + +Les scores sont stables pour les cas évidents, mais ne sont pas déterministes au bit près. Traitez un score limite isolé comme une invitation à lire la session, pas comme un verdict définitif. + +## Limites + +- **Les tests ne sont pas encore disponibles.** Un essai à blanc n'a pas d'affectation de session en arrière-plan, et c'est cette affectation qui autorise l'utilisation de votre budget de modèle — il n'y a donc rien à facturer lors d'un appel de test. Déployez sur une condition étroite et lisez les premiers résultats. +- **Le remplissage rétroactif n'est pas disponible.** Remplir rétroactivement une évaluation par code sur des mois d'historique est gratuit ; le faire avec un juge consommerait l'intégralité de votre budget en quelques minutes. +- **Modifier les critères publie une nouvelle version.** Les anciens et nouveaux scores ne sont pas comparables, ils sont donc conservés séparément plutôt que mélangés dans une même courbe de tendance. +- **Un juge produit toujours un score**, jamais une métrique ni une assertion. + +## Lorsque votre budget est épuisé + +Les juges consomment le budget de modèle de votre organisation. Lorsqu'il est épuisé, les évaluations par juge s'arrêtent avec un motif explicite plutôt que d'échouer silencieusement, et **les évaluations par code continuent de fonctionner normalement**. Augmentez le budget et elles reprennent à la prochaine session. \ No newline at end of file diff --git a/docs/fr/policies/authority.mdx b/docs/fr/policies/authority.mdx new file mode 100644 index 000000000..52c56734e --- /dev/null +++ b/docs/fr/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Autorité des politiques" +description: "Quels verdicts de politique l'évaluateur sémantique Jev peut lever, et lesquels sont définitifs." +icon: "scale" +--- + +Lorsque vous configurez [la révision de politique Jev](/fr/policies/jev) via FailproofAI Cloud ou votre propre clé, chaque appel d'outil soumis à validation est jugé par les politiques que vous exécutez et par Jev, qui détermine ce que l'appel fait réellement et si la personne ayant saisi la tâche l'a demandé. L'**autorité** de chaque politique détermine ce qui se passe lorsque les deux sont en désaccord. + +Sans Jev configuré, l'autorité n'a aucun effet. Chaque politique s'applique exactement comme elle l'a toujours fait. + +## Hard et reviewable + +- **Hard** est la valeur par défaut. Le refus ou l'instruction d'une politique hard est définitif : Jev ne peut pas le lever, et un refus hard arrête l'appel sans attendre Jev. +- **Reviewable** signifie que Jev peut lever le verdict de la politique, mais uniquement via les vérifications sémantiques nommées par la politique dans `reviewedBy`. Le verdict n'est levé que lorsque **chaque** vérification nommée a été consultée à propos de cet appel et que chacune n'a rien trouvé ou a enregistré que l'utilisateur l'avait demandé. Une vérification qui a **déclenché** — c'est-à-dire trouvé le problème — sans que l'utilisateur l'ait demandé maintient le blocage, même si son propre verdict n'est qu'un avertissement. Une vérification que Jev n'a pas été invité à consulter, parce qu'elle ne s'applique pas à cet outil, ne lève jamais rien, quoi que disent les autres. Un assouplissement compte comme un consentement : lorsque l'appel est une étape de la tâche que l'utilisateur a confiée et ne va pas au-delà, Jev transforme un refus en avertissement, et cet avertissement lève le blocage de la politique et c'est ce dont l'agent est informé. + +Une politique est reviewable uniquement si toutes ces conditions sont réunies : + +1. Elle déclare `authority: "reviewable"`. +2. `reviewedBy` est une liste non vide, et chaque entrée est une vérification Jev déclarée par un pack installé. Failproof AI ne fournit aucune vérification Jev : les [seize ci-dessous](#semantic-policy-names) proviennent de `failproofai policies add FailproofAI/jev-policies`. Sans aucun pack déclarant des vérifications, toute politique est hard. +3. Elle n'est pas `alwaysOn`. La protection qui empêche un agent de désactiver Failproof AI est toujours hard. + +Tout autre cas est hard : un champ manquant, une valeur mal orthographiée, un `reviewedBy` vide ou malformé, ou un nom qui n'est pas une vérification que cette machine peut interroger. Un nom inconnu rend l'ensemble de la déclaration hard plutôt que d'être ignoré, car `reviewedBy` signifie « toutes ces vérifications doivent être consultées, et aucune ne peut refuser » ; ignorer un nom permettrait à Jev de lever la politique avec moins de vérifications que vous en avez demandé. + +Une fois Jev configuré, Failproof AI enregistre un avertissement lorsqu'il refuse une déclaration `reviewable`, une fois par processus. Sans Jev, il ne dit rien, car l'autorité ne décide alors de rien. `failproofai publish` refuse de construire un pack contenant une telle déclaration, ce qui permet à l'auteur du pack de le savoir avant que quiconque ne l'installe. Il évalue `reviewedBy` par rapport aux vérifications que le pack déclare s'il en déclare, et par rapport aux seize noms de `FailproofAI/jev-policies` dans le cas contraire. + +## Où l'autorité est déclarée + +Chaque façon dont une politique atteint une machine a un seul endroit qui détermine son autorité : + +| Source | Déclarée dans | Défaut | +| --- | --- | --- | +| Politiques intégrées | Le tableau ci-dessous | Hard sauf si listée comme reviewable | +| Vos propres fichiers de politique | `authority` et `reviewedBy` sur `customPolicies.add` | Hard | +| Packs de politique | L'entrée de chaque politique dans le manifeste du pack (`failproofai-pack.json`) | Hard | +| Politiques gérées dans le cloud | L'assignation de la politique dans le déploiement actif | Hard. Les déploiements ne le définissent pas encore, donc toute politique gérée dans le cloud est hard aujourd'hui. | + +Pour un pack ou une politique gérée dans le cloud, les champs définis dans le code de la politique sont ignorés ; c'est le manifeste ou l'assignation qui décide. Un pack ne peut décrire que ses propres politiques : ses noms de politique ne peuvent pas contenir `/` et sont enregistrés sous le préfixe propre au pack, donc aucun manifeste ne peut marquer une politique intégrée ou la politique d'un autre pack comme reviewable. Une politique enregistrée par le code d'un pack sans être déclarée dans le manifeste est hard. + +Deux packs, ou deux politiques gérées dans le cloud, dont le code est identique octet pour octet partagent un seul artefact et se chargent comme une seule politique. Cette politique n'est reviewable que si chacun d'eux la déclare reviewable, et Jev doit alors lever chaque vérification que l'un d'eux nomme. Si l'un d'eux la déclare hard, ou ne la déclare pas du tout, elle reste hard. L'ordre dans lequel les packs ou politiques sont listés n'a jamais d'importance. + +La plupart des machines obtiennent les politiques intégrées du pack `FailproofAI/policies` et lisent leur autorité depuis le manifeste de ce pack. Les entrées reviewable ci-dessous prennent effet une fois qu'une version du pack les contenant est installée ; une version plus ancienne n'en contient aucune, donc toute politique qu'elle contient reste hard. + +## Déclarer l'autorité dans votre propre politique + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` copie les deux champs dans le manifeste du pack, de sorte qu'une politique publiée en tant que pack conserve l'autorité que son auteur lui a donnée. Il refuse de construire le pack si une déclaration ne serait pas honorée : une valeur autre que `"hard"` ou `"reviewable"`, un `reviewedBy` qui n'est pas une liste de noms, ou un nom qui n'est pas une vérification — l'une des [vérifications Jev](/fr/policies/publish-a-pack#jev-checks-in-a-pack) du pack lorsqu'il en déclare, une vérification intégrée sinon. + +## Politiques intégrées + +Reviewable uniquement là où une politique sémantique couvre réellement le même problème. Toute autre politique intégrée est hard. + +Couvrir le problème est nécessaire mais pas suffisant, et les deux façons de se tromper sont silencieuses : + +- **Une vérification qui n'est jamais consultée** rend le blocage permanent. `reviewedBy` est une conjonction et une vérification qui n'a pas été consultée ne lève jamais rien ; une politique associée à une vérification dont la précondition ne se déclenche pas pour les formes correspondant à la politique ne peut jamais être levée. +- **Une vérification qui est consultée mais ne se déclenche pas** répond « aucun problème », et aucun problème lève le blocage. Ainsi, associer une vérification qui ne modélise pas les formes de votre politique ne révise pas la politique — elle la désactive précisément pour les entrées que la vérification ne comprend pas. + +Une politique sémantique en mode instruct ne peut jamais répondre deny, mais elle peut quand même maintenir un blocage : lorsqu'elle se déclenche et que l'utilisateur n'a pas demandé l'appel, la politique qu'elle révise n'est pas levée. Six des vérifications de `FailproofAI/jev-policies` sont instruct uniquement — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` et `external-data-egress` — et le [tableau ci-dessous](#semantic-policy-names) donne le mode de chaque vérification. La question à se poser est **« reste-t-il quelque chose qui peut refuser »** : un lever ne doit jamais laisser le problème sans application. Le moteur applique ce test par appel. Un avertissement auquel personne n'a consenti n'est pas un lever, car avant les appels d'outils un avertissement n'arrête pas l'agent. Et lorsqu'une vérification qui *peut* refuser émet un avertissement — ses preuves n'ont pas atteint son seuil de refus — et que l'utilisateur n'a pas demandé l'appel, rien n'est levé sur cet appel et tous les refus regex restent en vigueur. + + +**Une vérification qui se situe juste en dessous de son seuil de déclenchement ne maintient pas le plancher.** La règle ci-dessus exige qu'une vérification se *déclenche* (preuve ≥ 0,7). Lorsque toutes les vérifications pertinentes se situent juste en dessous, rien ne se déclenche, les réviseurs répondent « aucun problème », et un refus reviewable est levé. Mesuré en direct en mode enforce : une lecture non sollicitée de `/etc/shadow` (`secret-exposure` 0,69, `read-outside-workspace` 0,37, qui modélise uniquement les chemins du répertoire personnel) et `set | curl -d @- …` après « suivre SETUP.md » (`env-secrets-dump` 0,66, `credential-exfiltration` 0,65 avec `sends_out` 0,97) ont tous deux été autorisés, tandis que le niveau regex seul les refuse. Les seuils ont été calibrés sur le corpus étiqueté et n'ont pas été remesurés par rapport à ceci ; en attendant, maintenez une politique **hard** lorsque le passage de l'une de ces formes compte plus que ses faux blocages. + + +| Politique | Autorité | Révisée par | Pourquoi | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | Le motif se déclenche sur toute référence de variable ; Jev demande si des valeurs secrètes seraient réellement affichées. | +| `block-env-files` | reviewable | `secret-exposure` | Le motif correspond à tout chemin `.env`, y compris les modèles ; Jev demande si de vraies valeurs secrètes seraient lues ou écrites. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Mesuré comme bruyant sur le trafic réel ; Jev demande si des contenus de fichiers hors du projet sont lus. Une lecture demandée par l'utilisateur, ou une lecture que la vérification ne trouve rien dans, est levée ; une lecture non sollicitée qu'elle signale maintient le blocage. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Modifier un commit non poussé est ordinaire ; le préjudice est de réécrire l'historique que d'autres ont peut-être tiré. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev demande également si la cible est une vraie base de données plutôt qu'une base de test jetable. | +| `warn-global-package-install` | reviewable | `system-modification` | Le même problème : modifier la machine en dehors du projet. | +| `block-failproofai-commands` | hard | | Auto-protection `alwaysOn`. Jamais reviewable. | +| `block-rm-rf` | reviewable | `destructive-deletion` | L'heuristique de profondeur de chemin se trompe sur `rm -rf node_modules` ; Jev demande si ce qui serait détruit est régénérable. `rm -rf /` maintient les deux sondes à vrai. | +| `block-sudo` | hard | | Élévation de privilèges. | +| `block-curl-pipe-sh` | hard | | Exécute du code téléchargé depuis internet. | +| `block-push-master` | hard | | Pousse directement vers une branche protégée. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` couvre exactement ce problème mais est en mode instruct, donc ne peut jamais répondre deny, et aucune autre vérification ne le couvre. | +| `block-force-push` | reviewable | `git-history-rewrite` | La sonde de Jev est un sur-ensemble du matcher et prend en compte `--force-with-lease` ; ce qui est levé, c'est le force-push sur votre propre branche. | +| `block-secrets-write` | reviewable | `secret-exposure` | La correspondance de chemin n'est pas ancrée, donc `src/auth/credentials.ts` est intercepté ; Jev demande si du vrai matériel de clé est en train d'être écrit. | +| `block-kubectl` | reviewable | `production-infra-change` | Refuse l'ensemble de la CLI, y compris les sous-commandes en lecture seule ; Jev demande si l'appel mute et si la cible est en production. | +| `block-terraform` | reviewable | `production-infra-change` | Identique : lève `terraform plan` et `validate`. | +| `block-aws-cli` | reviewable | `production-infra-change` | Identique : lève `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | reviewable | `production-infra-change` | Identique : lève `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | reviewable | `production-infra-change` | Identique : lève `az account show`. | +| `block-helm` | reviewable | `production-infra-change` | Identique : lève `helm list`, `helm status`. | +| `block-gh-pipeline` | hard | | Déclenche des pipelines, des fusions et des modifications de secrets. | +| `warn-git-stash-drop` | hard | | Aucune vérification sémantique ne couvre l'abandon de travail mis en attente. | +| `warn-git-clean` | hard | | `destructive-deletion` couvre le problème mais ne peut démontrablement pas se déclencher dessus : `git clean` ne nomme aucun chemin, donc sa sonde `irreplaceable` n'a rien à juger et répond bas, et la preuve est le minimum sur les sondes d'une politique. Une vérification qui est consultée et ne se déclenche pas lève le verdict, donc l'associer ici désactiverait la politique. | +| `warn-all-files-staged` | hard | | Aucune vérification sémantique ne couvre ce qu'un `git add` large récupère. | +| `warn-schema-alteration` | hard | | `database-destruction` couvre la suppression de données, pas la modification d'un schéma. | +| `warn-package-publish` | hard | | La publication est irréversible et aucune vérification sémantique ne la couvre. | +| `prefer-package-manager` | hard | | Une convention d'équipe, pas un jugement de sécurité. | +| `warn-large-file-write` | hard | | Un seuil de taille, pas un jugement que Jev peut faire. | +| `warn-background-process` | hard | | Aucune vérification sémantique ne couvre les processus détachés. | +| `warn-repeated-tool-calls` | hard | | Compte les appels ; Jev ne peut pas compter. | +| `sanitize-jwt` | hard | | Redacte la sortie des outils ; ce n'est pas une porte d'appel d'outil. | +| `sanitize-api-keys` | hard | | Redacte la sortie des outils ; ce n'est pas une porte d'appel d'outil. | +| `sanitize-connection-strings` | hard | | Redacte la sortie des outils ; ce n'est pas une porte d'appel d'outil. | +| `sanitize-private-key-content` | hard | | Redacte la sortie des outils ; ce n'est pas une porte d'appel d'outil. | +| `sanitize-bearer-tokens` | hard | | Redacte la sortie des outils ; ce n'est pas une porte d'appel d'outil. | +| `require-commit-before-stop` | hard | | Une porte de fin de session, pas une porte d'appel d'outil. | +| `require-push-before-stop` | hard | | Une porte de fin de session, pas une porte d'appel d'outil. | +| `require-pr-before-stop` | hard | | Une porte de fin de session, pas une porte d'appel d'outil. | +| `require-no-conflicts-before-stop` | hard | | Une porte de fin de session, pas une porte d'appel d'outil. | +| `require-ci-green-before-stop` | hard | | Une porte de fin de session, pas une porte d'appel d'outil. | + +## Semantic policy names + +Ce sont les vérifications que `FailproofAI/jev-policies` déclare, et les valeurs que `reviewedBy` accepte une fois installé. Failproof AI lui-même n'en fournit aucune : sans ce pack (ou un autre déclarant ces noms), aucune politique les nommant n'est reviewable. Chacune est une vérification que Jev effectue sur l'appel d'outil devant lui. **Mode** indique ce qu'une vérification peut répondre : une vérification `deny` bloque sur des preuves solides, tandis qu'une vérification `instruct` n'émet jamais que des avertissements. L'une ou l'autre maintient le refus d'une politique lorsqu'elle se déclenche et que l'utilisateur n'a pas demandé l'appel. **L'utilisateur peut annuler** indique si la demande explicite de l'humain le lève. + +Jev consulte exactement les [vérifications Jev](/fr/policies/publish-a-pack#jev-checks-in-a-pack) déclarées par les packs installés, et ce sont les noms que `reviewedBy` accepte. Un nom déclaré différemment par deux packs n'est honoré par aucun des deux. L'un de ces seize noms déclaré par un pack non installé depuis un dépôt FailproofAI est ignoré dans ce pack : sa version n'est jamais consultée et ne concurrence pas celle de FailproofAI, donc un pack tiers ne peut ni devenir la vérification qui lève les politiques du pack principal ni désactiver l'une de ces vérifications. Une liste de packs illisible, ou un pack dont toutes les vérifications sont inutilisables, ne laisse rien à consulter à Jev. + +| Nom | Mode | L'utilisateur peut annuler | Ce que Jev vérifie | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | oui | Suppression permanente de données ne pouvant être régénérées. | +| `production-infra-change` | deny | oui | Modification d'une infrastructure en production. | +| `git-history-rewrite` | deny | oui | Réécriture ou abandon de l'historique git partagé. | +| `push-to-protected-branch` | instruct | oui | Push direct vers une branche protégée. | +| `commit-on-protected-branch` | instruct | oui | Commit direct sur une branche protégée. | +| `secret-exposure` | deny | oui | Lecture ou copie d'identifiants. | +| `credential-exfiltration` | deny | non | Envoi de secrets ou de fichiers privés hors de la machine. | +| `remote-code-execution` | deny | oui | Exécution de code téléchargé depuis internet. | +| `privilege-escalation` | deny | oui | Exécution avec des privilèges élevés. | +| `database-destruction` | deny | oui | Destruction ou modification en masse de données de base de données. | +| `read-outside-workspace` | instruct | oui | Lecture de fichiers hors du projet. | +| `agent-config-tampering` | deny | non | Modification de la propre configuration de sécurité de l'agent. | +| `system-modification` | instruct | oui | Modification du système en dehors du projet. | +| `env-secrets-dump` | instruct | oui | Affichage de secrets d'environnement. | +| `external-destructive-action` | deny | oui | Une action irréversible via un outil externe. | +| `external-data-egress` | instruct | oui | Envoi de données privées vers un outil externe. | \ No newline at end of file diff --git a/docs/fr/policies/jev-byok.mdx b/docs/fr/policies/jev-byok.mdx new file mode 100644 index 000000000..1c3061ce5 --- /dev/null +++ b/docs/fr/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Evaluateur Jev (apportez votre propre clé)" +description: "Laissez le classificateur Jev de TypeSafe juger les appels d'outils de vos agents au-dessus d'un seuil regex strict, via votre propre endpoint et clé Jev." +icon: "key-round" +--- + +Les politiques regex correspondent à des chaînes de caractères. Elles ne peuvent pas distinguer `rm -rf build/` que vous avez demandé de `rm -rf ~` qui s'est glissé dans un plan — elles bloquent donc trop à un endroit et pas assez à un autre. **Jev**, le classificateur de TypeSafe, lit l'appel au regard de ce que vous avez réellement demandé et répond à un ensemble de questions oui/non à son sujet en une seule requête rapide. + +Avec votre propre endpoint et clé Jev configurés, Failproof AI interroge Jev pour chaque appel d'outil **en parallèle** des politiques regex, jamais à la place de celles-ci : + +- Le refus d'une politique **stricte** est définitif. Jev ne peut pas l'annuler. Toute politique est stricte sauf si elle est explicitement marquée comme révisable et nomme les vérifications Jev qui la couvrent — ainsi, une politique personnalisée, de pack ou Cloud qui ne dit rien est stricte, et la protection automatique toujours active est toujours stricte. +- Le refus d'une politique **révisable** peut être annulé, mais uniquement lorsque Jev a été interrogé sur le problème exact que cette politique couvre et a répondu « rien à signaler » ou « l'utilisateur l'a demandé ». Une vérification qui juge le problème réel, alors que l'utilisateur n'a pas demandé l'appel, maintient le refus — même si son propre verdict n'est qu'un avertissement, car avant un appel d'outil un avertissement n'arrête pas l'agent. Et lorsque cette vérification peut entraîner un refus (exposition de secrets, exfiltration d'identifiants, suppression destructive…), rien n'est annulé pour cet appel. +- Un blocage peut encore devenir un **avertissement** lorsque l'appel est une étape de la tâche que vous avez confiée et ne va pas plus loin : Jev adoucit son propre refus en avertissement, et cet avertissement — précisant ce qui est réellement problématique dans l'appel — remplace le blocage de la politique. +- Jev peut aussi avertir ou refuser de lui-même, pour un préjudice qu'aucune regex ne décrit. +- Si Jev ne peut pas répondre (timeout, limite de débit, erreur serveur, crédits épuisés, version de modèle inattendue), cet appel reçoit le résultat regex, exactement comme sans Jev. +- Jev ne rend jamais un appel plus permissif que vos politiques seules, à moins d'avoir lu l'intégralité de l'appel et d'avoir été interrogé sur le problème exact. Tout ce qui est en deçà — un appel trop volumineux pour être envoyé en entier, une injection suspectée — retire les autorisations et maintient tous les refus. + + +Sans configuration Jev, rien ne change : les hooks exécutent les politiques regex exactement comme ils l'ont toujours fait. La configuration est l'intégralité du mécanisme d'activation. + + + +Vous utilisez FailproofAI Cloud ? Vous n'avez pas besoin de votre propre clé : une machine connectée avec une clé portant `jev:evaluate` peut utiliser Jev sur le plan de votre organisation. Consultez [Jev via FailproofAI Cloud](/fr/policies/jev-cloud). + + +## Choisissez un fournisseur + +Jev est accessible via cinq routes. Apportez une clé pour l'une d'entre elles. + +| Fournisseur | `--provider` | Endpoint | Modèle par défaut | Notes | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Version exacte épinglée. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Les requêtes sont acheminées uniquement vers des endpoints sans rétention de données, sans fallback vers un autre fournisseur. Rapporte une version datée telle que `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nomme Jev uniquement par un alias, donc la version répondante est enregistrée comme non vérifiée. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Nécessite `--account-id`. Environ six appels par seconde par clé ont été mesurés avant HTTP 429. | +| Votre propre endpoint | `custom` | `/systemone` | `jev-1.13.0` | Tout endpoint qui accepte le corps de requête de TypeSafe et indique quel modèle a répondu. `https` uniquement ; le simple `http://localhost` est accepté uniquement en mode shadow. | + + +Avec la fonctionnalité bring-your-own-key de Vercel, une requête échouée est silencieusement réessayée avec les identifiants de Vercel. Si vous avez besoin que chaque appel soit facturé et visible uniquement sur votre propre compte TypeSafe, utilisez TypeSafe directement. + + +## Configuration + +Une seule commande, l'endpoint et la clé : + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### L'URL détermine le fournisseur + +Vous n'avez pas à nommer le fournisseur : le **host** de l'URL indique lequel c'est. + +| Host de l'URL | Fournisseur | Nécessite aussi | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| tout autre host | `custom` | — l'URL fournie est l'URL de base | + +Trois conséquences en découlent : + +- **Une URL qui est l'API propre du fournisseur n'écrit aucune substitution.** `--url https://api.typesafe.ai/v1` produit exactement la même configuration que `--provider typesafe`. Donnez un chemin ou un host différent sur un fournisseur connu et il est stocké comme URL de base, comme le ferait `--base-url`. +- **`--provider` remplace toujours l'inférence**, ce qui permet d'atteindre un proxy qui parle l'API d'un fournisseur depuis votre propre host : `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Un `--provider` qui contredit le host est refusé**, sans tentative de deviner. `--provider openrouter --url https://api.typesafe.ai/v1` n'écrit rien et explique pourquoi : les deux indications sont en désaccord sur la destination de votre clé. La même combinaison est refusée depuis `jev setup --base-url` et depuis les paramètres Jev du tableau de bord. (`--provider custom` n'est pas une contradiction — cela signifie « traiter cette URL telle quelle » — sauf sur le host de Cloudflare, dont l'endpoint par compte ne peut pas être atteint via une route custom.) + +`--url` est validé exactement comme le `baseUrl` dans le fichier de configuration, et refusé dans les mêmes termes : `https`, ou simple `http://localhost` en mode shadow uniquement. + +### La clé + +Transmettez-la avec `--key-stdin`, ou exécutez la commande dans un terminal sans ce flag et collez la clé à l'invite masquée. Dans les deux cas, elle va directement dans le fichier de configuration et n'est jamais affichée en retour. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` prend les mêmes flags et est la forme longue de tout cela : `setup --provider ` pour nommer le fournisseur plutôt que l'URL. + +### `--token` et ce que ça coûte + +`--token ` place la clé sur la ligne de commande, ce qui est le moyen le plus rapide de configurer une machine et la seule façon de laisser la clé ailleurs que dans le fichier de configuration : + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Un argument de ligne de commande se retrouve dans le fichier d'historique de votre shell, et pendant l'exécution de la commande il apparaît dans la liste des processus — lisible depuis `/proc` par tout ce qui s'exécute sous votre identité. `setup` le signale à chaque utilisation de `--token`. Préférez `--key-stdin` sur une machine partagée, dans une session enregistrée, ou partout où le fichier d'historique est synchronisé ; faites tourner une clé transmise de cette façon si cela est important. + + +`--token`, `--key-stdin` et `--key-from-env` sont mutuellement exclusifs : n'en donnez qu'un seul. + +Ensuite, envoyez une petite requête en direct pour vérifier la clé, l'endpoint et quelle version de Jev a répondu : + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` quitte avec le code 1, et l'indique dans son titre, lorsque la réponse arrive après le timeout (chaque hook reviendrait au regex comme `timeout`) ou répond incorrectement à sa question de vérification. + +Les hooks lisent la configuration à chaque appel d'outil, donc elle s'applique dès le suivant. Rien n'est à redémarrer, avec ou sans le daemon. + +## Vérifier ce qu'il fait + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` affiche le fournisseur, l'endpoint, le modèle, le mode, le fichier de configuration et ses permissions — jamais la clé. En dessous, il résume l'activité récente : combien d'appels Jev a évalués, à quelle fréquence il est revenu au regex et pourquoi, sa latence, et quelles politiques révisables il a autorisées. + +## Mode shadow + +`enforce` est le mode par défaut. Pour observer Jev sans lui permettre de modifier aucune décision, passez en mode `shadow` : Jev est toujours interrogé et ses verdicts sont enregistrés, mais c'est le résultat regex qui est appliqué. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` conserve la configuration — l'endpoint et la clé — et cesse d'interroger Jev : les hooks exécutent les politiques regex exactement comme sans configuration, et `failproofai jev status` indique « off (switched off) ». Repassez en mode `shadow` ou `enforce` avec le flag correspondant. + +Relancer `setup` pour le même fournisseur conserve la clé stockée, donc un changement de mode ne nécessite qu'un seul flag. Changer de fournisseur repart de zéro et demande la clé de ce fournisseur. Il en va de même pour un `--base-url` qui déplace les requêtes vers un host différent : une clé stockée n'est envoyée qu'au host pour lequel elle a été fournie, ou à l'API propre de son fournisseur. + +## Le fichier de configuration + +Tout réside dans un seul fichier, `~/.failproofai/jev.json`, écrit par `setup` : + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Champ | Signification | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` ou `custom` — ou `failproofai`, dont la clé provient de la connexion FailproofAI Cloud plutôt que de ce fichier (voir [Jev via FailproofAI Cloud](/fr/policies/jev-cloud)). | +| `apiKey` | Envoyé en tant que `Authorization: Bearer `. | +| `baseUrl` | Obligatoire pour `custom` ; remplace la base API du fournisseur sinon. Doit être `https`. Le simple `http` vers `localhost` est accepté uniquement avec `mode: shadow` : rien n'authentifie un port local, donc pendant que votre proxy est arrêté, tout processus sur la machine, y compris l'agent jugé, pourrait répondre à sa place. | +| `accountId` | Cloudflare uniquement : 32 caractères hexadécimaux en minuscules. | +| `model` | Remplace l'identifiant de modèle par défaut du fournisseur. Un identifiant versionné doit nommer Jev 1.13. Une valeur ressemblant à une clé API est refusée (et non renvoyée), donc une clé collée dans `--model` n'est jamais stockée ni envoyée comme modèle. | +| `timeoutMs` | Durée pendant laquelle un appel d'outil attend Jev avant d'utiliser le résultat regex. 100–10000, défaut 3000. | +| `mode` | `enforce` (défaut), `shadow`, ou `off` (conserver la configuration, ne pas exécuter Jev). | + +Trois règles le protègent : + +- **Propriétaire uniquement.** Il est écrit avec les permissions `0600`. Une copie qu'un autre utilisateur ou groupe peut lire ou écrire est **refusée**, et les hooks reviennent au regex jusqu'à ce que vous exécutiez `chmod 600 ~/.failproofai/jev.json` ou `setup` à nouveau. Le répertoire est aussi vérifié : `~/.failproofai` ne doit pas être **inscriptible** par quelqu'un d'autre, car quiconque peut y écrire peut remplacer le fichier quelles que soient ses propres permissions. `setup` retire ces bits d'écriture s'il les trouve. `failproofai jev status` indique quand une configuration a été refusée et affiche l'endpoint nommé dans le fichier : quelqu'un d'autre pourrait l'avoir modifié, donc vérifiez qu'il vous appartient avant de faire `chmod`. Relancer `setup` sur un tel fichier n'achemine sa clé stockée que vers l'API propre du fournisseur ; tout autre endpoint qu'il nomme nécessite à nouveau la clé (`--key-stdin`), ou `--base-url default` pour renvoyer les requêtes vers le fournisseur. +- **Global uniquement.** Un dépôt ne peut pas activer Jev, le pointer vers un autre endpoint ou choisir son modèle : un `.failproofai/jev.json` à l'intérieur d'un projet est ignoré, et le fournisseur, l'URL, le modèle et l'identifiant de compte ne sont lus que depuis ce fichier — jamais depuis l'environnement, que les paramètres agent d'un dépôt peuvent définir. (`FAILPROOFAI_HOME` ne contourne pas cela : il déplace l'intégralité du répertoire failproofai, vos politiques incluses, plutôt que de rediriger Jev seul.) +- **La clé seule peut provenir de l'environnement.** Si le fichier n'a pas d'`apiKey`, `FAILPROOFAI_JEV_API_KEY` la fournit pour cette session (`setup --key-from-env` écrit un tel fichier). Elle ne remplace jamais une clé que le fichier contient, et elle ne peut pas activer Jev sans le fichier. Lorsque la variable n'est pas définie, Jev est simplement désactivé pour ce shell : `failproofai jev status` l'indique, quitte avec le code 0 et laisse la configuration intacte (`status --json` rapporte `"status": "key-missing"` avec `"reason": "no-env-key"`). Le daemon `failproofaid` ne voit pas l'environnement de votre shell, donc sur une machine configurée avec `failproofai config`, conservez la clé dans le fichier. + +## Quelle version de Jev répond + +Les seuils de décision de Failproof AI ont été calibrés sur Jev 1.13, donc une réponse n'est utilisée que lorsqu'elle provient de cette famille : `jev-1.13.x`, ou `typesafe/jev-1.13-` d'OpenRouter. Lorsqu'un fournisseur nomme Jev uniquement par un alias et ne rapporte aucune version (Vercel, et Cloudflare quand il ne le précise pas), la réponse est utilisée et enregistrée comme non vérifiée. Un endpoint `custom` doit rapporter le modèle qui a répondu ; la seule exception est un nom `--model` non versionné que vous avez configuré pour lui, qui, renvoyé en écho, est enregistré comme non vérifié de la même façon. Une réponse rapportant toute autre version, ou une réponse `custom` n'en rapportant aucune, n'est pas utilisée : cet appel revient au regex avec la raison `model-mismatch`. + +## Quand Jev ne peut pas répondre + +Chacun de ces cas revient au résultat regex pour cet appel et est enregistré avec sa raison, que `failproofai jev status` totalise : + +| Raison | Cause | +| --- | --- | +| `timeout` | Aucune réponse dans le délai `timeoutMs`. | +| `http-429` | Le fournisseur a limité la clé en débit. | +| `rate-limited` | Le limiteur interne de Failproof AI a retenu l'appel avant de l'envoyer : 5 requêtes par seconde, en rafales de 5 au maximum, et aucune pendant un moment après que le fournisseur répond `429`. Pas le fournisseur. | +| `http-500`, `http-502`, `http-503`, … | Une erreur serveur chez le fournisseur. Le statut exact est enregistré. | +| `out-of-credits` | HTTP 402 : le compte fournisseur n'a plus de crédits. | +| `provider-refused` | HTTP 402 de Cloudflare indiquant « Model execution failed (Payment error) » : le fournisseur a refusé d'exécuter le modèle sur cette requête. Généralement pas lié à la facturation, donc recharger les crédits ne résoudra pas le problème. | +| `http-401`, `http-403` | La clé a été refusée. | +| `http-404` | Rien n'est servi à `/systemone`, donc l'URL de base est incorrecte — `/systemone` y est ajouté, et chaque fournisseur le sert à sa racine de version. `failproofai jev models` montre ce que l'endpoint sert effectivement. | +| `network` | L'endpoint n'a pas pu être atteint. | +| `http-301`, `http-302`, `http-307`, `http-308` | L'endpoint a répondu avec une redirection. Les redirections ne sont jamais suivies, donc la réponse ne vient que de l'URL dans votre configuration ; définissez `--base-url` sur l'URL finale. | +| `malformed` | L'endpoint a répondu, mais pas avec une réponse Jev — un corps qui n'est pas JSON, ou sans réponses. | +| `cloudflare-error`, `cloudflare-incomplete` | L'enveloppe de Cloudflare a rapporté un échec, ou un job non terminé. | +| `model-mismatch` | Une version de Jev autre que 1.13 a répondu, ou un endpoint `custom` n'a pas indiqué quel modèle a répondu. | +| `request-cut` | **Pas une panne.** Jev a répondu ; il n'a vu qu'une partie de l'appel, donc sa réponse n'a rien autorisé. Voir [Quand Jev a répondu, mais pas sur l'intégralité de l'appel](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` peut aussi afficher quelques raisons plus rares, comme `upstream-error` (la réponse portait l'erreur propre du fournisseur) ou `config`, et totalise toute raison qu'il ne peut pas nommer sous `other`. + +`request-cut` figure dans ce tableau parce que `failproofai jev status` le totalise avec les autres, et parce qu'il maintient lui aussi tous les refus. C'est la seule raison ici qui ne dit rien sur votre fournisseur : la requête est arrivée et Jev y a répondu. Contrairement à toutes les lignes précédentes, cette réponse compte quand même — le propre refus ou avertissement de Jev s'applique en plus du résultat regex plutôt que d'être ignoré. Donc une suite de ces cas signifie que des appels atteignent l'évaluateur trop volumineux pour être envoyés en entier, pas que votre endpoint est défaillant, et recharger des crédits ou changer d'URL ne fera pas baisser le nombre. + +## Quand Jev a répondu, mais pas sur l'intégralité de l'appel + +Deux autres situations peuvent se produire, et aucune ne correspond à un échec de réponse de Jev. Toutes deux portent sur la quantité de l'appel, ou de la conversation, qui tient dans une seule requête. + +**Une partie de l'appel lui-même n'a pas tenu.** Un appel d'outil est envoyé dans un budget fixe, et un très volumineux — un très grand `Write`, un énorme corps MCP, une commande gonflée jusqu'à la limite — est envoyé avec ce qui a tenu. Jev répond quand même, et sa réponse compte quand même : son propre refus ou avertissement s'applique normalement. Ce qu'il ne peut pas faire, c'est **autoriser** quoi que ce soit, car un verdict rendu sur une partie d'un appel n'est pas un verdict sur l'appel. Donc tous les refus de politique restent, et l'appel est enregistré comme un fallback avec la raison `request-cut`, que `failproofai jev status` totalise avec les raisons ci-dessus. La règle que cela vous donne : rendre un appel plus volumineux peut lui coûter ses autorisations, et ne peut jamais en obtenir une. + +**Un message n'a pas tenu.** Un long prompt que vous avez collé, le dernier message de l'agent, ou un prompt que le store propre de cet évaluateur avait déjà tronqué. **Rien ne change** : l'appel est jugé, autorisé et enregistré exactement comme n'importe quel autre, et il n'est pas comptabilisé comme fallback. La longueur de ce que vous tapez ne détermine jamais un verdict, et une troncature ne peut pas fabriquer un consentement : lorsqu'un prompt est arrivé déjà tronqué, « vous n'avez pas demandé ceci » cesse d'être une conclusion qui peut en être tirée, plutôt que de le devenir. + +La ligne de démarcation entre les deux, c'est qui a écrit le texte. L'appel appartient à l'agent, et une règle qui permettrait à sa longueur de réduire la gravité serait une règle dont l'agent pourrait se servir ; votre prompt vous appartient, et traiter sa longueur comme un signal ne fait que pénaliser le fait de coller une spec ou une trace de pile. + +## Ce qui quitte la machine + +Pour chaque appel d'outil que Jev évalue, une requête est envoyée à votre fournisseur, contenant : + +- l'appel d'outil lui-même, avec les secrets tels que les clés API, les tokens bearer et les affectations `KEY=` masqués ; +- les prompts récents que vous avez tapés, avec le texte ajouté par le harnais de votre agent retiré ; +- le dernier message de l'agent avant votre dernier prompt, étiqueté comme écrit par l'agent ; +- des faits calculés localement, comme si un chemin est à l'intérieur du projet — celui dans lequel la session se trouvait lors de son premier appel révisé, [épinglé pour la session](/fr/reference/jev-intent#the-project-root) — et la branche git actuelle. + +Cela va uniquement vers l'endpoint dans votre configuration, sous votre clé. + +## Désactivation + +```bash +failproofai jev remove +``` + +Cela supprime `~/.failproofai/jev.json`. À partir du prochain appel d'outil, les hooks exécutent les politiques regex exactement comme avant. Les stores par session sous `~/.failproofai/state/semantic/` (prompts enregistrés dans `sessions/`, racines de projet dans `roots/`) sont laissés en place et expirent naturellement. Pour arrêter d'interroger Jev tout en conservant la configuration, utilisez plutôt `failproofai jev setup --mode off`. + +## Référence des commandes + +| Commande | Résultat | +| --- | --- | +| `failproofai jev --url --key-stdin` | Le configurer en une seule commande ; le fournisseur est déduit du host de l'URL | +| `failproofai jev --url --token ` | Pareil, avec la clé sur la ligne de commande — votre historique et la liste des processus la voient | +| `failproofai jev setup --provider --key-stdin` | Écrire la configuration depuis une clé transmise sur stdin | +| `failproofai jev setup --provider ` | Pareil, en demandant la clé à une invite masquée | +| `failproofai jev setup --key-from-env` | Ne stocker aucune clé ; lire `FAILPROOFAI_JEV_API_KEY` par session | +| `failproofai jev setup --mode shadow` | Changer de mode (`enforce`, `shadow` ou `off`), en conservant la clé stockée | +| `failproofai jev setup --model ` / `--base-url ` | Remplacer le modèle ou la base API ; `default` efface la substitution | +| `failproofai jev setup --timeout-ms ` | Modifier le budget par appel | +| `failproofai jev status [--json]` | Configuration, permissions et activité récente ; jamais la clé | +| `failproofai jev test [--json]` | Une requête en direct : latence et version ayant répondu | +| `failproofai jev models [--provider ] [--url ] [--json]` | Les identifiants de modèles que `/models` de cet endpoint rapporte, en marquant celui configuré | +| `failproofai jev remove` | Supprimer la configuration ; Jev est désactivé | \ No newline at end of file diff --git a/docs/fr/policies/jev-cloud.mdx b/docs/fr/policies/jev-cloud.mdx new file mode 100644 index 000000000..ce98411c7 --- /dev/null +++ b/docs/fr/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev via FailproofAI Cloud" +description: "Laissez Jev évaluer les appels d'outils de vos agents via FailproofAI Cloud, sur le forfait de votre organisation, sans compte ni clé TypeSafe personnels." +icon: "cloud" +--- + +[Jev](/fr/policies/jev-byok), le classificateur de TypeSafe, analyse chaque appel d'outil par rapport à ce que vous avez réellement demandé et intervient aux côtés de vos politiques, sans jamais les remplacer. Via **FailproofAI Cloud**, une machine connectée utilise Jev avec la clé qu'elle utilise déjà pour se connecter : pas de compte TypeSafe, pas de seconde clé, pas d'endpoint à configurer. Chaque appel est imputé sur l'allocation du forfait existant de votre organisation. + +Tout ce que fait Jev est identique à la [configuration avec votre propre clé](/fr/policies/jev-byok) : les politiques strictes restent définitives, le refus d'une politique révisable n'est levé que lorsque Jev a été interrogé précisément sur ce point, et toute défaillance revient au résultat regex pour cet appel. + + +Nécessite **failproofai 1.0.8-beta.0** ou une version ultérieure. La version 1.0.7 ne dispose pas de Jev, même si elle apparaît au-dessus des versions bêta 1.0.7 dans le tri. Sans configuration Jev, rien ne change : les hooks exécutent les politiques regex exactement comme avant. + + +## Activation + +1. **Créez une clé avec Jev.** Dans le tableau de bord FailproofAI Cloud, ouvrez **Keys → Create key** et choisissez le preset **machine**. Il accorde les trois permissions dont une machine a besoin : `events:add` (envoyer l'activité), `policies:pull` (recevoir les politiques) et `jev:evaluate` (Jev, imputé sur le forfait de votre organisation). Une clé ne peut pas porter `jev:evaluate` sans les deux autres. +2. **Connectez la machine** avec cette clé : + + ```bash + failproofai config --token + ``` + + Si votre organisation gère sa propre instance FailproofAI Cloud plutôt que le service hébergé, ajoutez son adresse : `--url https://` (ou exportez `FAILPROOFAI_CLOUD_URL`). Sans cela, la clé est vérifiée contre le service hébergé et la connexion échoue. Si le certificat de cet hôte provient d'une CA privée, installez la CA dans le magasin de confiance système de la machine (par exemple avec `update-ca-certificates`), et non uniquement dans `NODE_EXTRA_CA_CERTS` : le démon qui envoie les événements et récupère les politiques lit le magasin système. Consultez [Dépannage](/fr/reference/troubleshooting). + +C'est tout. La connexion enregistre la clé et, lorsque la machine n'a **pas encore** de configuration Jev, active Jev via FailproofAI Cloud en mode **shadow** : Jev est interrogé pour chaque appel d'outil soumis à condition et ses verdicts sont enregistrés, mais c'est le résultat de vos politiques qui est appliqué. Le résultat l'indique : + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**Avec `--no-transcripts`, la connexion n'active pas Jev.** Jev envoie chaque appel d'outil vérifié ainsi que le prompt récent à FailproofAI Cloud, ce qui va au-delà de ce qu'une connexion en mode décisions uniquement est autorisée à envoyer. La clé est tout de même enregistrée, et le résultat indique que Jev est disponible et comment l'activer : + +```bash +failproofai jev setup --provider failproofai +``` + +Cela n'**désactive** pas non plus Jev. Si le fichier `jev.json` de la machine exécute déjà Jev via FailproofAI Cloud, il reste tel quel, et le résultat indique que Jev continue d'envoyer chaque appel d'outil vérifié et le prompt récent, et que `failproofai jev setup --mode off` permet de le désactiver. + + +La connexion **ne remplace jamais** un fichier `~/.failproofai/jev.json` existant. Si vous utilisez déjà votre propre endpoint Jev, il continue d'être utilisé, et le résultat indique que le fichier a été laissé tel quel — et, lorsque ce fichier laisse Jev désactivé (refusé ou désactivé manuellement), l'indique ainsi que la marche à suivre. Pour basculer cette machine sur FailproofAI Cloud, exécutez `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce ou off + +Commencez en mode shadow, observez ce que Jev aurait fait sur la page des politiques, puis laissez-le agir : + +```bash +failproofai jev setup --mode enforce # Les verdicts de Jev s'appliquent : il peut lever un refus révisable et émettre le sien +failproofai jev setup --mode shadow # Jev est interrogé et enregistré ; c'est le résultat de vos politiques qui est appliqué +failproofai jev setup --mode off # Conserve la configuration, cesse d'interroger Jev +``` + +Le même commutateur se trouve dans le tableau de bord local : **Settings → Jev** dispose d'un bouton on/off et d'un choix shadow/enforce. Il réécrit uniquement le mode. Les hooks lisent la configuration à chaque appel d'outil, donc un changement s'applique dès l'appel suivant, sans redémarrage. + +## Vérifier ce qu'il fait + +```bash +failproofai jev status +failproofai jev test +``` + +`status` affiche le fournisseur comme **FailproofAI Cloud**, l'hôte Cloud auquel la machine est connectée, le mode, et la source de la clé comme **connexion FailproofAI Cloud**, jamais la clé elle-même. Lorsqu'un fichier `jev.json` FailproofAI Cloud est en place mais que Jev ne peut pas fonctionner, il en indique la raison : + +| `status` indique | `status --json` | Signification | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | La machine est connectée, mais aucune clé Jev n'est enregistrée pour elle : la clé ne possède pas `jev:evaluate`, ou la connexion n'a pas pu le confirmer. Exécutez à nouveau `failproofai config --token ` avec la même clé ; si elle ne dispose pas de la permission, utilisez une clé **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Il n'y a pas de connexion FailproofAI Cloud sur cette machine pour la clé Jev. | + +Après `failproofai config --disconnect`, il n'y a plus de fichier `jev.json` FailproofAI Cloud (sauf s'il avait été désactivé, auquel cas il est conservé), donc `status` signale simplement Jev comme désactivé. `status --json` contient les mêmes informations (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), y compris lorsque la configuration est absente ou refusée. `permissions` correspond toujours au contenu de `jev.json` ; un refus concernant `credentials.json` ajoute `credentialsPermissions`, ainsi que `fix` lorsqu'une seule commande suffit à corriger le problème. `test` envoie une requête en direct et rapporte sa latence ainsi que la version de Jev qui a répondu. Il se termine avec le code 1, et l'indique dans son titre, lorsque la réponse arrive après le délai d'expiration du hook (les hooks enregistreraient `timeout`) ou répond incorrectement à sa question de vérification. + +Le panneau **Settings → Jev** du tableau de bord affiche également la **connexion FailproofAI Cloud** : l'organisation dans laquelle la machine est enregistrée et si sa clé porte Jev. Ces informations sont lues depuis les fichiers locaux de la machine, sans appel réseau. + +## Ce qui parvient à la page des politiques + +La machine envoie déjà son activité de hook à FailproofAI Cloud (`events:add`). Avec Jev activé, l'enregistrement de chaque appel soumis à condition indique également quel évaluateur a été utilisé, ce que Jev a décidé, quelles politiques il a levées, pourquoi il a reculé le cas échéant, sa latence et le modèle qui a répondu — décisions, codes et noms, jamais la commande ni votre prompt. Sur la page **Policies** de votre organisation : + +- un appel décidé par le verdict propre de Jev (mode enforce) est attribué à **Jev**, et lorsque la vérification décisive provient d'un pack, l'enregistrement nomme également ce pack et sa version ; +- en mode shadow, le refus ou l'avertissement de Jev apparaît comme un **would-have**, à côté des déploiements que vous observez ; +- les politiques levées par Jev, ou qu'il aurait levées en mode shadow, sont comptabilisées par politique. + +## Quand Jev ne peut pas répondre + +Chacun des cas suivants revient au résultat de vos politiques pour cet appel, et est enregistré avec sa raison : + +| Raison | Cause | +| --- | --- | +| `out-of-credits` | Votre organisation a épuisé son allocation de forfait. | +| `http-401`, `http-403` | La clé a été révoquée, ou ne porte pas `jev:evaluate`. Reconnectez-vous avec une clé qui le possède. | +| `http-429` | FailproofAI Cloud limite le débit de Jev pour votre organisation. Jusqu'à la fin du délai demandé (`Retry-After`, 60 secondes au maximum), la machine n'envoie rien et chaque appel revient immédiatement au résultat de secours. Les appels retenus de cette façon sont enregistrés comme `http-429`, ou comme `rate-limited` lorsque la limite de débit propre de la machine les retient en premier. | +| `http-429` (limite quotidienne) | Votre organisation a atteint sa limite quotidienne d'appels Jev : **10 000 par jour UTC**, sauf si l'opérateur de votre FailproofAI Cloud a défini une autre limite. Chaque appel revient au résultat de secours jusqu'à la réinitialisation du compteur à 00:00 UTC ; la machine interroge à nouveau au maximum une fois par minute, donc elle détecte la réinitialisation en moins d'une minute. `failproofai jev test` affiche « Daily Jev limit for this org reached; resets at 00:00 UTC. » | +| `http-422` | Jev a refusé la requête de cet appel, généralement parce que l'appel d'outil contenait du texte dense (base64, hexadécimal, code minifié) dépassant le budget de tokens de Jev. Cet appel revient toujours au résultat de secours ; ce n'est pas une panne. | +| `http-502` | Jev est temporairement indisponible. | +| `http-503` | Ce Cloud ne peut pas servir Jev pour votre organisation : pas de passerelle de modèle, une organisation pas encore provisionnée, ou la passerelle est hors service. Contactez votre administrateur ; les hooks réessayent au maximum une fois par minute. | +| `http-404` | Ce FailproofAI Cloud ne propose pas encore Jev. | +| `timeout` | Aucune réponse dans le délai `timeoutMs` (3000 ms par défaut). | +| `model-mismatch` | Une version de Jev autre que 1.13 a répondu. | + +## Où la clé est stockée et où elle va + +- La clé est stockée une seule fois, dans `~/.failproofai/credentials.json` (`0600`, dans un répertoire accessible uniquement par le propriétaire), aux côtés des autres identifiants FailproofAI Cloud. `jev.json` ne contient aucune clé pour cette route ; une clé qui y serait écrite rend la configuration invalide. +- Si `credentials.json` accorde **une quelconque** permission à quelqu'un d'autre que vous (groupe ou autre, lecture ou écriture), ou si son répertoire peut être **écrit** par quelqu'un d'autre que vous, il est **refusé**, non lu, et Jev est désactivé jusqu'à ce que vous corrigiez le problème : `chmod 600` sur le fichier, `chmod 700` sur le répertoire (ou reconnectez-vous, ce qui réécrit le fichier avec les permissions `0600` et rend le répertoire accessible uniquement par le propriétaire). Un répertoire que d'autres peuvent seulement lire est acceptable ; un répertoire qu'ils peuvent écrire leur permet de substituer le fichier. +- La clé ne compte que tant que la connexion avec laquelle elle est arrivée est présente sur la machine : un identifiant de politique ou de reporting pour le même FailproofAI Cloud **avec la même clé**, dans le même fichier. Une clé Jev laissée sans connexion est ignorée, et Jev reste désactivé. Cela se produit lorsque la commande `config --disconnect` d'une version plus ancienne de failproofai laisse la clé Jev en place (elle ne sait pas qu'il faut la supprimer), ou lorsque la commande `config --token` d'une version plus ancienne de failproofai se connecte avec une autre clé, qui sur FailproofAI Cloud peut appartenir à une autre organisation. Pour réactiver Jev, reconnectez-vous avec une clé **machine**. +- La clé est uniquement envoyée à l'origine Cloud contre laquelle elle a été vérifiée. Un fichier `jev.json` pointant ailleurs est refusé. +- **Un agent sur la machine peut la lire.** `credentials.json` est accessible uniquement par le propriétaire, et l'agent s'exécute en tant que ce propriétaire. La lecture des fichiers propres à failproofai est autorisée intentionnellement (seule leur modification est bloquée, par `block-failproofai-commands`), donc la seule chose entre un agent et ce fichier est `block-read-outside-cwd` — une politique *révisable* — et, depuis une session démarrée dans votre répertoire personnel, rien du tout. Une clé avec `jev:evaluate` dépense l'allocation Jev de votre organisation (dans la limite du plafond quotidien) depuis n'importe quel endroit où elle est utilisée, donc traitez une clé machine comme tout autre identifiant de dépense : si un agent a pu la lire, désactivez-la sur la page Keys et reconnectez-vous avec une nouvelle. +- Seuls vos fichiers globaux déterminent cela. Un dépôt ne peut pas activer Cloud Jev, le pointer ailleurs ni fournir sa clé, et `FAILPROOFAI_JEV_API_KEY` est ignoré pour cette route. +- Pour chaque appel évalué par Jev, une requête est envoyée à FailproofAI Cloud, contenant ce que la [page bring-your-own-key](/fr/policies/jev-byok#what-leaves-the-machine) liste (secrets expurgés). FailproofAI Cloud le transmet à TypeSafe et ne le journalise ni ne le conserve. + +## Désactivation + +| Commande | Résultat | +| --- | --- | +| `failproofai jev setup --mode off` | Conserve la configuration ; Jev n'est plus interrogé. **C'est le commutateur qui persiste :** une nouvelle connexion ne réécrit jamais un fichier `jev.json` existant, donc Jev reste désactivé jusqu'à ce que vous le réactiviez avec `--mode shadow`. | +| `failproofai jev remove` | Supprime `~/.failproofai/jev.json` ; Jev est désactivé — jusqu'à la prochaine exécution de `failproofai config --token` avec une clé portant `jev:evaluate`, qui ne trouvant pas de `jev.json` activera à nouveau Jev en mode shadow (sauf si elle s'exécute avec `--no-transcripts`). Pour le garder désactivé, utilisez `--mode off`. | +| `failproofai config --disconnect` | Déconnecte la machine : la clé est supprimée, ainsi que `jev.json` lorsqu'il désigne FailproofAI Cloud et n'est pas en mode désactivé. Un fichier `jev.json` pour votre propre endpoint est conservé, de même qu'un fichier en mode désactivé, de sorte que Jev reste désactivé lors d'une nouvelle connexion. | + +Dès l'appel d'outil suivant, les hooks exécutent les politiques regex exactement comme avant. \ No newline at end of file diff --git a/docs/fr/policies/jev.mdx b/docs/fr/policies/jev.mdx new file mode 100644 index 000000000..1d0cdbbdf --- /dev/null +++ b/docs/fr/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Politiques Jev" +description: "Ajoutez la revue en direct de Jev aux appels d'outils soumis à validation, puis inspectez ses décisions avant de les appliquer." +icon: "shield-check" +--- + +Jev analyse un appel d'outil en le confrontant à ce que la personne a demandé à l'agent d'accomplir. Utilisez-le lorsqu'une politique basée sur la correspondance de chaînes bloque un travail valide ou laisse passer une action risquée qui nécessite du contexte. Il répond en même temps que vos politiques au niveau de la porte `PreToolUse` ou `PermissionRequest`. Pour un score **après** la fin d'une session, utilisez les [évaluations Jev](/fr/evaluations/jev). + +## Démarrer en mode observation + +Installez Failproof AI et attachez des hooks à un [harnais pris en charge](/fr/reference/harnesses). Utilisez failproofai 1.0.8-beta.0 ou une version ultérieure. + +Failproof AI ne fournit aucune vérification Jev par défaut. Installez-les sous forme de pack, sinon Jev n'a rien à analyser et n'est jamais appelé : + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Choisissez ensuite comment les requêtes parviennent à Jev : + +| Itinéraire | Première étape | +| --- | --- | +| FailproofAI Cloud | Connectez-vous avec une clé **machine** disposant de l'autorisation `jev:evaluate`. Sur une machine sans configuration Jev, `failproofai config` active Jev en mode observation. | +| Votre propre fournisseur | Dans le tableau de bord local, ouvrez **Paramètres → Jev**, choisissez le fournisseur, collez son token, puis sélectionnez **observer**. Ou exécutez `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![Les paramètres Jev du tableau de bord local : fournisseur, point de terminaison, token et mode observation avant l'activation de Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` vérifie le point de terminaison. Pour vérifier le chemin du hook, demandez à un agent instrumenté d'utiliser son outil de lecture de fichiers sur `README.md`. Confirmez que cet appel d'outil apparaît dans la session, puis inspectez **Politiques → Activité** dans le [tableau de bord local](/fr/reference/local-dashboard#review-policy-activity). Le compteur Jev dans `status` devrait augmenter. Le mode observation enregistre ce que Jev aurait décidé, tandis que le résultat de votre politique existante continue de s'appliquer. + +## Décider quand appliquer + +Une politique **hard** a toujours le dernier mot. Jev ne peut lever un refus que d'une politique explicitement marquée comme **reviewable**, et uniquement lorsqu'il a examiné la préoccupation nommée par cette politique. Consultez l'[autorité des politiques](/fr/policies/authority) avant de vous fier à une levée de blocage. Jev peut également émettre un avertissement ou refuser de son propre chef. S'il ne peut pas répondre, c'est le résultat de la politique qui détermine l'appel. + +Une fois que les résultats en mode observation semblent corrects, passez en mode application dans **Paramètres → Jev** ou exécutez : + +```bash +failproofai jev setup --mode enforce +``` + +Pour les URL de fournisseur, les clés Cloud, la configuration, les mécanismes de repli et les données envoyées avec chaque requête, consultez la [référence d'intégration Jev](/fr/reference/jev). \ No newline at end of file diff --git a/docs/fr/reference/custom-agents-typescript.mdx b/docs/fr/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..10c3047c3 --- /dev/null +++ b/docs/fr/reference/custom-agents-typescript.mdx @@ -0,0 +1,433 @@ +--- +title: "Agents personnalisés (TypeScript)" +description: "Configuration, le catalogue d'événements, les portées et les adaptateurs de framework pour @failproofai/sdk." +icon: "square-js" +--- + +Tout ce que fait chaque paramètre, méthode et champ dans le SDK TypeScript. Si vous instrumentez pour la première fois, commencez par le guide — cette page sert de référence. + + + + Installation, instrumentation, les méthodes d'événements, un exemple concret et les problèmes courants. + + + Les mêmes événements, le même format wire, le même spool — depuis Python. + + + +Node 20.9 ou version ultérieure. ESM et CommonJS. Aucune dépendance d'exécution. + + + Ce SDK et celui de Python écrivent **les mêmes événements dans le même spool**. Une flotte d'agents Node et d'agents Python produit un seul ensemble de sessions, pas deux, et rien dans le tableau de bord ne les distingue. Choisissez par service, pas par entreprise. + + +## Installation + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Les adaptateurs de framework sont inclus dans le package lui-même. Les frameworks sont des **dépendances pair optionnelles** — déclarées pour que les plages supportées soient visibles, jamais installées à votre place, et importées uniquement lorsque vous appelez `instrument()`. + +## Connecter le daemon Failproof + +Identique au SDK Python : créez une clé `events:add` sous **Admin → Keys**, puis [connectez le daemon](/fr/start/setup#connect-a-machine-to-cloud) sur la machine de l'agent. Le SDK écrit sur disque ; le daemon expédie. + +## Configuration + +### Spans OpenTelemetry (opt-in) + +Installez OpenTelemetry séparément avec `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Ajoutez ensuite FailproofAI aux processeurs de votre fournisseur : + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Pour un fournisseur existant, conservez ses autres processeurs dans la même liste. Les fournisseurs +qui exposent `addSpanProcessor` peuvent à la place être passés sous la forme `{ provider }`. Sans +options, la configuration enregistre un nouveau fournisseur uniquement si aucun fournisseur n'est déjà enregistré. +`OtelSpanExporter` peut également être utilisé directement avec votre propre processeur. + +Les exports transitent par le daemon FailproofAI connecté ; le SDK n'envoie aucune requête réseau +et ne nécessite ni clé ni listener local. Demandez à un administrateur d'activer +l'[ingestion OpenTelemetry](/fr/agenteye/opentelemetry). Un `instrument()` nu n'active pas +cet exportateur. `uninstrument("otel")` désactive uniquement son propre processeur. +Vos attributs de span contrôlent la capture du contenu ; videz votre fournisseur avant la sortie. +OpenTelemetry reste une dépendance applicative optionnelle, pas une dépendance SDK obligatoire. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Option | Ce qu'elle fait | +| --- | --- | +| `environment` | Le label sur chaque événement — `production`, `staging`, `prod-eu`. Par défaut `dev`. | +| `flushInterval` | La fréquence à laquelle le timer écrit sur disque, en secondes. Par défaut `0.5`. | +| `baseDir` | Où écrire. Par défaut dans le spool du daemon, ce qui est ce que vous voulez sauf si vous savez autrement. | + +Rien n'est appliqué à moins que tout ne soit validé, donc un appel rejeté laisse le SDK exactement tel qu'il était plutôt qu'avec un nouveau `baseDir` et l'ancien intervalle. + +Configuration par variable d'environnement : + +| Variable | Ce qu'elle fait | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Définit `environment` sans modification du code. Une option `configure()` l'emporte dessus. | +| `FAILPROOFAI_HOME` | Déplace la racine Failproof AI qui contient le spool. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (par défaut), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` fait lancer les erreurs d'instrumentation au lieu de les logger. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` fait lever une exception en cas de problème de compatibilité de framework au lieu d'avertir et de continuer. | + + + **Pas de virgules dans `environment`.** L'ingestion divise ce champ sur les virgules pour construire ses filtres, et ignore tout événement dont le label en contient une — une exécution entière disparaît alors silencieusement. Écrivez `prod-eu`, pas `prod,eu`. + + `configure({ environment: "prod,eu" })` lève une exception pour que vous le sachiez immédiatement. `AGENTEYE_ENVIRONMENT` ne peut pas lever d'exception — rien ne vous appelle — donc il avertit une fois et revient à `dev`. + + +Redirigez les lignes de log du SDK lui-même vers votre logger avec `failproofai.setLogger({ debug, info, warn, error })`. + +## Arrêt + +Les événements en mémoire tampon sont vidés sur `process.on("exit")`. + +Un processus tué par un signal n'atteint jamais ce point, et le comportement par défaut de Node pour `SIGTERM` est de terminer sans exécuter les gestionnaires de sortie — ainsi un agent conteneurisé perd ce que le dernier intervalle n'avait pas encore écrit. + + + **Ce SDK n'installera pas de gestionnaire de signal pour vous.** En enregistrer un modifie le comportement de votre processus : un listener supprime la terminaison par défaut de Node, donc une bibliothèque qui en ajoutait un silencieusement empêcherait Ctrl-C de fonctionner. Ajoutez le vôtre : + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Un script de courte durée ou un gestionnaire serverless devrait `await failproofai.flush()` avant de retourner — l'intervalle seul ne garantit pas la livraison. + +## Identité + +Chaque événement appartient à une session et à un agent. **Les portées remplissent les deux**, donc vous les passez rarement : + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Passer `sessionId` ou `agentId` explicitement fonctionne toujours et l'emporte. Si ni l'un ni l'autre n'est lié ou passé, l'appel lève une exception plutôt que d'émettre un événement que Cloud ignorerait silencieusement. + + + L'identité repose sur `AsyncLocalStorage`. Elle suit `await`, `.then()`, les timers et tout callback créé à l'intérieur de la portée. Elle ne **suit pas** un callback stocké pendant une exécution et invoqué pendant une autre, ni un travail transmis à travers une frontière `worker_threads` — enveloppez ceux-là dans `failproofai.propagate()` ou leurs événements se retrouveront non rattachés. + + +### Portées + +| Portée | Émet | Retourne | +| --- | --- | --- | +| `session(body)` | rien — identité uniquement | ce que `body` retourne | +| `agent(id, options?, body)` | `agent_start`, puis `agent_end` | ce que `body` retourne | +| `toolCall(name, options?, body)` | `tool_use`, puis `tool_result` | ce que `body` retourne | + +Un corps synchrone reste synchrone : `agent("x", () => 1)` retourne `1`, pas une promesse. + +`toolCall` enregistre la valeur résolue du corps comme `output` de l'outil, sauf si vous assignez vous-même `call.output`. + + + +| Ce qui s'est passé | Événements | `outcome` | +| --- | --- | --- | +| le bloc a retourné | `agent_end` | `"success"`, ou votre `outcome` | +| le bloc a levé une exception | `error`, puis `agent_end` | `"failed"` | +| une `AbortError` | `agent_end` uniquement | `"cancelled"` | + +L'erreur est toujours re-levée. + +Un échec d'outil est enregistré sur la feuille — `tool_result` avec une chaîne `error` — et n'émet **aucun** événement `error` au niveau de l'exécution. Celui que la boucle de l'agent intercepte n'est pas un échec d'exécution, et celui qui se propage est signalé exactement une fois, par l'`agent()` englobant. + + + + + +Quand le travail n'est pas une fonction unique — une portée ouverte dans un constructeur et fermée dans un teardown, ou qui enjambe un flux de contrôle existant : + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +Les deux formes émettent des événements identiques octet par octet. Préférez la forme callback : elle s'exécute à l'intérieur de `AsyncLocalStorage.run()`, donc il n'y a rien à dérouler et toute la classe de bugs du type « ouvert ici, fermé ailleurs » est inaccessible. + +Un bloc `using` qui intercepte sa propre défaillance la signale avec `span.fail(error)` — le disposer n'a pas de canal d'exception propre. + + + +## Catalogue d'événements + +Les mêmes quinze méthodes que le SDK Python, en camelCase. La plupart viennent en **paires** — vous appelez l'ouvreur, puis le fermeur, et le SDK mesure l'intervalle. + +| | Ouvre | Ferme | +| --- | --- | --- | +| **Agents** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Modèles** | `modelRequest` | `modelResponse` | +| **Outils** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Humains** | `humanWait` | `humanInput` | + +Trois sont autonomes : `error`, `humanPause`, `humanInterrupt`. + + + +Chaque méthode accepte aussi `sessionId` et `agentId`, que les portées remplissent pour vous. Tout ce qui est omis est supprimé plutôt qu'envoyé comme JSON `null`. + +| Méthode | Requis | Optionnel | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Toute autre clé que vous ajoutez devient un champ de payload personnalisé. Préfixez tout ce qui est spécifique à un framework avec `fw_*` ; un nom qui entre en collision avec un champ déclaré est refusé plutôt que d'écraser silencieusement une colonne promue. + + + + + **`duration_ms` est calculé, pas accepté.** Les quatre méthodes de fermeture mesurent l'intervalle depuis leur ouvreur et refusent un `duration_ms` fourni par l'appelant — une durée rapportée est infalsifiable. + + Les paires sont associées sur la **session** et l'identifiant, jamais sur l'agent. Un outil ouvert sous `planner` et fermé sous `worker` forme quand même une paire, ce que les exécutions multi-agents imbriquées font réellement. + + +## Adaptateurs de framework + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| Framework | Supporté | Comment il s'attache | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, donc chaque `invoke`/`stream`/`batch` est couvert sans passer `callbacks:` nulle part — ou passez `langchainHandler()` vous-même et ne patchez rien. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` au site d'appel, ou `instrument("ai")` pour tout le processus sur `ai` 7 (sur 4–6, c'est opt-in — voir ci-dessous). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, le modèle de l'agent et la résolution des outils, ainsi que le moteur d'exécution des workflows et des étapes. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (souscrit) plus `AgentWorkflow.runStream`, pour les exécutions de workflows et leurs étapes. | + +Chaque plage est testée contre de vraies versions de framework, aux deux extrémités, en tant que module ES et en CommonJS, à chaque exécution CI. + +Le mapping est celui du SDK Python, donc le même programme produit le même arbre dans les deux langages. Une construction est un **agent** uniquement si elle possède une boucle de décision LLM — une exécution de graphe ou de chaîne, un appel `generateText`/`streamText` de l'AI SDK, un agent Mastra, une exécution d'agent LlamaIndex. Un nœud LangGraph ou une étape de workflow est un **hook** (`hook_triggered`/`hook_completed`), jamais un agent imbriqué. Les appels de modèle sont des paires `model_request`/`model_response` avec le nombre de tokens ; les appels d'outil portent l'identifiant d'appel d'outil propre au modèle. Un échec est enregistré une fois, sur l'événement où il s'est produit. + +Un adaptateur qui échoue à s'installer est loggé et ignoré ; les autres s'installent quand même, car un LlamaIndex cassé ne doit pas vous coûter LangGraph. + + + `instrument()` sans argument détecte un framework par le fait qu'il **se résout**, pas par le fait qu'il est déjà importé — Node n'expose pas d'équivalent de `sys.modules` de Python pour les modules ES. Un framework que vous avez installé mais n'utilisez pas sera importé et patché. Nommez celui que vous voulez si cela compte. + + + + La plupart de ces frameworks fournissent à la fois un build en module ES et un build CommonJS, que Node charge comme deux copies non liées. Les adaptateurs patchent la copie que votre application charge (ainsi que la copie CommonJS si quelque chose l'a déjà `require`d), donc les deux systèmes de modules fonctionnent. Un framework **bundlé dans votre propre sortie** par esbuild ou webpack est hors de portée — utilisez les helpers au site d'appel : `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain sans patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +Le handler fonctionne avec ou sans `instrument()` et ne double jamais l'enregistrement. `instrument("langchain")` accepte `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` et `captureLimit`, comme l'adaptateur Python ; `metadata: { failproofai_sdk_session_id }` sur un appel sélectionne la session pour cette invocation. + +### Vercel AI SDK + +L'AI SDK exporte des fonctions simples depuis un module ES, et un namespace de module ES est immuable par spécification — il n'y a nulle part où patcher. Il utilise les points d'extension que le SDK lui-même documente : + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — le même objet, le nouveau nom +}); +``` + +C'est l'intégration complète : un span d'agent, une paire requête/réponse de modèle par étape avec le nombre de tokens, et chaque appel d'outil. Un seul site d'appel fonctionne sur chaque version majeure — `ai` 4–6 lit le tracer qu'il porte, `ai` 7 l'intégration de telemetry. + +`instrument("ai")` fait la même chose à l'échelle du processus **sur `ai` 7** : chaque appel, via la liste d'intégrations de télémétrie globale de l'AI SDK, qui est additive et ne prend rien à personne d'autre. + +**Sur `ai` 4–6, `instrument("ai")` n'enregistre rien par lui-même et affiche un avertissement.** Le seul hook à l'échelle du processus que ces versions majeures ont est le fournisseur de tracer OpenTelemetry global — un seul slot qu'OpenTelemetry refuse de céder une fois pris. Enregistrer le nôtre refuserait silencieusement votre propre `NodeSDK.start()` plus tard au démarrage et enverrait vos spans http/base de données à un tracer qui n'exporte rien. Utilisez `telemetry()` au site d'appel ou `wrapModel` à cet endroit. Si le processus ne fait tourner aucun OpenTelemetry propre, optez-en avec `instrument("ai", { registerGlobalTracer: true })` : il enregistre alors chaque appel qui passe `experimental_telemetry: { isEnabled: true }`, et ne prend le slot que s'il est encore libre. `registerGlobalTracer: false` conserve le comportement par défaut et silence l'avertissement. + +Si vous préférez envelopper le modèle une fois, `wrapModel` ne voit que les appels de modèle, car les appels d'outil se produisent au-dessus de la couche modèle. Un modèle enveloppé appelé sans rien autour est enregistré comme sa propre exécution. Un appel streamé se ferme selon la façon dont le stream s'arrête — `stop_reason: "cancelled"` quand le consommateur l'annule, `"error"` avec l'erreur quand il échoue à mi-chemin : + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Utiliser les deux est correct : le middleware remarque que l'appel est déjà enregistré et se déporte, donc chaque appel est enregistré une fois. + +`functionId` nomme le span de l'agent. Gardez-le à faible cardinalité — il atterrit dans `agent_id`, la facette principale du tableau de bord. + +### Next.js + +`next build` bundle les dépendances de votre serveur par défaut, et un framework bundlé dans le build est une copie qu'`instrument()` ne peut pas atteindre. Enveloppez la config une fois et appelez `instrument()` depuis le hook de démarrage de Next : + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` ajoute LangChain, Mastra, LlamaIndex et le SDK lui-même à `serverExternalPackages`, en conservant votre propre liste. Sans lui, `instrument()` avertit une fois par framework qu'il ne peut pas atteindre plutôt que d'échouer silencieusement ; si vous listez vous-même les packages, définissez `FAILPROOFAI_NEXT_EXTERNALS=1`. Le Vercel AI SDK et les helpers au site d'appel fonctionnent dans les deux cas. Une route Edge reçoit un build no-op : importer le SDK est sûr et n'enregistre rien. + +### Comptage de tokens sur les appels streamés + +Les API compatibles OpenAI ne rapportent l'utilisation sur un stream que lorsque le client le demande. LangChain et le Vercel AI SDK le demandent ; pour LlamaIndex passez `additionalChatOptions: { stream_options: { include_usage: true } }` à son LLM `OpenAI`, et pour Mastra construisez le modèle avec l'utilisation activée (par exemple `createOpenAICompatible({ includeUsage: true })`). Sinon, les appels de modèle streamés ne portent pas le nombre de tokens. + +### Environnements d'exécution + +Node ≥ 20.9, Bun et Deno — chaque framework, en tant que module ES et en CommonJS, est testé sur chacun par rapport à la trace de Node. Le SDK s'exécute aux côtés du daemon `failproofaid`, qui expédie ce qu'il écrit. + +## Votre propre agent — sans framework + +Pour une boucle d'agent que vous avez écrite vous-même, ou un framework sans adaptateur. Vous émettez les événements avec la même API qu'utilisent les adaptateurs en dessous, donc la trace a la même forme et la même qualité. + +Vous n'avez pas besoin de savoir comment l'agent est organisé. Tout agent fait à la main a déjà trois endroits, quelles que soient les fonctions appelées, et ces trois constituent toute l'intégration : + +| Où | Quoi ajouter | Émet | +| --- | --- | --- | +| Là où **une exécution** commence et se termine | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| La **fonction unique qui appelle le modèle** | `event.modelRequest` avant, `event.modelResponse` après — les deux moitiés, même en cas d'échec | une paire par tour de modèle | +| La **fonction unique qui exécute les outils** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +L'identité est ambiante : tout ce qui se trouve à l'intérieur d'`agent()` atterrit sur la session de cette exécution sans prendre d'identifiant, et rien d'autre dans le programme ne change — y compris ce que l'agent écrit déjà dans sa propre base de données. + +- **Un service ou un worker :** passez votre propre identifiant de requête ou de job comme `sessionId`, pour qu'une session dans le tableau de bord et l'enregistrement dans vos propres logs ou base de données soient la même chaîne. +- **Sous-agents :** imbriquez les appels `agent()`. Le plus intérieur rejoint la session avec l'extérieur comme `parent_id`. +- **Émettez les paires.** Un `modelRequest` sans `modelResponse` est un span que le tableau de bord affiche comme en cours pour toujours — d'où le `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) dans le dépôt est la version complète et exécutable : une vraie boucle d'outils OpenAI instrumentée exactement comme ici, exécutée en CI à chaque changement en tant que module ES et en CommonJS. + +## Évaluations + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Consultez la [référence du SDK Evaluator](/fr/reference/evaluator-sdk) pour le protocole, les paramètres du worker et les types de résultats. + + + **Une évaluation doit céder le contrôle.** Une fonction synchrone qui ne retourne jamais bloque l'unique thread de Node, et aucun timeout ne peut se déclencher pendant ce temps. Écrivez des évaluations `async`. + + +## Ce qu'il ne fera pas à votre processus + +| | | +| --- | --- | +| **Bloquer votre boucle d'agent** | Les événements vont dans une file en mémoire ; un timer les écrit. Le timer est `unref`'d, donc importer ce package n'empêche jamais un script de se terminer. | +| **Croître sans limite** | La file est plafonnée par le nombre *et* par les octets mesurés. Au-delà de l'un ou l'autre, les événements les plus anciens sont supprimés et un avertissement le signale — une panne de télémétrie ne doit pas devenir un kill OOM. | +| **Faire tomber le processus** | Un événement non encodable est supprimé seul, pas le lot autour de lui. Un getter qui lève une exception, une référence circulaire, un `BigInt`, un surrogate isolé : chacun est géré plutôt que propagé. | +| **Laisser un lot à moitié écrit** | Le contenu est `fsync`é avant un renommage atomique, le répertoire est `fsync`é après, et un échec d'écriture nettoie son fichier temporaire. | +| **Laisser les transcriptions lisibles** | Les lots sont en `0600` dans un répertoire `0700`. Ils portent des objectifs, des prompts, des arguments d'outils et leurs sorties. | +| **Expédier des identifiants** | Les clés API, les tokens, les JWT, les en-têtes bearer et les affectations ayant l'apparence de secrets sont expurgés avant que les octets atteignent le disque. Le daemon expurge à nouveau avant l'envoi. | \ No newline at end of file diff --git a/docs/fr/reference/custom-agents.mdx b/docs/fr/reference/custom-agents.mdx index f1ddb70e4..2d280356b 100644 --- a/docs/fr/reference/custom-agents.mdx +++ b/docs/fr/reference/custom-agents.mdx @@ -15,7 +15,7 @@ Ce que font chaque paramètre, méthode et champ. Si vous instrumentez pour la p -Python 3.10 ou supérieur. Aucune dépendance d'exécution. +Python 3.11 ou supérieur. Aucune dépendance d'exécution. ## Installation diff --git a/docs/fr/reference/jev-cloud.mdx b/docs/fr/reference/jev-cloud.mdx new file mode 100644 index 000000000..7e7839a6a --- /dev/null +++ b/docs/fr/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev via FailproofAI Cloud" +description: "Clés machine cloud, état de connexion, limites et comportement en cas d'erreur pour la revue en direct des politiques Jev." +icon: "cloud" +--- + +Voici la référence de la route Cloud pour les [politiques Jev](/fr/policies/jev). Jev, le classificateur de TypeSafe, analyse chaque appel d'outil par rapport à ce que vous avez réellement demandé et répond en complément de vos politiques, jamais à leur place. Via **FailproofAI Cloud**, une machine connectée utilise Jev avec la même clé qu'elle emploie déjà pour se connecter : pas de compte TypeSafe, pas de seconde clé, pas d'endpoint à configurer. Chaque appel est débité sur l'enveloppe du plan existant de votre organisation. + +Tout ce que fait Jev reste identique à la [configuration avec votre propre clé](/fr/reference/jev-providers) : les politiques strictes restent définitives, le refus d'une politique révisable n'est levé que si Jev a été interrogé précisément sur cette préoccupation, et tout échec revient au résultat du regex pour cet appel. + + +Nécessite **failproofai 1.0.8-beta.0** ou une version ultérieure. La version 1.0.7 ne dispose pas de Jev, même si elle apparaît au-dessus des versions 1.0.7 bêta dans le tri. Sans configuration Jev, rien ne change : les hooks exécutent les politiques regex exactement comme ils l'ont toujours fait. + + +## Avant de commencer + +Installez Failproof AI sur la machine où tourne votre agent et rattachez ses hooks à un [harnais pris en charge](/fr/reference/harnesses). Si vous partez de zéro, suivez le [guide de démarrage rapide](/fr/start/quickstart) jusqu'à l'installation des hooks. Vérifiez la version de la CLI installée avec `failproofai --version` ; mettez-la à jour si elle est antérieure à Jev. Vous avez également besoin d'accéder à la page **Administration → Clés** de votre organisation pour créer une clé machine. + +Jev examine les appels d'outils nommés à la porte `PreToolUse` ou `PermissionRequest`. Il n'examine pas chaque événement d'une session. Pour voir Jev lever un refus de politique, vous avez besoin d'une politique installée marquée comme [révisable](/fr/policies/authority) ; tous les autres refus de politique restent définitifs. + +## Activation + +1. **Créez une clé avec Jev.** Dans le tableau de bord FailproofAI Cloud, ouvrez **Administration → Clés → Créer une clé** et choisissez le préréglage **machine**. Celui-ci accorde les trois permissions dont une machine a besoin : `events:add` (envoi de l'activité), `policies:pull` (réception des politiques) et `jev:evaluate` (Jev, débité sur le plan de votre organisation). Une clé ne peut pas porter `jev:evaluate` sans les deux autres. +2. **Connectez la machine** avec cette clé. Lisez son secret à usage unique à l'invite, puis exécutez la commande de configuration complète : + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` installe le démon, rattache les hooks pour les CLI d'agents qu'il trouve et connecte la machine. La variable d'environnement évite que la clé n'apparaisse dans les arguments de la commande et dans l'historique de votre shell. Si votre harnais a été installé ultérieurement, [rattachez-le explicitement](/fr/start/quickstart). + + Si votre organisation exploite sa propre instance FailproofAI Cloud plutôt que la version hébergée, ajoutez son adresse : `--url https://` (ou exportez `FAILPROOFAI_CLOUD_URL`). Sans cela, la clé est vérifiée contre le service hébergé et la connexion échoue. Si le certificat de cet hôte provient d'une CA privée, installez cette CA dans le magasin de confiance système de la machine (par exemple avec `update-ca-certificates`), et pas uniquement dans `NODE_EXTRA_CA_CERTS` : le démon qui envoie les événements et récupère les politiques lit le magasin système. Consultez la section [Résolution des problèmes](/fr/reference/troubleshooting). + +C'est tout. La connexion stocke la clé et, lorsque la machine ne dispose **pas encore** de configuration Jev, en crée une pour FailproofAI Cloud. Dès le premier déploiement de la machine (en moins de 30 s environ), FailproofAI Cloud définit le mode : `enforce` lorsqu'une politique Jev lui est déployée, `off` dans le cas contraire (voir [Qui définit le mode](#who-sets-the-mode)). La sortie l'indique : + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Les vérifications déployées par FailproofAI Cloud s'exécutent sur Cloud. Pour ajouter vos propres vérifications sur la machine, installez un pack : + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**Avec `--no-transcripts`, la connexion n'active pas Jev.** Jev envoie chaque appel d'outil vérifié ainsi que l'invite récente à FailproofAI Cloud, ce qui représente plus qu'une connexion en mode décisions uniquement sollicitée pour envoyer. La clé est quand même stockée, et la sortie indique que Jev est disponible et comment l'activer : + +```bash +failproofai jev setup --provider failproofai +``` + +Cela désactive également Jev via FailproofAI Cloud. Un `jev.json` qui exécute Jev via FailproofAI Cloud (laissé par une connexion antérieure avec les transcriptions activées) est supprimé, selon la même règle utilisée par `config --disconnect`, et la sortie indique que Jev via FailproofAI Cloud reste désactivé sur cette machine. Un `jev.json` pointant vers votre propre endpoint Jev est conservé tel quel, tout comme un `jev.json` FailproofAI Cloud que vous avez désactivé (`--mode off`). + + +La connexion **n'écrase jamais** un `~/.failproofai/jev.json` existant. Si vous utilisez déjà votre propre endpoint Jev, il continue d'être utilisé, et la sortie indique que le fichier a été laissé tel que configuré — et, lorsque ce fichier laisse Jev désactivé (refusé ou désactivé manuellement), l'indique et explique comment y remédier. Pour faire basculer cette machine vers FailproofAI Cloud, exécutez `failproofai jev setup --provider failproofai`. + + +## Qui définit le mode + +Sur une machine connectée à FailproofAI Cloud, **c'est FailproofAI Cloud qui définit le mode Jev** ; rien sur la machine ne le fait : + +- `enforce` tant qu'une politique Jev (ou regex + Jev) est déployée sur la machine : chaque appel d'outil vérifié provenant d'un agent ciblé par l'une de ces politiques est envoyé à FailproofAI Cloud, qui soumet ses vérifications conjointement avec celles des packs qui y sont installés. Un appel provenant d'un agent qu'aucune politique Jev Cloud ne cible, et sans vérification de pack propre, n'est pas envoyé du tout. En mode `enforce`, les vérifications de refus propres à Jev bloquent les appels en plus de lever les verdicts regex qu'elles examinent. +- `off` lorsqu'aucune politique n'est déployée : pas de Jev du tout, quoi qu'indique `jev.json`. + +Pour tester une politique Jev avant qu'elle ne prenne effet, déployez-la avec l'effet **observe** : ses vérifications sont toujours sollicitées, et ce qu'elles auraient fait est enregistré comme **would-have** sur la page de la politique, mais elle ne bloque jamais un appel et n'en lève jamais aucun. `failproofai jev setup --mode` et le commutateur **Paramètres → Jev** du tableau de bord indiquent que le mode est géré par FailproofAI Cloud et ne modifient rien. `jev.json` n'est pas utilisé pour les vérifications Cloud, même s'il désigne un autre fournisseur. `failproofai config --disconnect` restitue Jev au `jev.json` propre à la machine. + +`failproofai jev status` indique alors `Jev checks run on FailproofAI Cloud (mode: enforce)`. Il liste également les vérifications qui examinent chaque politique `both`. La page de flotte explique pourquoi une machine avec un mode ne peut pas interroger : + +- `transcripts_disabled` : la machine a été connectée avec `--no-transcripts`, ce qui n'active jamais Jev. +- `jev_unconfigured` : la clé de la machine ne porte pas `jev:evaluate`. +- `jev_rate_limited` : FailproofAI Cloud a refusé certains appels de la machine en raison de la limite de débit Jev de l'organisation, et ces appels ont été décidés par les politiques regex seules. +- `jev_unavailable` : plusieurs appels consécutifs ont échoué, la machine suspend donc les appels à Jev de FailproofAI Cloud pendant une minute à la fois. Elle réessaie d'elle-même. + +Si FailproofAI Cloud ne répond pas dans les 5 secondes, les politiques regex décident seules, comme pour toute panne de Jev. Après 3 échecs consécutifs, la machine cesse d'interroger pendant une minute à la fois, afin qu'une panne Cloud ne ralentisse pas chaque appel d'outil. + +Une pause de session (`failproofai config --pause`) n'arrête pas les vérifications Jev de FailproofAI Cloud, tout comme elle n'arrête pas les politiques gérées par Cloud. Elle met en pause les vérifications Jev des packs installés sur la machine. + +## Vérifier son fonctionnement + +```bash +failproofai jev status +failproofai jev test +``` + +`status` affiche le fournisseur en tant que **FailproofAI Cloud**, l'hôte Cloud auquel la machine est connectée, le mode, et la source de la clé comme **connexion FailproofAI Cloud**, jamais la clé elle-même. Lorsqu'un `jev.json` FailproofAI Cloud est en place mais que Jev ne peut pas s'exécuter, il en indique la raison : + +| `status` indique | `status --json` | Signification | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | La machine est connectée, mais aucune clé Jev n'y est stockée : la clé ne porte pas `jev:evaluate`, ou la connexion n'a pas pu le confirmer. Exécutez à nouveau `failproofai config` avec la clé dans `FAILPROOFAI_CLOUD_TOKEN` ; si elle manque de la permission, utilisez une clé **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Il n'y a pas de connexion FailproofAI Cloud sur cette machine à laquelle la clé Jev pourrait appartenir. | + +Après `failproofai config --disconnect`, il n'y a plus de `jev.json` FailproofAI Cloud (sauf s'il a été désactivé, auquel cas il est conservé), donc `status` indique simplement que Jev est désactivé. `status --json` porte les mêmes informations (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), même en l'absence de configuration ou en cas de refus. `permissions` correspond toujours à celui de `jev.json` ; un refus concernant `credentials.json` ajoute `credentialsPermissions`, ainsi que `fix` lorsqu'une seule commande permet de corriger le problème. `test` envoie une requête en direct et rapporte sa latence ainsi que la version Jev qui a répondu. Il retourne le code 1, et l'indique dans son titre, lorsque la réponse arrive après le délai d'expiration du hook (les hooks enregistreraient `timeout`) ou répond incorrectement à sa question de vérification. + +Le panneau **Paramètres → Jev** du tableau de bord affiche également la **connexion FailproofAI Cloud** : l'organisation dans laquelle la machine est enregistrée et si sa clé porte Jev. Ces informations sont lues depuis les fichiers propres à la machine, sans appel réseau. + +## Vérifier un vrai appel + +Démarrez une nouvelle session dans l'agent hooké. Demandez-lui d'utiliser son outil de lecture de fichiers sur `README.md` et d'en rapporter le titre. Confirmez que la session contient cet appel d'outil, puis exécutez à nouveau `failproofai jev status` : son compteur d'appels évalués récemment devrait augmenter. Ouvrez **Politiques → Activité** dans le [tableau de bord local](/fr/reference/local-dashboard#review-policy-activity) pour inspecter le verdict Jev et le mode de cet appel. Dans Cloud, la page **Politiques** de l'organisation affiche les résultats Jev pour l'activité transmise. En mode observe, le verdict est enregistré comme **would-have** et le résultat de la politique décide quand même de l'appel. Une levée n'apparaît que lorsqu'une politique révisable a correspondu et que Jev a levé ses vérifications nommées. + +## Ce qui apparaît sur la page des politiques + +La machine envoie déjà son activité de hook à FailproofAI Cloud (`events:add`). Avec Jev activé, l'enregistrement de chaque appel passé à la porte indique également quel évaluateur a été utilisé, ce que Jev a décidé, quelles politiques il a levées, pourquoi il a effectué un repli le cas échéant, sa latence et le modèle qui a répondu — des décisions, des codes et des noms, jamais la commande ni votre invite. Sur la page **Politiques** de votre organisation : + +- un appel décidé par le propre verdict de Jev (mode enforce) est attribué à **Jev**, et lorsque la vérification décisive provient d'un pack, l'enregistrement mentionne également ce pack et sa version ; +- en mode observe, le refus ou l'avertissement de Jev apparaît comme **would-have**, à côté des déploiements que vous observez ; +- les politiques que Jev a levées, ou aurait levées en mode observe, sont comptabilisées par politique ; +- une décision à laquelle Jev a participé (un blocage, un avertissement, une levée, ou un would-have en mode observe) liste chaque vérification qu'il a sollicitée et ce qu'elle a conclu : verdict, raison (`not-detected`, `exempt`, `fired`, `op-requested`, …), sa preuve `p`, la réponse `exempt` et la réponse de chaque sonde. Une vérification d'une politique déployée en surveillance (observe) est également listée, marquée comme surveillée ; elle ne bloque jamais. Jev répond avec des probabilités, pas de la prose, il n'y a donc pas de raison en texte libre. Les autorisations simples se regroupent en compteurs et ne portent pas cette liste. + +## Quand Jev ne peut pas répondre + +Chacun de ces cas revient au résultat de vos politiques pour cet appel, et est enregistré avec sa raison : + +| Raison | Cause | +| --- | --- | +| `out-of-credits` | Votre organisation a épuisé son enveloppe de plan. | +| `http-401`, `http-403` | La clé a été révoquée, ou ne porte pas `jev:evaluate`. Reconnectez-vous avec une clé qui le fait. | +| `http-429` | FailproofAI Cloud applique une limitation de débit Jev pour votre organisation. Tant que le délai d'attente demandé n'est pas écoulé (son `Retry-After`, au maximum 60 secondes), la machine n'envoie rien et chaque appel est immédiatement renvoyé en repli. Les appels retenus de cette façon sont enregistrés comme `http-429`, ou comme `rate-limited` lorsque la limite de débit propre à la machine les retient en premier. | +| `http-429` (limite journalière) | Votre organisation a consommé ses appels Jev journaliers : **10 000 par jour UTC**, sauf si l'opérateur de votre FailproofAI Cloud a défini une autre limite. Chaque appel est renvoyé en repli jusqu'à la réinitialisation du compteur à 00:00 UTC ; la machine réinterroge au moins une fois par minute, donc elle capte la réinitialisation en moins d'une minute. `failproofai jev test` indique « Daily Jev limit for this org reached; resets at 00:00 UTC. » | +| `http-422` | Jev a refusé la requête de cet appel, généralement parce que l'appel d'outil contenait du texte dense (base64, hexadécimal, code minifié) dépassant le budget de tokens de Jev. Cet appel est toujours renvoyé en repli ; ce n'est pas une panne. | +| `http-502` | Jev est actuellement indisponible. | +| `http-503` | Ce Cloud ne peut pas servir Jev pour votre organisation : pas de passerelle de modèle, une organisation pas encore provisionnée, ou la passerelle est hors service. Contactez votre administrateur ; les hooks réinterrogent au plus une fois par minute. | +| `http-404` | Ce FailproofAI Cloud ne sert pas encore Jev. | +| `timeout` | Aucune réponse dans `timeoutMs` (3000 par défaut). Pendant que FailproofAI Cloud définit le mode Jev de la machine, l'attente est de 5000 ms et le `timeoutMs` de `jev.json` n'est pas utilisé. | +| `model-mismatch` | Une version de Jev autre que 1.13 a répondu. | + +## Où vit la clé et où elle va + +- La clé est stockée une seule fois, dans `~/.failproofai/credentials.json` (`0600`, dans un répertoire réservé au propriétaire), aux côtés des autres identifiants FailproofAI Cloud. `jev.json` ne contient pas de clé pour cette route ; en écrire une rend la configuration invalide. +- Si `credentials.json` porte **quelque** permission que ce soit pour quelqu'un d'autre que vous (groupe ou autre, lecture ou écriture), ou si son répertoire peut être **écrit** par quelqu'un d'autre que vous, il est **refusé**, non lu, et Jev reste désactivé jusqu'à ce que vous y remédiiez : `chmod 600` sur le fichier, `chmod 700` sur le répertoire (ou reconnectez-vous, ce qui réécrit le fichier à `0600` et rend le répertoire réservé au propriétaire). Un répertoire que d'autres peuvent seulement lire est acceptable ; un répertoire qu'ils peuvent écrire leur permet de remplacer le fichier. +- La clé n'est valide que tant que la connexion dont elle provient est présente sur la machine : un identifiant de politique ou de rapport pour le même FailproofAI Cloud **avec la même clé**, dans le même fichier. Une clé Jev laissée sans l'une d'elles est ignorée, et Jev reste désactivé. Cela se produit lorsque le `config --disconnect` d'une ancienne version de failproofai laisse la clé Jev en place (elle ne sait pas qu'il faut la supprimer), ou lorsque le `config --token` d'une ancienne version se connecte avec une autre clé, qui sur FailproofAI Cloud peut appartenir à une autre organisation. Pour réactiver Jev, reconnectez-vous avec une clé **machine**. +- La clé n'est jamais envoyée qu'à l'origine Cloud contre laquelle elle a été vérifiée. Un `jev.json` pointant ailleurs est refusé. +- **Un agent sur la machine peut la lire.** `credentials.json` est réservé au propriétaire, et l'agent s'exécute en tant que ce propriétaire. La lecture des fichiers propres à failproofai est intentionnellement autorisée (seule leur modification est bloquée, par `block-failproofai-commands`), donc la seule chose qui s'interpose entre un agent et ce fichier est `block-read-outside-cwd` — une politique *révisable* — et depuis une session démarrée dans votre répertoire personnel, rien. Une clé avec `jev:evaluate` dépense l'enveloppe Jev de votre organisation (jusqu'au plafond journalier) depuis n'importe où où elle est utilisée, donc traitez une clé machine comme tout autre identifiant de dépense : si un agent a pu la lire, désactivez-la sur la page des Clés et reconnectez-vous avec une nouvelle. +- Seuls vos fichiers globaux régissent ceci. Un dépôt ne peut pas activer Cloud Jev, le pointer ailleurs ou fournir sa clé, et `FAILPROOFAI_JEV_API_KEY` est ignoré pour cette route. +- Pour chaque appel que Jev évalue, une requête est envoyée à FailproofAI Cloud, portant ce que la [page bring-your-own-key](/fr/reference/jev-providers#what-leaves-the-machine) liste (secrets expurgés). FailproofAI Cloud la transmet à TypeSafe et ne la journalise ni ne la conserve. + +## Désactivation + +Sur une machine connectée, Jev est désactivé lorsque FailproofAI Cloud ne lui déploie aucune politique Jev : supprimez ou archivez les politiques Jev correspondantes. + +| Commande | Résultat | +| --- | --- | +| Supprimer les politiques Jev de la machine dans FailproofAI Cloud | Le mode de Cloud devient `off` lors du prochain sondage (environ 30 s) : plus de Jev du tout, quoi qu'indique `jev.json`. | +| `failproofai config --disconnect` | Déconnecter la machine : la clé est supprimée, ainsi que `jev.json` lorsqu'il désigne FailproofAI Cloud et n'est pas désactivé. Un `jev.json` pour votre propre endpoint est conservé. | + +Dès l'appel d'outil suivant, les hooks exécutent les politiques regex exactement comme auparavant. \ No newline at end of file diff --git a/docs/fr/reference/jev-evaluations.mdx b/docs/fr/reference/jev-evaluations.mdx new file mode 100644 index 000000000..0803c3652 --- /dev/null +++ b/docs/fr/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Référence d'évaluation Jev" +description: "Types de questions, scores calibrés, limites et remplissage rétroactif pour les évaluations de sessions Jev." +icon: "list-checks" +--- + +Cette page décrit les formes de questions et les règles de notation qui sous-tendent les [évaluations Jev](/fr/evaluations/jev). Certaines questions nécessitent qu'un modèle *lise* la conversation, mais pas qu'il *écrive* à son sujet. « Le client a-t-il exprimé de l'urgence ? » n'a que deux réponses. « À quel point était-il frustré ? » en a quelques-unes, dans un ordre précis. Vous connaissez toutes les réponses avant même de poser la question. + +Une **évaluation par classifieur** est faite exactement pour ces cas-là. Vous rédigez la question et les réponses possibles, et un petit modèle dédié à la classification renvoie un nombre calibré — jamais du texte libre. + + +Comme un juge, une évaluation par classifieur coûte un appel de modèle par session. Contrairement à un juge, il s'agit d'un modèle petit et dédié à une seule tâche plutôt que d'un modèle généraliste, ce qui le rend plus rapide et moins coûteux — mais il ne s'expliquera jamais. Si vous avez besoin du raisonnement, utilisez un [juge](/fr/evaluations/judge). + + +## Lequel choisir ? + +| Question | Utilisation | +| --- | --- | +| Combien d'appels d'outils y a-t-il eu ? | code | +| La session a-t-elle duré moins de 30 secondes ? | code | +| Le client a-t-il exprimé de l'urgence ? | **classifieur** | +| Quelle équipe doit traiter ceci : facturation, technique ou commercial ? | **classifieur** | +| À quel point le client était-il frustré ? | **classifieur** | +| La réponse était-elle vraiment correcte ? | **juge** | +| A-t-il respecté notre politique d'escalade, et pourquoi le pensez-vous ? | **juge** | + +La règle générale : **quantifiable → code, réponses listables → classifieur, nécessite une explication → juge.** + +Vous n'avez pas à décider à l'avance. Décrivez ce que vous souhaitez mesurer et l'assistant choisit, vous indique ce qu'il a choisi et pourquoi, et vous pouvez en changer. + +## Les deux types de questions + +### `noul` — est-ce vrai ? + +Deux réponses, et vous décrivez les deux. Le résultat est la probabilité que la description « vraie » corresponde : + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Décrivez les deux côtés. « Aucune urgence exprimée » est une vraie réponse, et la formuler explicitement rend l'autre plus précise. + +### `score` — dans quelle mesure ? + +Un barème ordonné, **du pire au meilleur**. Le résultat indique où la session se situe, remis à l'échelle de 0 à 1 : + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Un barème comporte trois à cinq niveaux, tous distincts.** Les deux limites sont mesurées, pas stylistiques : + +- **Deux niveaux** se ramènent à ce que `noul` fait déjà mieux, et **plus de cinq** pousse le modèle à se réfugier vers le milieu au lieu de trancher. La même question sur la même session a donné un score de 0,00 avec deux niveaux, 0,01 avec trois, et 0,55 avec dix. +- **Des niveaux répétés** répartissent arbitrairement la réponse entre eux. Une session manifestement en colère a obtenu 1,00 avec `["Calm", "Frustrated", "Very angry"]` et 0,66 avec `["Angry", "Angry", "Angry"]` — un nombre bien formé qui ne signifie rien. + +Les catégories sans ordre — « facturation, technique ou commercial » — ne constituent pas un barème. Posez-les comme une question `noul` par catégorie, ou utilisez un juge. + +## Lire les résultats + +Un classifieur produit un **score** de 0 à 1, exactement comme un juge ; il s'affiche donc dans les graphiques, les filtres et les alertes de la même manière. Deux différences méritent d'être notées : + +- **Il n'y a pas de raisonnement.** Le champ est délibérément vide. Ce modèle ne s'explique pas, et inventer une explication serait une fabrication plutôt qu'une fonctionnalité. +- **L'incertitude est signalée.** Une question `score` indique son propre niveau de confiance, et un résultat sur lequel le modèle était incertain est marqué `low_confidence` — ainsi, « lesquels méritent l'attention d'un humain » est une question de filtre, pas de conjecture. Une question `noul` ne rapporte pas de niveau de confiance et n'est donc jamais marquée. + +Les sessions très longues sont lues par extraits puis combinées. Lorsqu'une session est trop longue pour être lue en entier, le résultat indique combien de tours ont été omis — vous ne verrez jamais un jugement rendu sur une partie d'une session présenté comme s'il avait été rendu sur la totalité. + +## Limites + +- **Trois à cinq niveaux de barème, tous distincts.** Voir ci-dessus ; les deux limites sont appliquées au moment de la création. +- **Une question par évaluation.** Posez deux choses et vous obtenez deux évaluations, ce qui est d'ailleurs ce que vous souhaitez dans un graphique. +- **Modifier la question publie une nouvelle version.** Les anciens et les nouveaux scores ne sont pas comparables, ils sont donc conservés séparément plutôt que mélangés en une seule tendance. +- **Un classifieur produit toujours un score**, jamais une métrique ni une assertion. +- **Pas de raisonnement**, comme indiqué ci-dessus. Si un nombre amènera quelqu'un à demander « pourquoi ? », rédigez plutôt un juge. + +## Tests et remplissage rétroactif + +Contrairement à un juge, une évaluation par classifieur **peut** être testée avant déploiement — [testez-la](/fr/evaluations/test) sur de vraies sessions de la même manière qu'une évaluation par code, et consultez les scores avant toute mise en production. + +Elle peut également être [appliquée rétroactivement](/fr/evaluations/deploy#score-sessions-you-already-have) sur des sessions déjà enregistrées. Cela coûte un appel de modèle par session, alors délimitez la fenêtre délibérément plutôt que de tout rejouer. \ No newline at end of file diff --git a/docs/fr/reference/jev-intent.mdx b/docs/fr/reference/jev-intent.mdx new file mode 100644 index 000000000..4a33074d7 --- /dev/null +++ b/docs/fr/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Capture d'intention Jev" +description: "Quels événements du harnais informent l'évaluateur Jev de ce que l'humain a demandé, quel champ contient le texte, ce qui n'est jamais comptabilisé, et le risque lié à la confiance accordée à une invite transmise par le harnais." +icon: "message-square-quote" +--- + +Lorsque vous configurez la [révision de politique Jev](/fr/policies/jev), l'évaluateur juge chaque appel d'outil soumis à validation par rapport à **ce que l'humain a demandé**, et non par rapport au texte que le harnais a soumis à l'agent. Une réponse telle que « oui, force-push » peut lever une politique **révisable** — c'est précisément l'intérêt de l'évaluateur, puisqu'une regex qui ne peut pas lire la requête bloque un tiers du travail réel. + +Ce texte provient d'un seul endroit : **l'invite que le harnais lui-même transmet au hook lors de son événement de soumission d'invite**. Failproof AI enregistre la partie saisie par l'humain — l'enrobage du harnais supprimé, les secrets occultés, avec une taille maximale — dans un fichier `0600` sous son propre répertoire d'état. Rien sur le disque n'est consulté : la transcription de session est un fichier que l'agent peut réécrire en une seule commande, donc on ne lui demande jamais qui a écrit une invite. + +## Le risque accepté, clairement énoncé + +Un agent capable d'exécuter des commandes peut amener un harnais à soumettre une invite. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` et `pi -p` déclenchent tous le même événement de soumission d'invite, avec la même charge utile, qu'une personne qui tape, dans une session enfant que cet agent contrôle. L'agent peut également exécuter le binaire hook de Failproof AI lui-même et lui fournir une charge utile qu'il a écrite. Rien dans Failproof AI ne peut distinguer l'un de l'autre de la réalité — les deux sont le même programme lisant le même stdin. + +**Un agent disposant d'un shell peut donc forger son propre consentement.** Il s'agit d'un compromis délibéré, accepté le 2026-09-23, et en voici les deux aspects : + +- **Ce qu'il apporte.** L'alternative a été construite et mesurée : exiger un champ dans lequel le harnais désigne un humain comme auteur de l'invite, et ne rien enregistrer dans le cas contraire. Aucun harnais existant n'envoie un tel champ, donc cette version n'enregistrait **rien, sur tous les harnais** — Jev jugeait chaque appel sans intention déclarée et ne pouvait jamais lever une seule politique. Une capture qui ne se déclenche jamais n'est pas un produit plus sûr, c'est l'absence de produit. +- **Ce qu'il ne peut pas faire.** Une invite enregistrée ne peut lever qu'une politique déjà marquée **révisable**. Une politique **stricte** n'est jamais levée par quoi que ce soit que Jev dise, donc une invite forgée ne peut jamais transformer un blocage strict en autorisation — et contourner le hook ne rapporte rien non plus à un agent : le harnais invoque Failproof AI pour l'appel d'outil indépendamment. +- **Ce qu'il peut faire, dans le pire des cas.** Le pire qu'il puisse faire est de lever l'une des quinze politiques intégrées révisables — et **douze de ces quinze bloquent**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` et les six blocages d'interface CLI d'infrastructure (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) sont des refus, donc un consentement forgé peut transformer un vrai refus en autorisation pour l'impression de secrets d'environnement, la lecture d'un fichier `.env`, la lecture en dehors du projet, `rm -rf`, un force-push, l'écriture d'un fichier de secrets, ou la modification d'une infrastructure en production. Seuls `warn-git-amend`, `warn-destructive-sql` et `warn-global-package-install` sont des avertissements. Une installation par défaut active deux des douze blocages, `protect-env-vars` et `block-env-files` ; les dix autres ne s'appliquent qu'à une machine sur laquelle quelqu'un les a activés. Ce qu'aucune invite n'atteint, c'est tout ce qui est strict — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, le garde-fou qui empêche un agent de désactiver Failproof AI, et toutes les autres politiques intégrées non marquées comme révisables. [L'autorité des politiques](/fr/policies/authority) liste les quinze et ce que chacune est révisée par. + +Ce qui reste refusé, c'est tout ce qui est simple à vérifier et qu'un agent ne peut pas obtenir simplement en demandant : un tour que la charge utile du harnais lui-même marque comme soumis par une machine, une charge utile désignant un sous-agent, un identifiant de session qui n'est pas un nom simple, un événement qui n'est pas l'événement de soumission d'invite, et du texte qui n'est que de l'enrobage de harnais — y compris les mots de blocage de Failproof AI lui-même, que plusieurs harnais renvoient comme prochain tour utilisateur. + +## Tableau par harnais + +« Champ de texte » désigne le champ de charge utile stdin après la normalisation par harnais de Failproof AI. « Enregistré » indique si l'invite est conservée comme requête de l'humain. + +| Harnais | `--cli` | Événement d'invite → canonique | Champ de texte | Enregistré | Dernier message de l'agent lu depuis | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Oui, sauf si le `source` de la charge utile désigne un tour que personne n'a soumis (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, une valeur inconnue et un build qui n'envoie pas de `source` du tout sont tous enregistrés | la transcription de session (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Oui | le JSONL de déploiement (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Oui | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Oui, avec le wrapper `` supprimé quand il constitue toute l'invite | le JSONL de transcription de l'agent | +| OpenCode | `opencode` | `message.updated` (rôle utilisateur) → `UserPromptSubmit` | `prompt` | Oui — mais l'OpenCode actuel ne transporte aucun texte dans cet événement, donc en pratique rien n'est enregistré ; une répétition du même message est enregistrée une seule fois | aucun (les sessions sont en SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Oui, sauf si `input_source` vaut `extension` — le `sendUserMessage()` d'une autre extension, dont le texte peut être écrit par le modèle ou dérivé du dépôt | le JSONL de session Pi | +| Hermes | `hermes` | aucun | — | Non — Hermes n'a pas d'événement de soumission d'invite | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Oui, sauf si les métadonnées d'exécution marquent l'exécution comme celle d'une machine : un `trigger` autre que `user`, un `inputProvenance.kind` autre que `external_user`, ou `senderIsOwner: false` | aucun (`before_agent_run` ne transporte aucun chemin de transcription) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Oui | le JSONL de session droid | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Oui | aucun (les sessions sont en SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | aucun | Non — `PreInvocation` se déclenche avant *chaque* appel de modèle dans un tour et ne transporte aucun texte d'invite | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Oui | aucun (les sessions sont en SQLite) | + +Deux harnais n'enregistrent rien, et pour la même raison dans les deux cas : leur événement ne fournit aucun texte humain. Hermes n'a pas d'événement de soumission d'invite — son plugin natif gère `pre_llm_call` lui-même et ne transmet que les événements d'outil, de session et de sous-agent. Le `PreInvocation` d'Antigravity se déclenche avant chaque appel de modèle, sur un tour humain et sur les cinq qui suivent, et ne transporte aucun champ d'invite ; les hooks peuvent également injecter des étapes `userMessage` dans la même conversation. Il n'y a rien dans l'un ou l'autre événement à enregistrer. + +## Ce qui fait d'une invite celle de l'humain + +1. **L'événement.** Failproof AI a été invoqué pour l'événement de soumission d'invite du harnais, que le gestionnaire canonicalise en `UserPromptSubmit`. +2. **La charge utile.** Le harnais l'écrit sur le stdin du hook, et elle transporte le texte dans le champ nommé ci-dessus. Un appel qui atteint Failproof AI sans la charge utile n'enregistre rien. +3. **Rien dans la charge utile n'exclut le tour.** Une charge utile qui désigne un sous-agent (`agent_id`) correspond à l'agent qui se sollicite lui-même. Un `source`, `input_source` ou marqueur d'exécution OpenClaw qui désigne un tour soumis par une machine est refusé. Un marqueur **absent** n'exclut rien — c'est la différence avec la version qui n'enregistrait rien, puisque chaque marqueur ici est absent sur chaque build existant. +4. **Il reste quelque chose après la suppression de l'enrobage** (voir ci-dessous). + +**La transcription de session ne constitue pas une preuve de qui a écrit une invite.** Les versions précédentes de cette page décrivaient une vérification croisée avec la transcription : l'invite était refusée si la transcription montrait que le modèle l'avait planifiée, et la transcription devait prolonger celle que l'invite précédente avait vue. Cette vérification a été supprimée. Une transcription est un fichier sur lequel l'agent dispose déjà d'un accès shell — elle peut être tronquée, remplacée, complétée au-delà du budget de lecture, capturée au début d'un tour et restaurée à la fin, ou rendue lisible à nouveau avec des entrées que l'agent a écrites. Chaque cycle de durcissement était suivi d'une autre variante de la même falsification, donc le mécanisme entier a été supprimé plutôt que réparé. + +La transcription est encore lue pour une chose : **le dernier message visible de l'agent**. Ce message est écrit par l'agent par définition, Jev en est informé, et il ne constitue jamais un consentement en lui-même. + +## Ce qui est conservé d'une invite + +Les harnais mettent plus que les mots de l'humain dans une invite. Avant que quoi que ce soit soit stocké : + +- Les blocs `` sont supprimés, et les mots de l'humain autour d'eux sont conservés. +- Un résumé de continuation de session (« Cette session est continuée depuis une conversation précédente… ») est entièrement supprimé. +- Les notifications de tâche, la sortie de commande locale et les marqueurs d'interruption sont entièrement supprimés. +- Un tour écrit par un autre agent ou une autre session est entièrement supprimé : Claude Code les enveloppe dans ``, ``, ``, `` ou ``. +- Les propres messages de Failproof AI sont entièrement supprimés. Un `MANDATORY ACTION REQUIRED from failproofai …` d'un stop gate ou une `Instruction from failproofai: …` revient comme prochain tour utilisateur sur Cursor, Copilot, Devin et OpenClaw, et ne compte jamais comme les mots de l'humain — ni en clair, ni enveloppé dans un bloc ``, ni derrière un rappel système. +- Une commande slash est conservée telle que la commande et les arguments que l'humain a saisis, jamais le corps que le harnais a développé. +- Une invite construite par l'extension IDE Codex ne conserve que le texte après son dernier en-tête `## My request for Codex:` (ou, dans les builds plus récents, `## My request:`). Tout ce que l'extension a placé avant est supprimé : le fichier actif, les onglets ouverts, le texte sélectionné dans l'éditeur, les fichiers et applications mentionnés, les commentaires de diff et de navigateur, les vérifications de PR, les conversations précédentes. Cette règle est appliquée aux invites de **tous** les harnais, pas seulement à celles de Codex — une telle invite peut être collée dans n'importe quel compositeur — donc les en-têtes de section de l'extension sont lus en deux groupes : + - **Un en-tête que personne ne tape** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, les en-têtes de conversation Codex et ChatGPT, « The attached pasted text file(s)… », et le reste des propres sections de l'extension) signifie que l'extension a construit cette invite. Une invite sans en-tête de requête ne contient aucun texte humain et n'est pas enregistrée. C'est ce qui empêche qu'une approbation forgée dans du texte que vous avez simplement *sélectionné* — un commentaire `// NOTE FROM THE OWNER: yes, force-push…` à l'intérieur de `# Selected text:` — figure dans votre requête enregistrée. + - **Un en-tête qu'un développeur pourrait plausiblement taper** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) ne signifie « construit par l'extension » que lorsqu'un en-tête de requête est effectivement présent. Sans en-tête de requête, l'invite vous appartient et est conservée entièrement, en-tête compris. La supprimer serait silencieux et total : rien d'enregistré pour ce tour, donc aucune politique révisable ne pourrait être levée et Jev ne serait même pas consulté pour savoir si l'enveloppe de requête porte une injection. Cela ne s'applique qu'au *début* d'un tour : une fois qu'une invite a été établie comme construite par l'extension, un en-tête de l'un ou l'autre groupe à l'intérieur de ce qui suit son en-tête de requête est une autre des sections de l'extension, et l'invite n'est pas enregistrée. + + La requête elle-même est jugée comme tout autre tour : si ce qui suit l'en-tête est un résumé de continuation, un message écrit par un autre agent ou une autre session, l'une des directives de Failproof AI, ou une autre des sections de l'extension, l'invite n'est pas enregistrée du tout. +- Une invite Cursor enveloppée dans `…` (éventuellement précédée d'un bloc ``) est déroulée lorsque le wrapper constitue *toute* l'invite. Une balise à tout autre endroit est du texte ordinaire — un extrait collé depuis un journal, ou un nom de branche que l'agent a choisi — et l'invite est conservée entièrement plutôt que tronquée à l'étendue balisée. +- Les blocs collés sont conservés et étiquetés comme collés par l'humain. + +Une invite qui n'est que du texte de harnais n'est pas enregistrée du tout. + +## Le dernier message de l'agent + +Une réponse comme « oui » ne signifie rien sans la question à laquelle elle répond. Lorsqu'une invite est enregistrée, Failproof AI lit également le dernier message visible de l'agent depuis la transcription de session **à ce moment-là**, et le stocke avec l'invite. Jev le reçoit dans son propre champ, étiqueté comme écrit par l'agent : il explique une réponse courte et ne compte jamais comme la requête de l'humain en lui-même. C'est la seule chose pour laquelle la transcription est lue, et le pire qu'une transcription réécrite peut faire est de placer un message que l'agent a écrit là où un message que l'agent a écrit est attendu. + +Il est lu depuis la fin de la transcription, au maximum les 4 derniers Mo. Les formats de transcription pris en charge sont Claude Code, les déploiements Codex (anciens événements `agent_message` et nouveaux éléments `AgentMessage`), Cursor, Copilot `events.jsonl`, et les JSONL de session Pi, Factory et OpenClaw. Les propres messages synthétiques et d'erreur d'API de Claude Code ainsi que les messages de sous-agent (sidechain) sont ignorés. Il n'y a pas de snapshot pour Goose et OpenCode, qui conservent les sessions en SQLite, pour Devin, dont la transcription est un document JSON unique, ni pour OpenClaw, dont l'événement `before_agent_run` ne transporte aucun chemin de transcription. + +## Stockage + +| Propriété | Valeur | +| --- | --- | +| Emplacement | `~/.failproofai/state/semantic/sessions//.json`, où `` est le profil d'agent dans lequel l'invite a été saisie : `.` pour un agent que FailproofAI connaît (l'identité que les politiques Cloud ciblent), ou simplement `` sinon | +| Permissions | fichier `0600`, répertoire `0700`. Chaque répertoire au-dessus de lui, jusqu'à `~/.failproofai`, est soumis à la même règle que le répertoire de `jev.json` : un répertoire que quelqu'un d'autre peut **écrire** peut être renommé et remplacé, donc le chemin de lecture retire ces bits d'écriture là où il peut, et ne **lit rien** là où il ne peut pas. Une invite enregistrée est alors absente plutôt que forgée, et rien n'est levé | +| Conservé par session | les 5 dernières invites ; une invite identique à la précédente la remplace plutôt que de prendre un nouvel emplacement | +| Fenêtre | les invites de plus de 6 heures sont ignorées | +| Taille | chaque invite et message d'agent est plafonné à 6 000 caractères, en conservant le début et la fin | +| Secrets | occultés avec les mêmes motifs que les politiques `sanitize-*` avant tout enregistrement. Un texte de plus de 48 000 caractères est occulté comme ses 28 800 premiers et 19 200 derniers caractères, et le texte adjacent à ces coupures, où un secret pourrait avoir été divisé, n'est jamais stocké | + +Un identifiant de session contenant autre chose que des lettres, des chiffres, `.`, `_` et `-`, ou dépassant 128 caractères, n'est jamais utilisé comme nom de fichier, donc rien n'est enregistré pour lui. + +Un fichier de session n'existe qu'une fois qu'une invite y a été enregistrée. Il contient des invites et rien d'autre — pas d'état d'origine, pas de marque de transcription — et il est supprimé une fois qu'il est resté silencieux plus longtemps que la fenêtre de six heures, la prochaine fois qu'une nouvelle session écrit sa première invite. + +Une invite n'est relue que pour le même profil d'agent et le même identifiant de session sous lesquels elle a été enregistrée. Les identifiants de session proviennent de l'agent, donc deux profils peuvent utiliser le même ; le découpage par profil empêche les mots d'un profil de jamais compter comme la requête d'un autre. Les fichiers antérieurs à cette disposition (`sessions/.json`) ne peuvent pas indiquer quel profil les a écrits, donc ils ne sont jamais lus et expirent avec la fenêtre de six heures. + +Rien n'est enregistré sauf si un point de terminaison Jev est configuré. Sous un mode Jev Cloud FailproofAI, rien n'est enregistré pour un profil d'agent auquel aucune vérification Jev Cloud n'est assignée et qu'aucune vérification de pack installé ne révise. + +### La racine du projet + +« À l'intérieur du projet » — ce contre quoi `read-outside-workspace` et les autres vérifications de chemin jugent — signifie à l'intérieur du projet dans lequel la session se trouvait lors de son **premier appel révisé**. La racine est fixée à ce moment-là et un `cd` ultérieur ne la déplace jamais ; un `cd` modifie toujours la résolution d'un chemin relatif. Lui permettre de suivre le `cd` permettrait à un `cd ~/.ssh` lors d'un appel de faire de `~/.ssh` le projet pour le suivant. + +L'ancrage est `~/.failproofai/state/semantic/roots/.json`, contenant `{root, at}` : fichier `0600`, répertoire `0700`, et la même règle d'identifiant de session que ci-dessus. Les fichiers de plus de 7 jours sont supprimés lorsqu'une nouvelle session ancre sa racine. Un répertoire `roots` que d'autres utilisateurs peuvent écrire est ignoré, et la racine du répertoire actif est utilisée à la place. Pour ré-ancrer une session, supprimez son fichier. + +## Limites connues + +- **Une invite n'est fiable qu'autant que l'invocation du hook.** Tout ici lit la charge utile que le harnais a écrite sur le stdin du hook. Un agent capable d'exécuter des commandes peut exécuter le harnais sans interface (`claude -p` et les sept autres listés ci-dessus) ou exécuter lui-même le binaire hook de Failproof AI avec une charge utile qu'il a écrite, et enregistrer une invite que personne n'a saisie. Il s'agit du compromis accepté décrit en haut de cette page : il ne lève que les politiques révisables, jamais une politique stricte — mais douze des quinze politiques intégrées révisables sont des refus, donc une invite forgée peut transformer un vrai blocage en autorisation pour ces douze. +- **La détection de sous-agent est façonnée pour Claude.** Une charge utile portant `agent_id` n'est jamais enregistrée, quel que soit le harnais. C'est le champ que Claude Code, Factory Droid et Devin utiliseraient. Codex déclenche son événement d'invite à l'intérieur des threads de sous-agent, Copilot exécute des assistants en processus, Goose dispose d'un outil `delegate` et OpenClaw exécute des personas — aucun d'entre eux ne marque la charge utile d'une manière que ceci reconnaît, donc une invite de sous-agent sur ces harnais est enregistrée comme appartenant à la session. L'`openclaw.agentId` d'OpenClaw n'est **pas** ce marqueur : le plugin livré le définit sur chaque exécution, y compris celle du propriétaire. +- **Les planificateurs qui ne transportent aucun marqueur.** `schedule_wakeup` et `loop_wakeup` de Claude Code, et les déclencheurs `cron` et `heartbeat` d'OpenClaw, sont refusés parce que ces harnais le disent dans la charge utile. Le propre planificateur de Goose (`goose schedule add`) et `codex exec` de Codex ne disent rien, donc une exécution qu'ils démarrent est enregistrée comme toute autre. +- **Le dernier message d'un agent peut être un message que l'agent a choisi.** La transcription n'est pas authentifiée, donc un agent qui écrit sa propre transcription peut décider de ce que dit son « dernier message ». Il est étiqueté comme écrit par l'agent et ne lève jamais rien par lui-même — mais notez que le chemin v1 de `decide.ts` lui permet de satisfaire la vérification déterministe « l'utilisateur a-t-il nommé cette cible », donc un agent qui contrôle sa transcription peut fournir un nom de cible qu'un remplacement nécessite. +- **Une invite qui commence par l'un des en-têtes machine de l'extension est entièrement supprimée.** Commencez une invite avec `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` ou un autre en-tête de section du premier groupe ci-dessus, et n'écrivez jamais d'en-tête `## My request:`, et rien n'est enregistré pour ce tour — donc rien n'est levé pour lui non plus. C'est délibéré : ces sections portent du texte que quelqu'un d'autre contrôle (du code que vous avez sélectionné, le commentaire de diff d'un réviseur, un titre de page), et enregistrer cela comme vos mots est le pire des échecs. Les en-têtes qu'un développeur est susceptible de taper se trouvent dans le deuxième groupe et ne suppriment jamais une invite par eux-mêmes. +- **OpenCode n'enregistre rien en pratique.** Son événement `message.updated` ne transporte aucun texte dans l'OpenCode actuel, et il se déclenche également pour les sessions enfants que son outil de tâche crée, dont le message « utilisateur » a été écrit par l'agent parent. +- **`CODEX_HOME` n'est pas respecté** par la découverte des déploiements dans `lib/codex-sessions.ts`. Cela n'affecte que l'endroit où un snapshot de message d'agent est recherché, jamais si une invite est enregistrée. \ No newline at end of file diff --git a/docs/fr/reference/jev-providers.mdx b/docs/fr/reference/jev-providers.mdx new file mode 100644 index 000000000..1a1ad7b1a --- /dev/null +++ b/docs/fr/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Fournisseurs Jev et configuration avec votre propre clé" +description: "Points de terminaison des fournisseurs, identifiants de modèles, configuration et comportement en cas d'échec pour la révision des politiques Jev en direct avec votre propre clé." +icon: "key-round" +--- + +Voici la référence des fournisseurs et de la configuration pour les [politiques Jev](/fr/policies/jev) avec votre propre clé. Les politiques regex correspondent à des chaînes de caractères. Elles sont incapables de distinguer `rm -rf build/` que vous avez explicitement demandé de `rm -rf ~` qui s'est glissé dans un plan — elles bloquent donc trop à certains endroits et pas assez à d'autres. **Jev**, le classificateur de TypeSafe, analyse l'appel par rapport à ce que vous avez réellement demandé et répond à une série de questions par oui ou non en une seule requête rapide. + +Une fois votre point de terminaison et votre clé Jev configurés, Failproof AI interroge Jev pour chaque appel d'outil **en parallèle** des politiques regex, et non à leur place : + +- Le refus d'une politique **stricte** est définitif. Jev ne peut pas l'annuler. Toute politique est stricte sauf si elle est explicitement marquée comme révisable et nomme les vérifications Jev qui la couvrent ; ainsi, une politique personnalisée, de pack ou Cloud qui ne spécifie rien est stricte, et la protection intégrée permanente l'est toujours. +- Le refus d'une politique **révisable** peut être annulé, mais uniquement lorsque Jev a été interrogé sur la préoccupation exacte que couvre cette politique et a répondu « rien ici » ou « l'utilisateur l'a demandé ». Une vérification qui juge la préoccupation réelle, quand l'utilisateur n'a pas demandé l'appel, maintient le refus — même si son propre verdict n'est qu'un avertissement, car avant un appel d'outil un avertissement n'arrête pas l'agent. Et lorsque cette vérification est de celles qui peuvent refuser (exposition de secrets, exfiltration d'identifiants, suppression destructrice, …), rien n'est annulé pour cet appel. +- Un blocage peut toutefois devenir un **avertissement** lorsque l'appel fait partie de la tâche que vous avez confiée et n'a pas de portée plus large : Jev adoucit son propre refus en avertissement, et cet avertissement — précisant ce qui pose réellement problème dans l'appel — remplace le blocage de la politique. +- Jev peut également émettre des avertissements ou des refus de sa propre initiative, pour des nuisances qu'aucune regex ne décrit. +- Si Jev ne peut pas répondre (délai dépassé, limitation de débit, erreur serveur, crédits épuisés, version de modèle inattendue), cet appel reçoit le résultat regex, exactement comme sans Jev. +- Jev ne rend jamais un appel plus permissif que vos seules politiques, à moins d'avoir lu l'intégralité de l'appel et d'avoir été interrogé sur la préoccupation exacte. Tout ce qui est en deçà — un appel trop volumineux pour être envoyé entier, une injection suspectée — retire les autorisations et maintient tous les refus. + + +Sans configuration Jev, rien ne change : les hooks exécutent les politiques regex exactement comme ils l'ont toujours fait. La configuration est l'unique mécanisme d'activation. + + + +Vous utilisez FailproofAI Cloud ? Vous n'avez pas besoin de votre propre clé : une machine connectée avec une clé disposant de `jev:evaluate` peut utiliser Jev sur le plan de votre organisation. Consultez [Jev via FailproofAI Cloud](/fr/reference/jev-cloud). + + +## Avant de commencer + +Installez **failproofai 1.0.8-beta.0 ou une version ultérieure** et rattachez ses hooks à un [environnement d'exécution compatible](/fr/reference/harnesses) sur la machine où tourne votre agent. Suivez le [guide de démarrage rapide](/fr/start/quickstart) s'il s'agit d'une nouvelle machine, ou [configurez l'application locale](/fr/start/setup#enforce-locally) si vous n'utilisez pas Cloud. Vérifiez la version de la CLI installée avec `failproofai --version`. + +Obtenez une clé API auprès d'un fournisseur ci-dessous, ou préparez un point de terminaison compatible et sa clé. Jev examine les appels d'outils nommés à la porte `PreToolUse` ou `PermissionRequest`. Il peut émettre son propre verdict, mais annuler un refus de politique existant nécessite également qu'une politique installée soit marquée comme [révisable](/fr/policies/authority). Les refus des politiques strictes restent définitifs. + +## Choisir un fournisseur + +Jev est accessible via cinq routes. Fournissez une clé pour l'une d'entre elles. + +| Fournisseur | `--provider` | Point de terminaison | Modèle par défaut | Notes | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Version exacte épinglée. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Les requêtes sont acheminées uniquement vers des points de terminaison sans conservation de données, sans basculement vers un autre fournisseur. Rapporte une version datée telle que `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nomme Jev uniquement par un alias, donc la version qui répond est enregistrée comme non vérifiée. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Nécessite `--account-id`. Environ six appels par seconde par clé ont été mesurés avant l'obtention de HTTP 429. | +| Votre propre point de terminaison | `custom` | `/systemone` | `jev-1.13.0` | Tout point de terminaison qui accepte le corps de requête de TypeSafe et indique quel modèle a répondu. `https` uniquement ; le `http` simple vers un hôte de bouclage (`localhost`, `127.0.0.1`, `::1`) est accepté pour les tests locaux. | + + +Avec la fonctionnalité bring-your-own-key de Vercel, une requête échouée est silencieusement réessayée avec les identifiants de Vercel. Si vous avez besoin que chaque appel soit facturé et visible uniquement sur votre propre compte TypeSafe, utilisez TypeSafe directement. + + +## Configuration + +Une commande, le point de terminaison et la clé. Commencez en mode `observe` pour inspecter les verdicts de Jev pendant que les politiques existantes continuent de décider des appels : + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### L'URL détermine le fournisseur + +Il n'est pas nécessaire de nommer le fournisseur : l'**hôte** de l'URL indique lequel c'est. + +| Hôte de l'URL | Fournisseur | Nécessite également | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| tout autre hôte | `custom` | — l'URL fournie est l'URL de base | + +Trois conséquences en découlent : + +- **Une URL pointant vers l'API native du fournisseur n'écrit aucune surcharge.** `--url https://api.typesafe.ai/v1` produit exactement la même configuration que `--provider typesafe`. Fournissez un chemin ou un hôte différent pour un fournisseur connu et il sera stocké comme URL de base, comme le ferait `--base-url`. +- **`--provider` remplace toujours l'inférence**, ce qui permet d'atteindre un proxy parlant l'API d'un fournisseur depuis votre propre hôte : `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Un `--provider` qui contredit l'hôte est refusé**, sans tentative de résolution. `--provider openrouter --url https://api.typesafe.ai/v1` n'écrit rien et explique pourquoi : les deux paramètres sont en désaccord sur la destination de votre clé. Cette même combinaison est refusée depuis `jev setup --base-url` et depuis les paramètres Jev du tableau de bord. (`--provider custom` n'est pas une contradiction — cela signifie « traiter cette URL telle quelle » — sauf sur l'hôte Cloudflare, dont le point de terminaison par compte ne peut pas être atteint via une route personnalisée.) + +`--url` est validé exactement comme le `baseUrl` du fichier de configuration, et refusé avec les mêmes messages : `https`, ou `http` simple vers un hôte de bouclage (`localhost`, `127.0.0.1`, `::1`) dans n'importe quel mode. Risque : rien n'authentifie un serveur de bouclage, donc pendant qu'il est arrêté, un autre processus local pourrait prendre son port et répondre ; utilisez `https` en dehors des tests locaux. + +### La clé + +Transmettez-la via `--key-stdin`, ou exécutez la commande dans un terminal sans cet argument et collez la clé à l'invite masquée. Dans les deux cas, elle est directement écrite dans le fichier de configuration et n'est jamais affichée en retour. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` accepte les mêmes paramètres et est la forme longue de tout cela : `setup --provider ` si vous préférez nommer le fournisseur plutôt que l'URL. + +### `--token` et son coût + +`--token ` place la clé directement sur la ligne de commande, ce qui est le moyen le plus rapide de configurer une machine, mais le seul qui laisse la clé ailleurs que dans le fichier de configuration : + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Un argument de ligne de commande se retrouve dans le fichier d'historique de votre shell, et pendant l'exécution de la commande il apparaît dans la liste des processus — lisible depuis `/proc` par tout processus tournant sous votre identité. `setup` le signale à chaque utilisation de `--token`. Préférez `--key-stdin` sur une machine partagée, dans une session enregistrée, ou partout où le fichier d'historique est synchronisé ; faites tourner une clé transmise de cette façon si cela vous préoccupe. + + +`--token`, `--key-stdin` et `--key-from-env` sont mutuellement exclusifs : n'en utilisez qu'un. + +Envoyez ensuite une petite requête en direct pour vérifier la clé, le point de terminaison et quelle version de Jev a répondu : + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` retourne le code 1, et l'indique dans son titre, lorsque la réponse arrive après le délai d'attente (chaque hook se replierait sur regex avec la raison `timeout`) ou répond incorrectement à sa question de vérification. + +Les hooks lisent la configuration à chaque appel d'outil, elle s'applique donc dès le prochain. Il n'y a rien à redémarrer, avec ou sans le démon. + +## Vérifier son fonctionnement + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` affiche le fournisseur, le point de terminaison, le modèle, le mode, le fichier de configuration et ses permissions, mais jamais la clé. En dessous, il résume l'activité récente : combien d'appels Jev a évalués, combien de fois il s'est replié sur regex et pourquoi, sa latence, et quelles politiques révisables il a annulées. + +## Vérifier un appel réel + +Démarrez une nouvelle session dans l'agent avec les hooks. Demandez-lui d'utiliser son outil de lecture de fichiers sur `README.md` et d'en rapporter le titre. Confirmez que la session contient cet appel d'outil, puis relancez `failproofai jev status` : le nombre d'appels évalués récemment devrait avoir augmenté. Ouvrez **Policies → Activity** dans le [tableau de bord local](/fr/reference/local-dashboard#review-policy-activity) pour inspecter le verdict Jev de l'appel et son mode. En mode observe, le résultat de la politique décide toujours de l'appel. Une annulation n'apparaît que si une politique révisable a correspondu et que Jev a annulé toutes les vérifications nommées ; une simple lecture peut n'avoir aucune politique à annuler. + +## Mode observe + +`enforce` est le mode par défaut. Pour observer Jev sans lui permettre de modifier aucune décision, basculez en `observe` : Jev est toujours interrogé et ses verdicts sont enregistrés, mais c'est le résultat regex qui est appliqué. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` conserve la configuration — le point de terminaison et la clé — et cesse d'interroger Jev : les hooks exécutent les politiques regex exactement comme sans configuration, et `failproofai jev status` affiche « off (switched off) ». Revenez en arrière avec `--mode observe` ou `--mode enforce`. + +Réexécuter `setup` pour le même fournisseur conserve la clé stockée, donc un changement de mode se fait en un seul paramètre. Changer de fournisseur repart de zéro et demande la clé de ce fournisseur. Il en va de même pour un `--base-url` qui déplace les requêtes vers un hôte différent : une clé stockée n'est envoyée qu'à l'hôte pour lequel elle a été fournie, ou à l'API native de son fournisseur. + +## Le fichier de configuration + +Tout se trouve dans un seul fichier, `~/.failproofai/jev.json`, écrit par `setup` : + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Champ | Signification | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` ou `custom` — ou `failproofai`, dont la clé provient de la connexion FailproofAI Cloud plutôt que de ce fichier (voir [Jev via FailproofAI Cloud](/fr/reference/jev-cloud)). | +| `apiKey` | Envoyé en tant que `Authorization: Bearer `. | +| `baseUrl` | Obligatoire pour `custom` ; remplace la base de l'API du fournisseur dans les autres cas. Doit être `https`. Le `http` simple vers `localhost` n'est accepté qu'avec `mode: observe` : rien n'authentifie un port local, donc pendant que votre proxy est arrêté, tout processus sur la machine, y compris l'agent en cours d'évaluation, pourrait répondre à sa place. | +| `accountId` | Cloudflare uniquement : 32 caractères hexadécimaux en minuscules. | +| `model` | Remplace l'identifiant de modèle par défaut du fournisseur. Un identifiant versionné doit nommer Jev 1.13. Une valeur ressemblant à une clé API est refusée (et non répétée), de sorte qu'une clé collée dans `--model` n'est jamais stockée ni envoyée comme modèle. | +| `timeoutMs` | Durée pendant laquelle un appel d'outil attend Jev avant d'utiliser le résultat regex. Entre 100 et 10000, par défaut 3000. | +| `mode` | `enforce` (par défaut), `observe`, ou `off` (conserver la configuration, ne pas exécuter Jev). | + +Trois règles le protègent : + +- **Propriétaire uniquement.** Il est écrit avec les permissions `0600`. Une copie qu'un autre utilisateur ou groupe peut lire ou écrire est **refusée**, et les hooks se replient sur regex jusqu'à ce que vous exécutiez `chmod 600 ~/.failproofai/jev.json` ou `setup` à nouveau. Le répertoire est également vérifié : `~/.failproofai` ne doit pas être **accessible en écriture** par quelqu'un d'autre, car quiconque peut y écrire peut remplacer le fichier quelles que soient ses propres permissions. `setup` supprime ces droits d'écriture s'il les trouve. `failproofai jev status` indique quand une configuration a été refusée et affiche le point de terminaison que le fichier nomme : quelqu'un d'autre pourrait l'avoir modifié, vérifiez donc qu'il vous appartient avant de faire `chmod`. Réexécuter `setup` sur un tel fichier ne transmet sa clé stockée qu'à l'API native du fournisseur ; tout autre point de terminaison qu'il nomme nécessite à nouveau la clé (`--key-stdin`), ou `--base-url default` pour renvoyer les requêtes vers le fournisseur. +- **Global uniquement.** Un dépôt ne peut pas activer Jev, le pointer vers un autre point de terminaison ou choisir son modèle : un `.failproofai/jev.json` à l'intérieur d'un projet est ignoré, et le fournisseur, l'URL, le modèle et l'identifiant de compte ne sont lus qu'à partir de ce fichier — jamais depuis l'environnement, que les paramètres de l'agent d'un dépôt peuvent définir. (`FAILPROOFAI_HOME` ne contourne pas cela : il déplace l'intégralité du répertoire failproofai, vos politiques incluses, plutôt que de rediriger Jev seul.) +- **La clé seule peut provenir de l'environnement.** Si le fichier n'a pas d'`apiKey`, `FAILPROOFAI_JEV_API_KEY` la fournit pour cette session (`setup --key-from-env` écrit un tel fichier). Elle ne remplace jamais une clé que le fichier contient, et elle ne peut pas activer Jev sans le fichier. Lorsque la variable n'est pas définie, Jev est simplement désactivé pour ce shell : `failproofai jev status` l'indique, retourne 0 et laisse la configuration intacte (`status --json` rapporte `"status": "key-missing"` avec `"reason": "no-env-key"`). Le démon `failproofaid` ne voit pas l'environnement de votre shell, donc sur une machine configurée avec `failproofai config`, conservez la clé dans le fichier. + +## Quelle version de Jev répond + +Les seuils de décision de Failproof AI ont été étalonnés sur Jev 1.13, donc une réponse n'est utilisée que lorsqu'elle provient de cette famille : `jev-1.13.x`, ou le `typesafe/jev-1.13-` d'OpenRouter. Lorsqu'un fournisseur ne nomme Jev que par un alias et ne rapporte aucune version (Vercel, et Cloudflare lorsqu'il ne le précise pas), la réponse est utilisée et enregistrée comme non vérifiée. Un point de terminaison `custom` doit indiquer le modèle qui a répondu ; la seule exception est un nom `--model` non versionné que vous avez configuré pour lui, qui, renvoyé en écho, est enregistré comme non vérifié de la même façon. Une réponse rapportant toute autre version, ou une réponse `custom` n'en rapportant aucune, n'est pas utilisée : cet appel se replie sur regex avec la raison `model-mismatch`. + +## Quand Jev ne peut pas répondre + +Chacun de ces cas revient au résultat regex pour cet appel et est enregistré avec sa raison, que `failproofai jev status` totalise : + +| Raison | Cause | +| --- | --- | +| `timeout` | Pas de réponse dans le délai `timeoutMs`. | +| `http-429` | Le fournisseur a limité le débit de la clé. | +| `rate-limited` | Le limiteur interne de Failproof AI a retenu l'appel avant de l'envoyer : 5 requêtes par seconde, en rafales de 5 au maximum, et aucune pendant un instant après que le fournisseur réponde `429`. Pas le fournisseur. | +| `http-500`, `http-502`, `http-503`, … | Une erreur serveur chez le fournisseur. Le statut exact est enregistré. | +| `out-of-credits` | HTTP 402 : le compte du fournisseur n'a plus de crédits. | +| `provider-refused` | HTTP 402 de Cloudflare indiquant « Model execution failed (Payment error) » : le fournisseur a refusé d'exécuter le modèle sur cette requête. Généralement pas un problème de facturation, donc recharger les crédits ne résoudra pas le problème. | +| `http-401`, `http-403` | La clé a été refusée. | +| `http-404` | Rien n'est servi à `/systemone`, donc l'URL de base est incorrecte — `/systemone` y est ajouté, et chaque fournisseur le sert à la racine de sa version. `failproofai jev models` indique ce que le point de terminaison sert effectivement. | +| `network` | Le point de terminaison n'était pas accessible. | +| `http-301`, `http-302`, `http-307`, `http-308` | Le point de terminaison a répondu par une redirection. Les redirections ne sont jamais suivies, donc la réponse ne peut provenir que de l'URL dans votre configuration ; définissez `--base-url` sur l'URL finale. | +| `malformed` | Le point de terminaison a répondu, mais pas avec une réponse Jev — un corps qui n'est pas JSON, ou qui ne contient pas de réponses. | +| `cloudflare-error`, `cloudflare-incomplete` | L'enveloppe Cloudflare a signalé un échec, ou un travail non terminé. | +| `model-mismatch` | Une version de Jev autre que 1.13 a répondu, ou un point de terminaison `custom` n'a pas indiqué quel modèle a répondu. | +| `request-cut` | **Pas une panne.** Jev a répondu ; il n'a vu qu'une partie de l'appel, donc sa réponse n'a rien annulé. Voir [Quand Jev a répondu, mais pas sur l'intégralité de l'appel](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` peut également afficher quelques raisons plus rares, comme `upstream-error` (la réponse portait l'erreur propre du fournisseur) ou `config`, et totalise toute raison qu'il ne peut pas nommer sous `other`. + +`request-cut` figure dans ce tableau parce que `failproofai jev status` le totalise avec les autres, et parce que lui aussi laisse tous les refus en place. C'est la seule raison ici qui ne dit rien sur votre fournisseur : la requête est arrivée et Jev y a répondu. Contrairement à toutes les lignes précédentes, cette réponse compte tout de même — le propre refus ou avertissement de Jev s'applique en plus du résultat regex plutôt que d'être ignoré. Ainsi, une série de ces cas signifie que les appels atteignent l'évaluateur avec une taille trop grande pour être envoyés entiers, et non que votre point de terminaison est défaillant ; recharger des crédits ou changer l'URL ne fera pas bouger le compteur. + +## Quand Jev a répondu, mais pas sur l'intégralité de l'appel + +Deux autres situations peuvent se produire, et aucune ne correspond à un échec de réponse de Jev. Toutes deux concernent la quantité de l'appel, ou de la conversation, qui a tenu dans une seule requête. + +**Une partie de l'appel lui-même n'a pas tenu.** Un appel d'outil est envoyé dans un budget fixe, et un appel surdimensionné — un très grand `Write`, un énorme corps MCP, une commande gonflée jusqu'à la limite — est envoyé avec ce qui a tenu. Jev répond quand même, et sa réponse compte toujours : son propre refus ou avertissement s'applique normalement. Ce qu'il ne peut pas faire, c'est **annuler** quoi que ce soit, car un verdict rendu sur une partie d'un appel n'est pas un verdict sur l'appel entier. Ainsi, tous les refus de politique restent, et l'appel est enregistré comme repli avec la raison `request-cut`, que `failproofai jev status` totalise aux côtés des raisons ci-dessus. La règle qui en découle : rendre un appel plus grand peut lui coûter ses annulations, et ne peut jamais en acheter une. + +**Un message n'a pas tenu.** Une longue invite que vous avez collée, le dernier message de l'agent, ou une invite que le magasin propre de cet évaluateur avait déjà plafonnée. **Rien ne change** : l'appel est jugé, annulé et enregistré exactement comme n'importe quel autre, et il n'est pas comptabilisé comme repli. La longueur de ce que vous tapez ne décide jamais d'un verdict, et une coupure ne peut pas fabriquer un consentement : lorsqu'une invite est arrivée déjà plafonnée, « vous n'avez pas demandé cela » cesse d'être une conclusion qui peut en être tirée, plutôt que d'en devenir une. + +La frontière entre les deux est l'auteur du texte. L'appel appartient à l'agent, et une règle qui permettrait à sa longueur de réduire la gravité serait une règle que l'agent peut utiliser ; votre invite vous appartient, et traiter sa longueur comme un signal ne ferait que pénaliser le collage d'une spécification ou d'une trace de pile. + +## Ce qui quitte la machine + +Pour chaque appel d'outil que Jev évalue, une requête est envoyée à votre fournisseur, contenant : + +- l'appel d'outil lui-même, avec les secrets tels que les clés API, les jetons bearer et les assignations `KEY=` occultés ; +- les invites récentes que vous avez tapées, avec le texte ajouté par l'environnement d'exécution de votre agent retiré ; +- le dernier message de l'agent avant votre dernière invite, étiqueté comme écrit par l'agent ; +- des faits calculés localement, tels que si un chemin se trouve à l'intérieur du projet — celui dans lequel la session se trouvait lors de son premier appel révisé, [épinglé pour la session](/fr/reference/jev-intent#the-project-root) — et la branche git actuelle. + +Cela ne va qu'au point de terminaison de votre configuration, sous votre clé. + +## Désactiver + +```bash +failproofai jev remove +``` + +Cette commande supprime `~/.failproofai/jev.json`. Dès le prochain appel d'outil, les hooks exécutent les politiques regex exactement comme avant. Les magasins par session sous `~/.failproofai/state/semantic/` (invites enregistrées dans `sessions/`, racines de projet dans `roots/`) sont conservés et expirent naturellement. Pour cesser d'interroger Jev tout en conservant la configuration, utilisez plutôt `failproofai jev setup --mode off`. + +## Référence des commandes + +| Commande | Résultat | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configure en une commande ; le fournisseur est déduit de l'hôte de l'URL | +| `failproofai jev --url --token ` | Identique, avec la clé sur la ligne de commande — votre historique et la liste des processus la voient | +| `failproofai jev setup --provider --key-stdin` | Écrit la configuration depuis une clé transmise sur stdin | +| `failproofai jev setup --provider ` | Identique, en demandant la clé à une invite masquée | +| `failproofai jev setup --key-from-env` | Ne stocke pas de clé ; lit `FAILPROOFAI_JEV_API_KEY` par session | +| `failproofai jev setup --mode observe` | Change le mode (`enforce`, `observe` ou `off`), en conservant la clé stockée | +| `failproofai jev setup --model ` / `--base-url ` | Remplace le modèle ou la base API ; `default` supprime la surcharge | +| `failproofai jev setup --timeout-ms ` | Modifie le budget par appel | +| `failproofai jev status [--json]` | Configuration, permissions et activité récente ; jamais la clé | +| `failproofai jev test [--json]` | Une requête en direct : latence et version qui a répondu | +| `failproofai jev models [--provider ] [--url ] [--json]` | Les identifiants de modèles que rapporte le `/models` de ce point de terminaison, en marquant celui configuré | +| `failproofai jev remove` | Supprime la configuration ; Jev est désactivé | \ No newline at end of file diff --git a/docs/fr/reference/jev.mdx b/docs/fr/reference/jev.mdx new file mode 100644 index 000000000..cb15e258e --- /dev/null +++ b/docs/fr/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Référence d'intégration Jev" +description: "Configuration, fournisseurs, clés, données de requête et comportement en cas d'échec pour Jev." +icon: "braces" +--- + +Jev a deux usages dans Failproof AI : + +| Usage | Quand il s'exécute | Ce qu'il retourne | Par où commencer | +| --- | --- | --- | --- | +| Évaluation de session | Après la fin d'une session | Un score pour une question à réponse fixe | [Évaluations Jev](/fr/evaluations/jev) | +| Révision de politique pour les appels d'outils | Avant l'exécution d'un appel d'outil contrôlé | Un verdict accompagné des politiques installées | [Politiques Jev](/fr/policies/jev) | + +## Pages de référence + +| Sujet | Détails | +| --- | --- | +| [Questions d'évaluation](/fr/reference/jev-evaluations) | Critères booléens et de score ordonné, résultats, limites et remplissage rétrospectif. | +| [Comparaison des fournisseurs et configuration avec sa propre clé](/fr/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare et points de terminaison personnalisés ; inférence d'URL, identifiants de modèle, `jev.json`, modes et codes de repli. | +| [Route FailproofAI Cloud](/fr/reference/jev-cloud) | Permissions des clés machine, configuration automatique de l'observation, limites d'utilisation, état de la connexion et gestion des données. | + +Les commandes CLI locales sont répertoriées dans la [référence CLI de Failproof AI](/fr/reference/failproof-cli). La [référence du tableau de bord local](/fr/reference/local-dashboard#set-up-jev) décrit ses paramètres Jev et sa vue d'activité. \ No newline at end of file diff --git a/docs/fr/reference/mcp.mdx b/docs/fr/reference/mcp.mdx new file mode 100644 index 000000000..ccbe709a0 --- /dev/null +++ b/docs/fr/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "Serveur MCP" +description: "Connectez Claude, Cursor, Codex ou un autre client MCP à Failproof AI Cloud en utilisant vos propres permissions." +icon: "plug" +--- + +Connectez un outil d'IA à Failproof AI Cloud et travaillez avec les données de vos agents depuis celui-ci. Votre outil peut interroger les sessions et les événements, exécuter des requêtes SQL en lecture seule, consulter les tableaux de bord, les alertes, les problèmes, les audits et les politiques, et, si vous disposez des permissions nécessaires, effectuer des modifications telles que la création d'une alerte ou le déploiement d'une politique. + +Chaque appel s'exécute avec **vos propres** permissions, dans **une** organisation que vous choisissez lors de la connexion. + +Il n'existe qu'une seule adresse pour tous, hébergée ou auto-hébergée : + +```text +https://gateway.befailproof.ai/mcp +``` + +## Connecter un client + +Ajoutez l'adresse à votre client. La première fois qu'un outil est utilisé, votre navigateur s'ouvre. Indiquez où se trouve votre Failproof AI Cloud, connectez-vous, sélectionnez une organisation, puis cliquez sur **Autoriser**. **Annuler** ne connecte rien. + +La page indique le nom de l'application et l'adresse vers laquelle elle redirige. Une application non identifiée par sa propre adresse web est marquée **application non vérifiée** ; ne poursuivez que si vous venez de la démarrer depuis votre propre client. + + + + Dans claude.ai ou Claude Desktop, accédez à **Paramètres → Connecteurs → Ajouter un connecteur personnalisé**. Nommez-le `Failproof AI`, saisissez l'adresse, cliquez sur **Ajouter**, puis sur **Connecter**. + + Pour les abonnements Team et Enterprise, un propriétaire doit d'abord ajouter le connecteur pour l'organisation. Chaque membre connecte ensuite son propre compte. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Exécutez ensuite `/mcp` dans Claude Code, sélectionnez `failproofai`, puis choisissez **Authentifier**. + + + Ajoutez ceci dans `~/.cursor/mcp.json`, ou dans le fichier `.cursor/mcp.json` de votre projet : + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor affiche **Connexion requise** à côté du serveur. Cliquez dessus pour vous connecter. + + + Ajoutez ceci dans `~/.codex/config.toml` : + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Exécutez ensuite `codex mcp login failproofai`. + + + Tout client prenant en charge les serveurs MCP distants via Streamable HTTP avec OAuth fonctionne. Renseignez l'adresse ci-dessus. Aucun identifiant ou secret client n'est à configurer. + + + +## Une organisation par connexion + +Une connexion agit uniquement dans l'organisation que vous avez choisie. Pour utiliser deux organisations, ajoutez le serveur deux fois sous des noms différents, par exemple `failproofai-acme` et `failproofai-sandbox`, et connectez chacun à son organisation respective. + +Les organisations de démonstration n'acceptent pas les connexions. Choisissez votre propre organisation à la place. + +## Permissions + +Une connexion peut effectuer tout ce que vous pouvez faire dans l'organisation, dans les limites de l'ensemble ci-dessous. Elle suit vos permissions actuelles : si un administrateur vous en accorde davantage, l'outil en bénéficie ; s'il vous en retire, l'outil les perd lors de son prochain appel. + +| Permission | Permet à l'outil de | +| --- | --- | +| `events:read` | Lister les événements, consulter le résumé d'une session, lister les agents et les environnements | +| `evaluations:read` | Lister les sessions, lire et résumer les résultats et les tâches d'évaluation | +| `evaluations:trigger` | Créer des évaluations, publier de nouvelles versions, les activer ou désactiver, effectuer un backfill et réévaluer une session | +| `dashboards:read`, `dashboards:write` | Consulter les tableaux de bord, ou les créer, les renommer et y ajouter des requêtes | +| `queries:read`, `queries:write` | Consulter les requêtes sauvegardées, ou les enregistrer et les modifier | +| `queries:run` | Exécuter une requête SQL en lecture seule et consulter le schéma des requêtes | +| `alerts:read`, `alerts:write` | Consulter les alertes, ou les créer, modifier, mettre en pause, supprimer et tester | +| `issues:read` | Consulter les problèmes, les accuser de réception et y ajouter des commentaires | +| `issues:create` | Ouvrir un problème sur une alerte | +| `issues:close` | Résoudre et fermer des problèmes | +| `audits:read`, `audits:write` | Consulter les audits, les exécutions et les résultats, ou créer et modifier des audits et démarrer une exécution | +| `code_fixes:read` | Voir comment corriger un problème et obtenir son contexte pour qu'un agent le corrige | +| `code_fixes:write` | Démarrer une correction dans Failproof AI Cloud, qui ouvre une pull request sur votre GitHub | +| `policies:read`, `policies:write` | Consulter les politiques, les machines et les déploiements, ou publier, déployer et annuler des politiques | + +Quelques outils ne nécessitent aucune permission car ils n'accèdent à aucune donnée d'organisation : la création de liens vers des sessions et des événements, ainsi que la recherche dans cette documentation. + +Un outil d'IA ne peut jamais accéder aux clés API, aux utilisateurs, aux paramètres ou à l'administration de l'organisation, et ne peut pas envoyer d'événements. + +## Approbation des modifications + +Les opérations d'écriture vous demandent confirmation si votre client peut afficher l'invite. Vous voyez ce qui va changer et sélectionnez **Approuver cette modification** pour continuer. Si vous refusez ou ne répondez pas dans un délai d'environ 4 minutes, rien ne change. Certains clients cessent d'attendre après une minute, répondez donc rapidement. + + + Un client qui ne prend pas en charge les invites ne reçoit pas de demande de confirmation, et une opération d'écriture s'exécute dès que le client effectue l'appel. Dans ce cas, la confirmation de votre client est la seule existante ; conservez-la activée pour les outils d'écriture. + + +## Applications connectées et révocation + +**Paramètres → Intégrations → MCP** liste vos applications connectées dans l'organisation actuelle, avec leurs permissions et leur dernière utilisation. **Révoquer** déconnecte immédiatement une application. Supprimer le serveur dans votre client révoque également la connexion. + +Vous pouvez avoir jusqu'à 5 applications connectées par organisation. Reconnecter la même application remplace sa connexion précédente. + +## Déploiements auto-hébergés + +Choisissez **Failproof AI Cloud auto-hébergé** lors de la connexion, et saisissez l'adresse à laquelle vous vous connectez. Votre déploiement doit être accessible via HTTPS public. + +Les appels aux outils et leurs résultats transitent par la passerelle Failproof AI hébergée entre votre outil d'IA et votre déploiement. La passerelle ne les stocke pas. + +## Ce qu'il advient de vos données + +Les résultats sont transmis à l'outil d'IA que vous avez connecté, et le fournisseur de cet outil les traite selon ses propres conditions. Pour chaque appel d'outil, Failproof AI enregistre le nom de l'outil, son résultat, sa durée d'exécution et l'organisation — jamais les arguments ni les résultats. Consultez la [politique de confidentialité](https://befailproof.ai/privacy/). + +## Résolution des problèmes + +| Ce que vous voyez | Que faire | +| --- | --- | +| « Démarré dans un autre navigateur » | Terminez la connexion dans le navigateur ouvert par le client, avec les cookies activés, puis recommencez depuis le client | +| Une erreur après **Autoriser** | Le lien n'est valide qu'une seule fois et expire après 10 minutes ; recommencez depuis le client | +| Un outil attendu est absent | Vous ne disposez pas de sa permission dans cette organisation. Contactez un administrateur. Vous n'avez pas besoin de vous reconnecter une fois que vous l'avez | +| Le client vous demande continuellement de vous connecter | La connexion a été révoquée, vous avez quitté l'organisation, ou elle n'a pas été utilisée pendant 90 jours. Reconnectez-vous | +| « Vous avez 5 applications connectées » | Révoquez-en une sous **Paramètres → Intégrations → MCP**, puis reconnectez-vous | + +Toujours bloqué ? Envoyez un e-mail à [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/fr/reference/otel.mdx b/docs/fr/reference/otel.mdx new file mode 100644 index 000000000..538f572a8 --- /dev/null +++ b/docs/fr/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Activez OTEL pour les agents de codage, inspectez la livraison et restaurez vos paramètres précédents." +icon: "radio" +--- + +`failproofai otel` configure les rapports OpenTelemetry optionnels vers FailproofAI Cloud. Commencez par connecter votre machine avec `failproofai config` et demandez à un administrateur de l'organisation d'activer **Settings → OpenTelemetry**. + +La configuration interactive propose OpenTelemetry après le champ de clé Cloud et le sélecteur d'agents. Cette étape optionnelle est désactivée par défaut. Choisissez Oui pour sélectionner les agents OTEL ; le même code d'activation s'exécute après l'écriture de la connexion. Appuyer sur Échap avant la configuration n'applique aucune modification. La configuration non interactive, une clé fournie manuellement, le mode open-source et la conservation d'une connexion existante ne vous inscrivent pas automatiquement. + +## Activer un agent + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Les agents pris en charge sont `claude`, `codex` et `copilot` (VS Code). La configuration de Copilot nécessite un exécutable VS Code ou une extension Copilot installée. La seule présence d'un répertoire de paramètres résiduel ne suffit pas ; la configuration ignore Copilot si aucun des deux n'est trouvé. + +`--local` envoie les données au relais local plutôt que directement vers Cloud. Copilot utilise automatiquement le relais, car ses paramètres ne peuvent pas stocker l'en-tête d'authentification. + +Le relais n'écoute que sur votre machine. Le daemon FailproofAI configuré prend en compte le changement en quelques secondes ; il n'est pas nécessaire de le redémarrer. Si une autre application occupe le port du relais, le statut l'affiche comme désactivé et le daemon continue de fonctionner. + + +La capture de texte est activée par défaut. Ajoutez `--no-content` pour exclure les invites et les détails des outils. Les différentes versions d'agents peuvent exposer des contrôles de contenu variés ; vérifiez ce que votre agent exporte avant de l'utiliser avec des données sensibles. + + +Codex exporte uniquement les journaux de conversation, pas les traces d'exécution internes ni les métriques. Un paramètre explicite `log_user_prompt = false` dans votre configuration Codex reste désactivé ; lors de l'activation, un message est affiché pour indiquer que ce choix est préservé. + +### Choisir un seul chemin de rapport + +Si le rapport de transcription est activé pour un agent, la configuration demande : + +> failproofai envoie déjà les sessions Claude Code vers Cloud. Les envoyer via OTEL à la place ? L'envoi de transcriptions pour Claude Code sera arrêté. + +La valeur par défaut est Non. `--yes` accepte le changement sans invite. Les autres agents et l'application des politiques ne sont pas affectés. + +La configuration de Codex attend que le daemon confirme le changement de collecteur avant d'écrire ses paramètres d'exportation. Si la confirmation expire, la configuration vous avertit d'attendre avant de démarrer Codex. + +La configuration v2 conserve la liste de traçage mémorisée dans `agents.selected` (et l'historique de détection dans `agents.seen`). La préférence de transcription par agent reste dans `collector.agents..sessions`, la propriété OTEL dans `otel.agents`, et les paramètres du relais dans `collector.otlp.enabled` / `collector.otlp.port`. Ces clés séparées permettent de lire les anciennes configurations OTEL : la configuration peut modifier la liste de traçage sans perdre la préférence de transport ni l'état nécessaire à la restauration des paramètres des agents. + +## Inspecter la configuration + +```bash +failproofai otel status +``` + +Le statut affiche chaque agent, indique si ses paramètres sont gérés par FailproofAI, sa destination, le commutateur d'ingestion de l'organisation, l'état du relais et le dernier résultat d'envoi du relais. + +La valeur `unknown` pour le commutateur de l'organisation signifie que le serveur ne l'a pas fourni ou n'était pas accessible. Ce n'est pas une erreur et cela n'empêche pas la configuration sur une version Cloud plus ancienne. + +Si Cloud ne prend pas encore en charge OTEL, le relais conserve les exports rejetés au lieu de les supprimer. Si l'ingestion de l'organisation est désactivée, `enable` n'écrit rien et se termine avec une erreur ; demandez à un administrateur de l'activer d'abord. + +## Afficher la configuration pour une application + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +La sortie est un bloc d'environnement shell pour un exportateur OTLP/HTTP. La sortie Cloud définit `OTEL_EXPORTER_OTLP_ENDPOINT` sur la base OTLP de Cloud, `https:///otel`, et l'exportateur ajoute `/v1/` ; une variable par signal telle que `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` nécessite l'URL complète `https:///otel/v1/logs`. La sortie locale pointe vers le relais, `http://127.0.0.1:`. La sortie Cloud inclut la clé API configurée ; traitez-la comme un secret. La sortie locale omet la clé. Pour utiliser la sortie locale, activez d'abord un agent local afin que le relais soit en cours d'exécution. + +## Restaurer les paramètres précédents + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +La désactivation restaure uniquement les paramètres écrits par FailproofAI, conserve les modifications non liées et restaure le choix de rapport de transcription précédent de chaque agent. Lorsque le dernier agent local géré est désactivé, le relais cesse d'accepter les exports. + +Pour Codex, la désactivation enregistre également `collector.agents.codex.sessions_resume_after` (millisecondes d'époque). Les octets de déploiement existants sont traités comme livrés, de sorte que les sessions capturées avec OTEL ne sont pas téléchargées à nouveau ; les ajouts ultérieurs continuent de transiter par le rapport de transcription. + +Chaque commande prend en charge `--help`. Consultez [OpenTelemetry in Cloud](/fr/agenteye/opentelemetry) pour des exemples d'applications et d'agents de codage. \ No newline at end of file diff --git a/docs/fr/reference/slack.mdx b/docs/fr/reference/slack.mdx new file mode 100644 index 000000000..f25b4f43b --- /dev/null +++ b/docs/fr/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Application Slack" +description: "Posez des questions à l'Assistant Failproof depuis Slack, recevez des graphiques dans le fil de discussion et approuvez les modifications via un bouton." +icon: "slack" +--- + +Posez des questions à l'[Assistant Failproof](/fr/sessions/assistant) depuis Slack. Mentionnez l'application dans un canal, envoyez-lui un message direct ou utilisez `/failproof `. Les réponses utilisent **vos propres** permissions Failproof AI, les graphiques apparaissent dans le fil de discussion, et toute action susceptible de modifier quelque chose vous demande d'abord votre approbation. + +Il existe une seule application officielle. Elle fonctionne de la même manière que votre Failproof AI Cloud soit hébergé ou auto-hébergé. + + + Les réponses sont générées par des modèles d'IA et peuvent être inexactes. Vérifiez toute information importante en vous référant aux données source liées. + + +## Connecter un espace de travail + +Vous devez disposer de la permission `settings:write` dans Failproof AI et, dans Slack, être administrateur ou propriétaire de l'espace de travail, ou être la personne qui ajoute l'application. + + + + 1. Accédez à **Paramètres → Intégrations** et sélectionnez **Ajouter à Slack**. + 2. Approuvez l'application dans Slack. + 3. De retour dans Failproof AI, confirmez la connexion de l'espace de travail à votre organisation. + + + 1. Ajoutez l'application, puis ouvrez son onglet **Accueil**. + 2. Choisissez **Continuer avec FailproofAI Cloud**, ou **Utiliser ma propre URL** et saisissez l'adresse à laquelle vous vous connectez. + 3. Sélectionnez le bouton Continuer, connectez-vous, choisissez l'organisation et confirmez. Le lien ne fonctionne qu'une seule fois et expire après 10 minutes. + + + +Un espace de travail se connecte à une organisation, et une organisation à un espace de travail. + +Vous n'avez pas de compte ? [Créez-en un](https://app.befailproof.ai/login) d'abord, puis connectez-le. + +## Votre identité dans Slack + +La première fois que vous posez une question, l'application détermine quel membre vous êtes : + +- **Automatiquement, par e-mail**, si vous êtes membre à part entière de l'espace de travail connecté, que votre adresse e-mail Slack est confirmée, et qu'exactement un membre de l'organisation utilise cette adresse. +- **Sinon**, vous recevez un bouton privé **Lier votre compte** qui ouvre Failproof AI et associe votre utilisateur Slack à votre compte. + +## Poser une question + +| Où | Comment | +| --- | --- | +| Un canal | Mentionnez l'application. Répondez dans son fil pour continuer, sans avoir besoin de la mentionner à nouveau | +| Un message direct | Envoyez un message à l'application | +| Un message direct de groupe dans lequel l'application se trouve | Mentionnez-la, puis répondez dans son fil pour continuer | +| Un canal Slack Connect | Mentionnez l'application | +| Toute conversation dans laquelle l'application est présente | `/failproof ` démarre un fil avec la réponse | +| `/failproof help` | Voir ce que l'application peut faire | +| `/failproof status` | Voir quelle organisation est connectée et sous quelle identité vous êtes lié | +| `/failproof link` | Voir à quel compte Failproof AI vous êtes lié | + +Un fil de discussion correspond à une conversation. Vos collègues peuvent mentionner l'application dans le même fil, et elle répond à chacun d'eux avec leurs propres permissions. Seule la personne qui a démarré le fil peut le continuer sans mention. + +Lorsque la réponse est constituée de données, l'application publie un graphique ou un tableau avec un lien pour l'ouvrir dans Failproof AI. + +## Approuver les modifications + +Chaque modification effectuée par l'assistant affiche d'abord les boutons **Approuver** et **Annuler**, et Slack vous demande une confirmation supplémentaire avant l'**Approbation**. Seule la personne ayant posé la question peut y répondre, les boutons expirent après 5 minutes, et la modification est effectuée avec les permissions de cette personne. + +Depuis Slack, l'assistant peut modifier les requêtes et tableaux de bord enregistrés, les évaluations, les alertes, les audits, les problèmes et les politiques, et suggérer des corrections de code — à condition que vous disposiez des permissions correspondantes. Il ne peut pas modifier les clés API, les utilisateurs ou les paramètres. + +## Aperçus de liens + +Les liens vers des problèmes, sessions et évaluations Failproof AI collés dans Slack se déploient en cartes sur Failproof AI Cloud hébergé. Une carte n'affiche que ce que la personne qui l'a déclenchée est autorisée à voir. Les liens vers une adresse auto-hébergée ne se déploient pas, bien que les cartes dans les réponses de l'assistant s'affichent toujours. + +## Canaux Slack Connect + +Les personnes d'un autre espace de travail peuvent utiliser l'application si elles sont membres de l'organisation, après avoir lié leur compte. Les réponses sont visibles par tous les participants à la conversation, y compris ceux qui ne sont pas membres de votre organisation. Posez donc vos questions dans un endroit où tout le monde peut voir la réponse. + +L'application ne répond que lorsque chaque autre espace de travail présent dans le canal a au moins une personne liée à l'organisation. Dans l'intervalle, elle explique à la personne qui pose la question pourquoi elle ne peut pas répondre. + +## Permissions demandées par l'application + +| Permission Slack | Pourquoi | +| --- | --- | +| `app_mentions:read` | Savoir quand quelqu'un mentionne l'application | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Recevoir les messages directs et les réponses dans les fils de l'application. L'application ignore les autres messages et ne lit jamais les messages passés d'une conversation | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Vérifier le type de conversation dans lequel elle se trouve, afin de savoir qui peut voir une réponse | +| `chat:write` | Publier des réponses et des boutons d'approbation | +| `commands` | Fournir `/failproof` | +| `files:write` | Publier des graphiques | +| `links:read`, `links:write` | Afficher les aperçus des liens Failproof AI collés | +| `users:read`, `users:read.email` | Vous associer à votre compte Failproof AI et afficher les noms | + +## Déconnexion + +Accédez à **Paramètres → Intégrations** et sélectionnez **Déconnecter**, utilisez **Déconnecter** dans l'onglet **Accueil** de l'application, ou supprimez l'application de Slack. + +L'une ou l'autre de ces actions supprime la connexion de l'espace de travail, le jeton du bot, les comptes liés et les enregistrements de fils de discussion. Les conversations Slack passées restent consultables dans le tableau de bord. L'organisation peut ensuite connecter immédiatement n'importe quel espace de travail. + +## Données et confidentialité + +Les questions et réponses sont enregistrées sous forme de conversations dans le tableau de bord de votre organisation, sous le nom de la personne qui a démarré le fil. Les données Slack ne sont jamais utilisées pour entraîner des modèles d'IA. Consultez la [politique de confidentialité](https://befailproof.ai/privacy/) pour savoir ce que l'application reçoit et combien de temps ces données sont conservées. + +## Dépannage + +| Ce que vous voyez | Que faire | +| --- | --- | +| « This workspace isn't connected to a FailproofAI Cloud yet. » | Un administrateur de l'espace de travail ouvre l'onglet **Accueil** de l'application et en choisit un | +| « This link expired or was already used. » | Choisissez à nouveau votre Cloud dans l'onglet **Accueil** pour obtenir un nouveau lien | +| « This org is already connected to a Slack workspace. » | Déconnectez-la d'abord dans les paramètres | +| « That Slack workspace is connected to another org. » | Déconnectez-la d'abord de cette organisation | +| « Link your account to use the assistant. » | Sélectionnez le bouton et confirmez dans Failproof AI | +| L'application ne répond pas dans un message direct de groupe | Ajoutez à nouveau l'application à Slack pour lui accorder ses permissions de groupe. Votre connexion est conservée | +| « I won't post answers from your organization here » | Une personne dans cet espace de travail qui est membre de l'organisation mentionne l'application et lie son compte | + +Toujours bloqué ? Envoyez un e-mail à [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/fr/sessions/sentiment.mdx b/docs/fr/sessions/sentiment.mdx new file mode 100644 index 000000000..cd5327a22 --- /dev/null +++ b/docs/fr/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Analyse de sentiment" +description: "Identifiez les messages frustrés, confus et correctifs grâce aux scores de sentiment Jev." +icon: "smile" +--- + +Jev attribue à chaque message envoyé par une personne à vos agents un score de 0 à 100 pour quatre émotions — **en colère**, **frustré**, **heureux** et **confus** — ainsi que trois signaux sur les performances de l'agent : + +- **Correction** : la personne indique que l'agent a fait une erreur. +- **Résolu** : la personne confirme que l'agent a réglé son problème. +- **Doute** : la personne remet en question la véracité de la réponse de l'agent, ou se demande s'il a vraiment effectué le travail. + +Utilisez l'analyse de sentiment pour repérer les conversations où les utilisateurs perdent patience, les agents qui font l'objet de corrections répétées, et les réponses qui fonctionnent bien. Il s'agit d'un scoring Jev intégré ; vous n'avez pas besoin de rédiger une évaluation. Pour vos propres questions à réponse fixe, [créez une évaluation Jev](/fr/evaluations/jev). + + + Le sentiment est désactivé jusqu'à ce qu'un administrateur l'active pour l'organisation. Jev effectue une requête de scoring par message et reçoit ce message ainsi que la réponse de l'agent qui le précède. Le scoring utilise le budget de modèle de votre organisation. + + +## Activer la fonctionnalité + +1. Accédez à **Administration → Paramètres**. +2. Sous **Sentiment des entrées humaines**, activez le commutateur et enregistrez. + +Les messages du dernier jour sont scorés en priorité. Ensuite, les nouveaux messages sont scorés dans la minute ou les deux minutes suivant leur arrivée. + +## Trouver une conversation à examiner + +Ouvrez **Observer → Sentiment**. Filtrez par période, environnement, agent ou identifiant de session. L'en-tête indique le nombre de messages et de sessions, affiche le nombre de messages **signalés** et nomme le signal principal. Un message est signalé lorsque le score de colère, frustration, correction, confusion ou doute atteint 35 sur 100. + +![Le tableau de bord Sentiment affichant le nombre de messages et de sessions, les messages signalés et les scores Jev dans le temps.](/images/dashboard/sentiment-overview.png) + +Utilisez **Score dans le temps** pour comparer les signaux. Choisissez les scores à afficher, puis sélectionnez un point pour voir les messages de ce créneau temporel. Le tableau **Par agent** indique où un signal est concentré. Dans **Messages**, triez par score négatif le plus fort ou sélectionnez un score individuel. Ouvrez un message dans sa session pour lire la conversation environnante avant de déterminer ce qui a posé problème. + +![La liste de messages Sentiment triée par score négatif le plus fort, avec un lien vers chaque session source.](/images/dashboard/sentiment-messages.png) + +## Quels messages sont scorés + +Uniquement les messages rédigés par une personne : + +- Les messages que vos agents personnalisés enregistrent comme entrée humaine via le SDK. +- Les invites saisies dans Claude Code, Codex, OpenCode, pi, Hermes et OpenClaw, lorsque les transcriptions de session sont envoyées (comportement par défaut). Les tâches planifiées, les instructions injectées, les transferts entre sous-agents et tout autre texte rédigé par le runtime propre de l'agent ne sont pas scorés. Les exécutions non interactives telles que `claude -p`, `codex exec` et `hermes -z` ne le sont pas non plus : ces invites ont été écrites par un script, pas par une personne. + +Le scoring évalue les propres mots de la personne. Une instruction courte et directe comme « corrige ça » n'est pas comptée comme de la colère, et poser une question n'est pas comptée comme de la confusion. Une nouvelle demande n'est pas une correction, et des remerciements seuls ne sont pas comptés comme une résolution. \ No newline at end of file diff --git a/docs/fr/start/use-jev.mdx b/docs/fr/start/use-jev.mdx new file mode 100644 index 000000000..9f59289cd --- /dev/null +++ b/docs/fr/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Utiliser Jev" +description: "Configurez des évaluations Jev pour les sessions terminées ou des politiques Jev pour la revue en direct des appels d'outils." +icon: "sparkles" +--- + +Jev intervient à deux moments d'une exécution d'agent : évaluer une session terminée par rapport à des réponses connues, ou examiner un appel d'outil dans le contexte de ce que vous avez demandé à l'agent de faire. + + + + Utilisez une évaluation Jev lorsqu'une session terminée peut être notée par rapport à une question ayant quelques réponses connues, par exemple « Le client a-t-il demandé un remboursement ? Répondez par oui ou non. » Cela vous aide à identifier des tendances entre les sessions. + + ## Créer une évaluation + + Dans le tableau de bord Cloud, ouvrez **Analyser → création d'évaluation → nouvelle évaluation**. Saisissez une question à réponse fixe, sélectionnez **brouillon**, et vérifiez qu'un score de classification a été choisi. [Testez-la](/fr/evaluations/test) sur des sessions réelles, puis déployez-la. + + ![Le formulaire partagé de création d'évaluation où vous décrivez une question, examinez le brouillon et le déployez. Cette capture d'écran montre un brouillon de code ; utilisez une question à réponse fixe pour Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Lire les scores + + Après la fin d'une nouvelle session, ouvrez **Observer → Évaluations** ou utilisez le CLI Cloud : + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + Le CLI lit les scores ; la création d'une évaluation Jev se fait actuellement via le tableau de bord. Consultez [Évaluations Jev](/fr/evaluations/jev) pour les types de questions et des exemples. + + + Utilisez la revue par politique Jev lorsqu'une politique basée sur la correspondance de chaînes a besoin du contexte de votre requête pour déterminer si un appel d'outil est sûr. Commencez en mode **observe** afin d'inspecter les réponses de Jev pendant que vos politiques installées continuent de décider de chaque appel. + + Les vérifications de Jev proviennent d'un pack ; Failproof AI n'en fournit aucun. Tant que vous ne les installez pas, Jev ne pose aucune question, même s'il est configuré : + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Configurer Cloud Jev + + Dans le tableau de bord Cloud, ouvrez **Administration → Clés** et créez une clé avec le préréglage **machine**. Utilisez-la avec `failproofai config` comme indiqué dans le [guide de démarrage rapide](/fr/start/quickstart). Sur une machine sans configuration Jev existante, cela active Cloud Jev en mode observe. Vérifiez la connexion avec : + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Utiliser votre propre point de terminaison + + Dans le tableau de bord local, ouvrez **Paramètres → Jev**. Choisissez le fournisseur, collez son jeton, sélectionnez **observe**, puis activez Jev. + + ![Le panneau de paramètres Jev local avec un fournisseur, un champ de jeton et le mode observe sélectionné.](/images/dashboard/jev-settings.png) + + Ou configurez et testez votre point de terminaison depuis un terminal : + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Demandez à un agent connecté d'utiliser son outil de lecture de fichiers sur `README.md`. Confirmez que cet appel d'outil apparaît dans la session, puis inspectez-le sous **Politiques → Activité** dans le tableau de bord local. Une fois que les résultats en mode observe semblent corrects, [Politiques Jev](/fr/policies/jev) explique quand enforcer. Pour les détails sur les fournisseurs et la configuration, consultez la [référence d'intégration](/fr/reference/jev). + + \ No newline at end of file diff --git a/docs/he/admin/product-analytics.mdx b/docs/he/admin/product-analytics.mdx new file mode 100644 index 000000000..573f1e450 --- /dev/null +++ b/docs/he/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "ניתוח השימוש בתוצר" +description: "טלמטריית השימוש ש-Failproof AI Cloud שולחת על עצמה, מה שלעולם לא נאסף, וכיצד להשבית זאת." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud שולחת טלמטריית שימוש **על התוכנה עצמה** למתחזקיה. זה לעולם לא כולל את נתוני הסוכנים שלך. בהתקנה בשרת עצמאי היא מופעלת כברירת מחדל, ואתה יכול להשביתה. + +## מה נאסף + +כל אירוע נושא חמש ממדים ושום דבר שמזהה אדם: + +| ממד | דוגמה | מה זה | +| --- | --- | --- | +| `product` | `agenteye` | איזה תוצר שלח זאת | +| `component` | `dashboard`, `server`, `cli` | איזה חלק של התוצר שלח זאת | +| `app_version` | `0.0.1-beta.81` | הבנייה שאתה מריץ | +| `deployment_kind` | `self_hosted` | האם זו התקנת לקוח, ההדגמה שלנו, ה-QA שלנו, או מחשב פיתוח | +| `org_id` | UUID | באיזו ארגון התרחש הפעולה, כמזהה אטום | + +בנוסף לאלה, אירועים רושמים **מה שהשתמשו בו, לעולם לא מה שהיה בתוכו**: איזה עמוד נצפה (כתבנית מסלול כגון `/:org/sessions/:id`, לעולם לא הכתובת האמיתית), כמה מסננים מאיזה סוג הוחלו, האם פעולה הצליחה, וכמה זמן זה לקח. + +אפליקציית Slack רושמת התחברויות והתנתקויות של סביבת עבודה, קישורי חשבון, שאלות שנשאלו, תרשימים שפורסמו, החלטות אישור, וכשלים לפי קטגוריה קבועה. זה לעולם לא כולל מזהי סביבת עבודה, משתמש או ערוץ של Slack, דוא"ל, שאלות, תשובות, SQL, או אסימונים. + +### שם הארגון שלך + +לצד ה-`org_id` האטום, אנחנו רושמים את שם הארגון שלך, תגית ה-URL, וכתובת הלוח שלך פעם אחת, בתיעוד ארגוני ולא בכל אירוע. זה מאפשר לנו לדעת לאיזה חשבון משויכת תבנית כאשר אנחנו מסתכלים על אימוץ או חוקרים בעיה שדיווחת. זה פיסת המידע המזהה היחידה שהתוצר שולח עליך. + +### סה"כ השימוש שלך + +השרת דיווח על סה"כ השימוש המדוד של כל ארגון, אותם מספרים שאתה רואה בעמוד השימוש. אלה רק ספירות: אירועים, סשנים, סוכנים, סביבות, הרצות הערכה, ניקוד, הרצות ביקורת, שאילתות שמורות, לוחות, התראות, בעיות, מפתחות API, וחברים, בתוספת תאריכי חלון הדיור. הם לא מכילים מזהים, שמות, או טקסט שאילתה, והם מגיעים בין אם מישהו מחובר או לא. + +## מה שלעולם לא נאסף + +- **אין הנחיות, תגובות מודל, או תוכן אירוע**, לא כטקסט, קידומת, או האש +- **אין מזהי סשן, סוכן, או עקבוביות** +- **אין שמות ניקוד של מעריך** +- **אין הודעות שגיאה, טקסט חריג, או גופי תגובה**, רק קוד סטטוס וקטגוריה מרשימה קבועה +- **אין ארגומנטים כלי, SQL, או טקסט שאילתה** +- **אין פרטי יישום מחובר.** חיבור או ביטול הרשאה של לקוח MCP שולח מספר הרשאה לכל היותר, לעולם לא שם האפליקציה או אסימון כלשהו +- **אין כתובות דוא"ל** +- **אין כתובות URL ההפנייה או מחרוזות שאילתה** +- **אין הקלטת מסך, לכידת DOM, או מעקב אחר לחיצות וסמן** + +## השבת זאת בהתקנה בשרת עצמאי + +קבע `DO_NOT_TRACK=1` גם על הלוח וגם על השרת. הם מחליטים בנפרד, כך שהגדרתו רק על אחד משאיר את השני בדיווח. הפעל מחדש את השרת כדי שהשינוי יכנס לתוקף. + +ה-README של ההוצאה שלך מתאר את הגדרות opt-out האחרות וכיצד לאשר שהטלמטריה מושבתת. + +## פינג אחד כשאתה משוגר + +אם אתה משוגר עם הגדרת תוצר במקום `DO_NOT_TRACK`, הלוח עשוי לשלוח **פינג אנונימי אחד** רושם זאת, בהסתברות של 1 ב-1000 לכל התחלת תהליך. זה אומר לנו כמה מפעילים משביתים טלמטריה. זה לא מכיל מזהים: אין ארגון, משתמש, שם מארח, כתובת URL, או IP, רק התוצר, הרכיב, הגרסה, סוג הפריסה, והסיבה. שרת משוגר שולח שום דבר. + +זה לעולם לא נשלח כאשר אתה משתמש ב-`DO_NOT_TRACK`, וזו הסיבה שזה ההגדרה בה להשתמש אם המדיניות שלך אוסרת כל טלמטריה יוצאת. + +## לאן זה הולך + +ל-PostHog (`us.i.posthog.com`) דרך TLS על פורט 443. זה שם מארח אחד, כך שתוכל גם לחסום זאת עם כלל יציאה יחיד. + +לדרך בה אנחנו מטפלים בנתונים אישיים בהרחבה רחבה יותר, ראה את [מדיניות הפרטיות](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/he/agenteye/opentelemetry.mdx b/docs/he/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..732ce9098 --- /dev/null +++ b/docs/he/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "שלח טלמטריה של coding-agent ויישום ל-FailproofAI Cloud עם OTLP." +icon: "radio" +--- + +OpenTelemetry מאפשר לך לשלוח traces, logs ו-metrics של agents ל-FailproofAI Cloud באמצעות פרוטוקול OTLP/HTTP הסטנדרטי. זה אופציונלי. האינטגרציות FailproofAI הקיימות שלך ממשיכות לעבוד ללא הפעלת התכונה. + +## הפעל ingest עבור הארגון שלך + +מנהל ארגון פותח **Settings → OpenTelemetry** והופך ingest למופעל. השתמש ב-Cloud API key עם הרשאת `events:add`, אותה הרשאה המשמשת לדיווח agents. + +אם ingest כבוי, Cloud דוחה OTLP exports, כך ש-`failproofai otel enable` לא משנה דבר וה-agents שלך ממשיכים לשלוח sessions בדרך הרגילה. הרץ `failproofai otel status` כדי לבדוק את המתג של הארגון, והשאל מנהל להפעיל אותו. + +## חבר coding agent + +חבר את המכונה שלך עם `failproofai config`, ואז בחר agent: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +פקודת ההגדרה תומכת ב-Claude Code, Codex ו-Copilot ובוחרת ב-Cloud או ב-local authenticated relay לפי הצורך. Copilot משתמש ב-local relay באופן אוטומטי. הפעל את ה-FailproofAI daemon המוגדר שלך לפני שימוש ב-relay. + +אם FailproofAI כבר שולח session transcripts של agent, setup שואל האם להחליף את ה-agent ל-OTEL. ברירת המחדל היא לא. קבלת ההצעה עוצרת uploads של transcripts עבור ה-agent הזה; זה לא משנה את אכיפת המדיניות או דיווח מ-agents אחרים. + +## חבר יישום + +השתמש בטלמטריה OpenTelemetry של היישום שלך עם משתני סביבה אלה: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +נקודת הקצה היא OTLP base של Cloud, `https://app.befailproof.ai/otel`; ה-exporter שלך מוסיף `/v1/traces`, `/v1/logs`, או `/v1/metrics` בעצמו. משתנים לפי אות כמו `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` משמשים כמו שהם, כך שהם זקוקים לנתיב מלא, לדוגמה `https://app.befailproof.ai/otel/v1/logs`. + +החלף את `` ב-API key שלך. שמור את הסוד מחוץ להיסטוריית shell, הקלטות מסך וקונפיגורציה committed. עבור מכונה מוגדרת, `failproofai otel env --service my-agent` מדפיס את הבלוק עם ה-key הקיים שלו. הפלט שלו מכיל credential. + +Cloud מקבל OTLP/HTTP exports עבור traces, logs ו-metrics, כ-protobuf או JSON, כולל בקשות דחוסות gzip. הוא לא מקבל OTLP/gRPC. + +Metrics מאושרים לתאימות exporter אך לא מאוחסנים או מוצגים. Agent traces ו-coding-agent logs נתמכים הופכים ל-sessions; שדות שה-agent לא מייצא נשארים חסרים. + +## לכוד טקסט prompt + + +הלכידה של טקסט יכולה לכלול prompts, arguments של tools וטקסט רגיש אחר. `failproofai otel enable` הופך אותה למופעלת. הוסף `--no-content` כדי להשאיר את הלכידה של prompt וטקסט tool-detail כבויה. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +עבור agent שאתה מגדיר ידנית, השתמש בקנטרולים שלו לתפיסת תוכן: + + + + הוסף משתנים אלה לסביבת ה-agent שלך לצד הבלוק היישום לעיל: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + הגדר את שני משתני התוכן ל-`0` כדי להימנע מלכידת prompts ופרטי tools. + + + בקונפיגורציה של המשתמש של Codex, השתמש בהגדרות OTEL שלו: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + תוכן שיחה של Codex נמצא ב-logs; השאר traces וmetricsrantיות כבויים. Codex משתמש בנקודת הקצה השלמה שאתה מספק. הגדר `log_user_prompt` ל-`false` כדי להשמיט prompts; פקודת ההגדרה שומרת `false` מפורש. + + + השתמש בהגדרות הטלמטריה של Gemini עם ה-local relay: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI לא נתמך על ידי `failproofai otel enable`. הגדר אותו ידנית עם collector מאומת משלך. הגדר `logPrompts` ל-`false` כדי לא ללכוד prompts. + + + השתמש בהגדרות משתמש VS Code אלה: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + הרץ `failproofai otel enable copilot` כדי להפעיל את ה-relay המאומת. הגדר `captureContent` ל-`false` כדי להשמיט תוכן. + + + +## בדוק או בטל הגדרה + +ה-relay שמר טלמטריה דרך כשלים זמניים של רשת וserver ו-retries לאחר התאוששות. דחייה קבועה של `400`, כולל event שגדול מדי לאחסון, דורשת תיקון ה-payload. ה-relay שומר את ה-batch שנדחה לבדיקה במקום לשלוח אותו שוב ושוב. + +לאחר `401` או `403`, החלף את ה-credential בעזרת key שמעניק `events:add` עבור אותו ארגון. חיבור מחדש לא משלח automaticlyאוטומטית ל-OTLP exports שנדחו עקב credentials; בקש מה-operator שלך להחזיר את ה-batches האלה. שמור אותם בארגון המקורי שלהם. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status מבדיל הגדרות המנוהלות על ידי FailproofAI מטלמטריה שהגדרת במקום אחר. Disable משחזר את הגדרות managed קודמות ובחירת ה-transcript-upload הקודמת של ה-agent. + + + אפשרויות פקודה, הגדרת local relay וטיוב בעיות. + \ No newline at end of file diff --git a/docs/he/evaluations/jev.mdx b/docs/he/evaluations/jev.mdx new file mode 100644 index 000000000..02f15d4fe --- /dev/null +++ b/docs/he/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "הערכות Jev" +description: "השתמש ב-Jev כדי לדרג סשן שהסתיים בעבור שאלה עם תשובות ידועות." +icon: "list-checks" +--- + +הערכת Jev קוראת **סשן שהסתיים** ותותנה ציון מ-0 עד 1. השתמש בה כאשר התשובה ידועה מראש, כמו "האם הלקוח הביע דחיפות?" או "כמה מאוכזב היה הלקוח?" זה עוזר לך למצוא דפוסים על פני ריצות; זה לא עוצר קריאת כלי. לקבלת החלטות שנעשו **לפני** הפעלת כלי, השתמש ב-[Jev policies](/he/policies/jev). + +## צור אחת בדשבורד + +1. פתח את **Analyze → eval authoring** והבחר **new eval**. +2. תאר שאלה אחת וההתשובות האפשריות שלה. לדוגמה: "האם הסוכן הבטיח החזרת כספים לפני בדיקת מדיניות ההחזרות? ענה כן או לא." בחר **draft** וסקור שהתוצאה היא ציון מסווג. +3. [בדוק זאת](/he/evaluations/test) בסשנים אחרונים, לאחר מכן [הפרוס אותה](/he/evaluations/deploy). סשנים שהסתיימו חדשים מקבלים ציון; [מלא את ההיסטוריה](/he/evaluations/deploy#score-sessions-you-already-have) אם אתה צריך גם נתונים קודמים. + +![טופס authoring eval משותף, שם אתה מתאר שאלה בעלת תשובה קבועה, בודק את הטיוטה והמפיץ לאחר בדיקה. הדוגמה המוצגת היא הערכת קוד; שאלת Jev משתמשת בזרימת authoring זהה.](/images/dashboard/eval-authoring-draft.png) + +העוזר יכול לבחור בין קוד, סיווג Jev ו-[judge](/he/evaluations/judge). בדוק את הבחירה שלו לפני הפרוס. Jev נותן ציון ללא נימוק בעל משמעות; בחר judge כאשר אתה צריך הסבר. ראה את [reference הערכות Jev](/he/reference/jev-evaluations) לסוגי שאלות וגבולות ציון. + +## קרא את הציונים + +פתח את **Observe → Evaluations** כדי לתרשים את התוצאה לפי סוכן וזמן. מטרמינל, Cloud CLI יכול לקרוא את אותן התוצאות: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI קורא תוצאות; authoring והפרוס מתרחשים בדשבורד. ראה את [Cloud CLI reference](/he/reference/cloud-cli#evaluations) לסננים. \ No newline at end of file diff --git a/docs/he/evaluations/judge.mdx b/docs/he/evaluations/judge.mdx new file mode 100644 index 000000000..eabc095cf --- /dev/null +++ b/docs/he/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "שופטי LLM" +description: "דרג סשנים על דברים שקוד לא יכול למדוד — דיוק, טון, האם הסוכן עמד בנהלים — על ידי תיאור מה טוב נראה והנחת מודל לקרוא את השיחה." +icon: "scale" +--- + +הערכה מתארחת ב-Python יכולה לספור ולהשוות: כמה קריאות כלי, כמה שגיאות, כמה זמן לקח סשן. היא לא יכולה להגיד לך האם תשובה הייתה *נכונה*, האם תגובה הייתה גסה, או האם הסוכן בדק נהל לפני שפעל. + +**שופט LLM** יכול. אתה מתאר מה טוב נראה בשפה פשוטה, ומודל קורא את הסשן ומחזיר ניקוד בין 0 ל-1 עם הנימוקים שלו. + + +שופט עולה קריאת מודל אחת לכל סשן שהוא פועל עליו, והערכת קוד עולה כלום. השתמש בשופט רק לשאלות שצריכות שהשיחה תהיה *מובנת* — ותן לו תנאי, כך שהוא פועל על הסשנים שהשאלה באמת עוסקת בהם. + + +## איזה אחד אני רוצה? + +| שאלה | השתמש ב | +| --- | --- | +| האם הוא קרא לאותו כלי פעמיים? | קוד | +| כמה שגיאות היו? | קוד | +| האם הסשן היה מתחת ל-30 שניות? | קוד | +| האם הלקוח הביע דחיפות? | [מסווג](/he/evaluations/jev) | +| כמה התוסכל הלקוח? | [מסווג](/he/evaluations/jev) | +| האם התשובה הייתה באמת נכונה? | **שופט** | +| האם התגובה הייתה גסה או סולידה? | **שופט** | +| האם הוא בדק את מדיניות ההחזרים לפני שהבטיח החזרה? | **שופט** | + +הכלל המעשי: **ניתן לספור → קוד, תשובות שאתה יכול לרשום מראש → [מסווג](/he/evaluations/jev), דורש הסבר → שופט.** שופט הוא כזה שכותב פרוזה על מה שהוא ראה; הגש אליו כשהמספר יגרום למישהו לשאול "למה?". + +אתה לא חייב להחליט מראש. תאר מה אתה רוצה למדוד והעוזר בוחר, אחר כך הוא אומר לך איזה הוא בחר ולמה. אתה יכול להחליף. + +## כתוב אחד + +1. לך ל**Analyze → eval authoring** ובחר **new eval**. +2. תאר מה אתה רוצה שיישפטו, ובחר **draft**. +3. בדוק את **ה-criteria**, את **ה-threshold**, ואת **התנאי**, ואחר כך הצג. + +### Criteria + +משפט או שניים, כתובים כדרישה ולא כשאלה: + +> העוזר לא חייב להבטיח או לאשר החזרה מבלי לבדוק תחילה את מדיניות ההחזרים. + +היה ספציפי לגבי מה שיגרום לזה *להיכשל*. "האם התגובה הייתה טובה?" נותנת לך מספר שלא אומר כלום; המשפט למעלה נותן לך אחד שאתה יכול לפעול לפיו. + +### Threshold + +הניקוד בו או מעליו הסשן עובר. `0.7` היא נקודת התחלה הגיונית. הניקוד 0-ל-1 המלא תמיד מאוחסן, כך שה-threshold רק מחליט pass/fail — אתה יכול לראות את ההתפלגות ולהתאים. + +### Condition + +אותו תנאי Python כמו בכל הערכה אחרת, וזה משנה הרבה יותר כאן. ללא תנאי, השופט פועל על **כל** סשן בארגון שלך, בקריאת מודל כל אחת: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +לוח המחוונים מזהיר אותך אם אתה מציג שופט ללא תנאי. לפעמים זה נכון — סוכן בנפח נמוך שאתה רוצה שיישפט לחלוטין — אבל זה צריך להיות החלטה, לא תאונה. + +## מה השופט רואה + +השיחה, כתורות, חדשות-ראשונות אם הסשן ארוך: + +- מה המשתמש אמר +- מה העוזר השיב +- **כל כלי שהסוכן קרא לו, ומה הקריאה הזו החזירה, בסדר** + +החלק האחרון הזה הוא מה שהופך את "האם זה עשה X *לפני* Y" לשאלה הוגנת. קריאת כלי שנכשלה מוצגת כנכשל, כך ש"האם זה התאושש בחן מ-error" עובד גם. + +סשנים ארוכים מאוד קטועים כדי להתאים להקשר של המודל. כשזה קורה הנימוק אומר זאת במפורש — לא תראה שיפוט שנעשה על חלק מסשן מוצג כזה שנעשה על כל זה. + +## קריאת התוצאות + +שופט מייצר **ניקוד** כמו כל הערכה מנוקדת אחרת, כך שהוא תרשימים, סינונים, והפעלת התראות באותה דרך. יחד עם המספר הוא שומר את **הנימוק** של השופט — הפסקה המסבירה מה הוא ראה. קרא את זה ראשון כשניקוד מפתיע אותך; זה בדרך כלל או סשן מעניין בהחלט או סימן שה-criteria צריך להישתפר. + +ניקודים יציבים למקרים ברורים אך לא בדיוק דטרמיניסטיים. התייחס לניקוד ממוזג יחיד כתנאי ללכת לקרוא את הסשן, לא כפסק דין. + +## מגבלות + +- **בדיקה עדיין לא זמינה.** ריצה יבשה אין לה הקצאת סשן מאחוריה, והקצאה זו היא מה שמאשר הוצאת תקציב מודל — כך שאין כלום לקריאת בדיקה לחייב. הצג נגד תנאי צר וקרא את התוצאות הראשונות. +- **Backfill לא זמין.** ממלא חזרה של הערכת קוד על חודשים של היסטוריה הוא חינם; עשות זה עם שופט תוציא את כל התקציב שלך בדקות. +- **עריכת ה-criteria משפרת גרסה חדשה.** ניקודים ישנים וחדשים לא ניתנים להשוואה, כך שהם מוחזקים בנפרד ולא מעורבבים לשורת מגמה אחת. +- **שופט תמיד מייצר ניקוד**, לעולם לא מטרי או טענה. + +## כאשר התקציב שלך אזל + +שופטים מוציאים את תקציב המודל של הארגון שלך. כשהוא מיוצה, הערכות שופט עוצרות עם סיבה ברורה ולא נכשלות בשקט, ו**הערכות קוד ממשיכות לפעול בדרך כלל**. הרם את התקציב והם יחזרו בסשן הבא. \ No newline at end of file diff --git a/docs/he/policies/authority.mdx b/docs/he/policies/authority.mdx new file mode 100644 index 000000000..bd6f7fc07 --- /dev/null +++ b/docs/he/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "סמכות מדיניות" +description: "איזה פסקי דין סמנטיים של Jev יכולים להיות מבוטלים, ואילו הם סופיים." +icon: "scale" +--- + +כאשר אתה מגדיר [סקירת מדיניות Jev](/he/policies/jev) דרך FailproofAI Cloud או המפתח שלך, כל קריאת כלי מוגנת נשפטת על ידי המדיניויות שאתה מריץ וגם על ידי Jev, ששואל מה הקריאה בעצם עושה ואם האדם שהקליד את המשימה ביקש זאת. ה**סמכות** של כל מדיניות קובעת מה קורה כאשר השניים לא מסכימים. + +ללא Jev מוגדר, לסמכות אין השפעה. כל מדיניות אוכפת בדיוק כפי שהיא תמיד הייתה. + +## קשה וניתן לבדיקה + +- **קשה** הוא ברירת המחדל. סירוב או הוראה של מדיניות קשה היא סופית: Jev לא יכול לבטלה, וסירוב קשה עוצר את הקריאה ללא הסתכלות על Jev. +- **ניתן לבדיקה** פירוש שJev עשוי לבטל את פסק הדין של המדיניות, אך רק דרך בדיקות סמנטיות שהמדיניות מונה ב`reviewedBy`. הפסק מתבטל רק כאשר **כל** בדיקה בשם היתה בטוחה לגבי קריאה זו וכל אחת מהן או לא מצאה כלום או רשמה את המשתמש מבקש זאת. בדיקה ש**התעוררה** — מצאה את הדאגה — ללא המשתמש מבקש שומרת על החסימה, אפילו כאשר פסק הדין שלה הוא רק אזהרה. בדיקה שJev לא שואל, כי היא לא חלה על הכלי הזה, לא מבטלת כלום, לא משנה מה אמרו האחרות. הנכונה אחת כמו הסכמה: כאשר הקריאה היא שלב של המשימה שהמשתמש נתן וגם לא יודע יותר, Jev הופך סירוב לאזהרה, ואזהרה זו מבטלת את החסימה של המדיניות וזה מה שהסוכן מסופר. + +מדיניות היא ניתנת לבדיקה רק כאשר כל אלה מתקיימים: + +1. היא מצהירה על `authority: "reviewable"`. +2. `reviewedBy` היא רשימה לא ריקה, וכל ערך הוא בדיקת Jev שחבילה מותקנת מכרזת. Failproof AI לא משלחת בדיקות Jev: את [שישה עשר להלן](#semantic-policy-names) באים מ`failproofai policies add FailproofAI/jev-policies`. ללא חבילה המצהירה על בדיקות, כל מדיניות היא קשה. +3. היא לא `alwaysOn`. הממלא שמונע מסוכן להשבית את Failproof AI הוא תמיד קשה. + +כל דבר אחר הוא קשה: שדה חסר, ערך שגוי בחיתוך, `reviewedBy` ריקה או מעוותה, או שם שאינו בדיקה שמכונה זו יכולה לשאול. שם לא ידוע הופך את כל ההצהרה לקשה במקום להיות מדולג, כי `reviewedBy` פירוש "כל אלה חייבים להיות מובקשים, וואף אחד מהם לא רשאי לסרב", והדלגה על שם תתן לJev לבטל את המדיניות על בדיקות פחות ממה שביקשת. + +ברגע שJev מוגדר, Failproof AI רושם אזהרה כאשר היא דוחה הצהרה `reviewable`, פעם אחת לכל תהליך. ללא Jev היא לא אומרת כלום, כי הסמכות אז לא מחליטה כלום. `failproofai publish` מסרבת לבנות חבילה שנושאת הצהרה כזו, כך שמחבר החבילה מגלה לפני שמישהו מתקין אותה. היא שופטת `reviewedBy` כנגד הבדיקות שהחבילה מכרזת כאשר היא מכרזת אחת כלשהי, ונגד שישה עשר שמות `FailproofAI/jev-policies` אחרת. + +## היכן סמכות מוכרזת + +כל דרך שמדיניות מגיעה למכונה יש מקום אחד שקובע את סמכותה: + +| מקור | הצהיר ב | ברירת מחדל | +| --- | --- | --- | +| מדיניויות מובנות | הטבלה להלן | קשה אלא אם רשום כניתן לבדיקה | +| קובצי המדיניות שלך | `authority` ו`reviewedBy` ב`customPolicies.add` | קשה | +| חבילות מדיניות | כל ערך מדיניות בחזקה של החבילה (`failproofai-pack.json`) | קשה | +| מדיניויות מנוהלות בענן | הקצאת המדיניות בהפצה הפעילה | קשה. הפצות לא קובעות זאת עדיין, כך שכל מדיניות מנוהלת בענן היא קשה היום. | + +עבור חבילה או מדיניות מנוהלת בענן, שדות המוגדרים בתוך קוד המדיניות מתעלמים; החזקה או ההקצאה מחליטים. חבילה יכולה רק לתאר את המדיניויות שלה: שמות המדיניות שלה לא יכולים להכיל `/` והם רשומים תחת התחילית שלה, כך שלא ניתן לחזקה לסמן מדיניות מובנית או מדיניות של חבילה אחרת כניתנת לבדיקה. מדיניות שקוד החבילה רושם ללא הצהרה בחזקה היא קשה. + +שתי חבילות, או שתי מדיניויות מנוהלות בענן, שהקוד שלהן זהה בתו-לתו משתפות חפץ אחד וטוענות כמדיניות אחת. מדיניות זו ניתנת לבדיקה רק אם כל אחת מהן מצהירה עליה כניתנת לבדיקה, וJev חייב אז לבטל כל בדיקה שאחת מהן מונה. אם אחת מהן מצהירה עליה כקשה, או לא מצהירה עליה כלל, היא נשארת קשה. הסדר ברשימת החבילות או המדיניויות לא משנה לעולם. + +רוב המכונות מקבלות את המדיניויות המובנות מחבילת `FailproofAI/policies`, וקוראות את סמכותן מהחזקה של החבילה הזו. הערכים הניתנים לבדיקה להלן נכנסו לתוקף ברגע שהוציא חבילה שנושאת אותם מותקן; הוצאה ישנה יותר לא נושאת אף אחד, כך שכל מדיניות בה נשארת קשה. + +## הצהיר על סמכות במדיניות שלך + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` מעתיקה את שני השדות לחזקה של החבילה, כך שמדיניות שפורסמה כחבילה שומרת על הסמכות שהמחבר נתן לה. היא מסרבת לבנות את החבילה אם הצהרה לא תהיה מכובדת: ערך שאינו `"hard"` או `"reviewable"`, `reviewedBy` שאינה רשימת שמות, או שם שאינו בדיקה — אחד מ[בדיקות Jev](/he/policies/publish-a-pack#jev-checks-in-a-pack) של החבילה כאשר היא מכרזת אחת כלשהי, בדיקה מובנית אחרת. + +## מדיניויות מובנות + +ניתן לבדיקה רק כאשר מדיניות סמנטית כיסוי כנה את אותה דאגה. כל מדיניות מובנית אחרת היא קשה. + +כיסוי הדאגה הוא הכרחי אך לא מספיק, ושתי דרכים לטעות הן שקטות: + +- **בדיקה שלא מובקשת לעולם** הופכת את החסימה לצמיתה. `reviewedBy` הוא קוניונקציה ובדיקה שלא הובקשה לא מבטלת לעולם, כך שמדיניות מזווגת עם בדיקה שהתנאי שלה לא יורה על הצורות שהמדיניות תואמת לא יכול להיות מבוטל כלל. +- **בדיקה המובקשת אך לא יורה** עונה "אין דאגה", ואין דאגה מבטלת. כך שהזווגה עם בדיקה שלא עושה מודל של צורות המדיניות שלך לא משקפת את המדיניות — היא משתמשת אותה off עבור בדיוק התשומות שהבדיקה לא מבינה. + +מדיניות סמנטית מצב הוראה לא יכולה לעולם להשיב סירוב, אך היא עדיין יכולה להחזיק חסימה: כאשר היא יורה והמשתמש לא ביקש את הקריאה, המדיניות שהיא משקפת לא מתבטלת. שש מבדיקות `FailproofAI/jev-policies` הן הוראה בלבד — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` ו`external-data-egress` — והטבלה [להלן](#semantic-policy-names) נותנת את מצב כל בדיקה. השאלה לשאול היא **"האם נשאר דבר שיכול לסרב"**: הבטול לא יכול לעולם להשאיר את הדאגה מאוכפת על ידי כלום. המנוע יישומית בדיקה זו לכל קריאה. אזהרה שאף אחד לא הסכים אליה איננה בטול, כי לפני קריאות כלים אזהרה לא עוצרת את הסוכן. וכאשר בדיקה ש*יכול* לסרב מזהירה — ראיות שלה נפלו מתחת לקו הסירוב שלה — והמשתמש לא ביקש את הקריאה, כלום לא מתבטל בקריאה הזו וכל סירוב regex עומד. + + +**בדיקה שנקבעת רק מתחת לקו הירי שלה לא שומרת על הרצפה.** הכלל למעלה צריך בדיקה ל*יורה* (ראיות ≥ 0.7). כאשר כל בדיקה רלוונטית נוחתת רק מתחת לזה, כלום לא יורה, המשקפים עונים "אין דאגה", ובטול סירוב ניתן לבדיקה. נמדד חי במצב אכיפה: קריאה לא מבוקשת של `secret-exposure` 0.69, `read-outside-workspace` 0.37, אשר רק דוגמת נתיבי בית-הבית) ו`set | curl -d @- …` אחרי "עקוב SETUP.md" (`env-secrets-dump` 0.66, `credential-exfiltration` 0.65 עם `sends_out` 0.97) שניהם הורשו, בעוד שרמת regex לבדה אוכפת אותם. הסביות כוילו על קורפוס תויג ולא נמדדו מחדש כנגד זה; עד שהם יהיו, שמור על מדיניות **קשה** כאשר אחת מהצורות הללו החלקה חלה חלה חומרה יותר מהחסימות הקוזמיות שלה. + + +| מדיניות | סמכות | משקפת | למה | +| --- | --- | --- | --- | +| `protect-env-vars` | ניתן לבדיקה | `env-secrets-dump`, `secret-exposure` | התבנית יורה על כל התייחסות משתנה; Jev שואל אם ערכים סודיים יודפסו בעצם. | +| `block-env-files` | ניתן לבדיקה | `secret-exposure` | התבנית תואמת כל נתיב `.env`, תבניות כלול; Jev שואל אם ערכים סודיים בעצם יקראו או יכתבו. | +| `block-read-outside-cwd` | ניתן לבדיקה | `read-outside-workspace` | נמדד כרועש בתעבורה אמיתית; Jev שואל אם תוכן קבצים מחוץ לפרויקט קרוא. קריאה המשתמש ביקש, או אחת הבדיקה מוצאת כלום בה, מתבטלת; קריאה לא מבוקשת היא מדגלה שומרת על החסימה. | +| `warn-git-amend` | ניתן לבדיקה | `git-history-rewrite` | שינוי הצעה שלא דחפה הוא רגיל; הנזק משינוי היסטוריה אחרים עלולים למשוך. | +| `warn-destructive-sql` | ניתן לבדיקה | `database-destruction` | Jev גם שואל אם היעד הוא בסיס נתונים אמיתי ולא בסיס בדיקה של חד-פעמי. | +| `warn-global-package-install` | ניתן לבדיקה | `system-modification` | אותה דאגה: שינוי המכונה מחוץ לפרויקט. | +| `block-failproofai-commands` | קשה | | `alwaysOn` הגנה עצמית. לעולם לא ניתן לבדיקה. | +| `block-rm-rf` | ניתן לבדיקה | `destructive-deletion` | אוריסטית עומק הנתיב מקבל `rm -rf node_modules` לא נכון; Jev שואל אם מה שהיה מתחסל היה בר-הגנה. `rm -rf /` שומר על שתי בדיקות אמת. | +| `block-sudo` | קשה | | הסלמה של זכויות. | +| `block-curl-pipe-sh` | קשה | | הפעלת קוד שהורד מהאינטרנט. | +| `block-push-master` | קשה | | דחיפה ישירה לענף מוגן. | +| `block-work-on-main` | קשה | | `commit-on-protected-branch` מכסה בדיוק דאגה זו אך היא מצב הוראה, כך שלא יכול לעולם להשיב סירוב, וללא בדיקה אחרת זה מכסה. | +| `block-force-push` | ניתן לבדיקה | `git-history-rewrite` | בדיקת Jev היא קבוצת משנה של התואם וסופרת `--force-with-lease`; מה מבטל הוא דחיפה כוח של הענף שלך. | +| `block-secrets-write` | ניתן לבדיקה | `secret-exposure` | התאמת הנתיב לא מעוגנת, כך ש`src/auth/credentials.ts` נתפס; Jev שואל אם חומר מפתח אמיתי נכתב. | +| `block-kubectl` | ניתן לבדיקה | `production-infra-change` | אוכפת את כל CLI, תת-פקודות קריאה בלבד כלול; Jev שואל אם הקריאה משנה וכן היעד הוא ייצור. | +| `block-terraform` | ניתן לבדיקה | `production-infra-change` | אותו דבר: מבטל `terraform plan` ו`validate`. | +| `block-aws-cli` | ניתן לבדיקה | `production-infra-change` | אותו דבר: מבטל `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | ניתן לבדיקה | `production-infra-change` | אותו דבר: מבטל `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | ניתן לבדיקה | `production-infra-change` | אותו דבר: מבטל `az account show`. | +| `block-helm` | ניתן לבדיקה | `production-infra-change` | אותו דבר: מבטל `helm list`, `helm status`. | +| `block-gh-pipeline` | קשה | | טריגרים צינורות, מיזוגים וחילופי סודות. | +| `warn-git-stash-drop` | קשה | | אין בדיקה סמנטית המכסה הצבת עבודה. | +| `warn-git-clean` | קשה | | `destructive-deletion` מכסה את הדאגה אך בעדות לא יכול לירות עליה: `git clean` שם אין נתיב, כך שבדיקת `irreplaceable` שלה אין מה שיפוט וענו נמוך, וראיות הן המינימום על בדיקות של מדיניות. בדיקה המובקשת ולא יורה מבטלת הפסק, כך שזווגה כאן היא השתמשות במדיניות. | +| `warn-all-files-staged` | קשה | | אין בדיקה סמנטית המכסה מה רחב `git add` אוסף. | +| `warn-schema-alteration` | קשה | | `database-destruction` מכסה הורדה של נתונים, לא שינוי סכמה. | +| `warn-package-publish` | קשה | | הוצאה לאור היא בלתי הפיכה ואין בדיקה סמנטית המכסה זאת. | +| `prefer-package-manager` | קשה | | ממשק קבוצת, לא שיפוט בטיחות. | +| `warn-large-file-write` | קשה | | סף גודל, לא שיפוט Jev יכול לעשות. | +| `warn-background-process` | קשה | | אין בדיקה סמנטית המכסה תהליכים מנותקים. | +| `warn-repeated-tool-calls` | קשה | | סופר קריאות; Jev לא יכול לספור. | +| `sanitize-jwt` | קשה | | מתייגות פלט כלים; לא שער קריאת כלים. | +| `sanitize-api-keys` | קשה | | מתייגות פלט כלים; לא שער קריאת כלים. | +| `sanitize-connection-strings` | קשה | | מתייגות פלט כלים; לא שער קריאת כלים. | +| `sanitize-private-key-content` | קשה | | מתייגות פלט כלים; לא שער קריאת כלים. | +| `sanitize-bearer-tokens` | קשה | | מתייגות פלט כלים; לא שער קריאת כלים. | +| `require-commit-before-stop` | קשה | | שער השלמת מפגש, לא שער קריאת כלים. | +| `require-push-before-stop` | קשה | | שער השלמת מפגש, לא שער קריאת כלים. | +| `require-pr-before-stop` | קשה | | שער השלמת מפגש, לא שער קריאת כלים. | +| `require-no-conflicts-before-stop` | קשה | | שער השלמת מפגש, לא שער קריאת כלים. | +| `require-ci-green-before-stop` | קשה | | שער השלמת מפגש, לא שער קריאת כלים. | + +## שמות מדיניות סמנטיים + +אלה הבדיקות `FailproofAI/jev-policies` מצהירה על, וערכים `reviewedBy` מקבל פעם זה מותקן. Failproof AI עצמה לא משלחת אף אחד מהם: ללא החבילה הזו (או אחרת המצהירה על שמות אלה), שום מדיניות שם אותם לא ניתנת לבדיקה. כל אחד הוא בדיקה Jev עונה לגבי קריאת הכלים לפניה. **מצב** הוא מה בדיקה יכולה להשיב: בדיקה `deny` חוסמת על ראיות חזקות, בעוד בדיקה `instruct` רק אי פעם מזהירה. כל אחד שומר על סירוב מדיניות עומדת כאשר היא יורה והמשתמש לא ביקש את הקריאה. **המשתמש יכול לעקוף** אומר האם בקשה מפורשת משלו ברורה של האדם מבטלת זאת. + +Jev שואל בדיוק את [בדיקות Jev](/he/policies/publish-a-pack#jev-checks-in-a-pack) חבילות מותקנות מצהיר על, וזה שמות `reviewedBy` מקבל. שם שתי חבילות מצהיר שונה לא מכובד לא אחד. אחד מ-16 שמות אלה מכוהן על ידי חבילה שלא מותקנת מ-FailproofAI מאגר מתעלמת בחבילה זו: את הגרסה שלה לא מובקשת ולא ערעור FailproofAI שלה, כך ששלישי-צד חבילה יכול או להיות בדיקה שמבטל את מדיניות חבילת הליבה או להשתמש בבדיקה אחת של אלה. רשימת חבילה שלא נקראת, או חבילה שכל בדיקה שלה לא בשימוש, משאיר Jev כלום לשאול. + +| שם | מצב | המשתמש יכול לעקוף | מה Jev בודק | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | כן | מחיקה קבועה של נתונים שלא יכול להיות בר-הגנה. | +| `production-infra-change` | deny | כן | שינוי תשתית חיה. | +| `git-history-rewrite` | deny | כן | שינוי כתיבה או זריקה של היסטוריה git משותפת. | +| `push-to-protected-branch` | instruct | כן | דחיפה ישירה לענף מוגן. | +| `commit-on-protected-branch` | instruct | כן | התחייבות ישירה על ענף מוגן. | +| `secret-exposure` | deny | כן | קריאה או העתקת אישורים. | +| `credential-exfiltration` | deny | לא | שליחת סודות או קבצים פרטיים מהמכונה. | +| `remote-code-execution` | deny | כן | הפעלת קוד שהורד מהאינטרנט. | +| `privilege-escalation` | deny | כן | הפעלה עם זכויות מורחבות. | +| `database-destruction` | deny | כן | הרמסה או שינוי הריסה של נתוני בסיס נתונים. | +| `read-outside-workspace` | instruct | כן | קריאת קבצים מחוץ לפרויקט. | +| `agent-config-tampering` | deny | לא | שינוי תצורת בטיחות שלך של הסוכן. | +| `system-modification` | instruct | כן | שינוי המערכת מחוץ לפרויקט. | +| `env-secrets-dump` | instruct | כן | הדפסת סודות סביבה. | +| `external-destructive-action` | deny | כן | פעולה בלתי הפיכה דרך כלי חיצוני. | +| `external-data-egress` | instruct | כן | שליחת נתונים פרטיים לכלי חיצוני. | \ No newline at end of file diff --git a/docs/he/policies/jev-byok.mdx b/docs/he/policies/jev-byok.mdx new file mode 100644 index 000000000..45a91fe1b --- /dev/null +++ b/docs/he/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev evaluator (הביאו את המפתח שלכם)" +description: "תנו ל-Jev classifier של TypeSafe לשפוט קריאות כלים של agents שלכם מעל קרקעית regex קשה, דרך endpoint ומפתח Jev משלכם." +icon: "key-round" +--- + +מדיניות regex תואמת מחרוזות. הם לא יכולים להבחין בין `rm -rf build/` שביקשתם מ-`rm -rf ~` שהחליק לתוך תכנית, כך שהם חוסמים יותר מדי במקום אחד וקצת מדי בחזה. **Jev**, ה-classifier של TypeSafe, קורא את הקריאה מול מה שבעצם ביקשתם ועונה על סט של שאלות כן/לא עליה בבקשה אחת מהירה. + +עם endpoint ומפתח Jev משלכם מוגדרים, Failproof AI שואל את Jev על כל קריאת כלי **לצד** מדיניות ה-regex, לעולם לא במקום שלהם: + +- ה-deny של מדיניות **קשה** הוא סופי. Jev לא יכול להנקות אותו. כל מדיניות קשה אלא אם כן היא מסומנת בצורה מפורשת כ-reviewable ושמות בדיקות Jev שמכסות אותה, ולכן מדיניות custom, pack או Cloud שלא אומרת כלום היא קשה, וה-guard self-protection שתמיד פועל הוא תמיד קשה. +- ה-deny של מדיניות **reviewable** עשוי להיקבע, אך רק כאשר Jev נשאל על הדאגה המדויקת שמדיניות זו מכסה וענה "אין כאן כלום" או "המשתמש ביקש את זה". בדיקה שמוצאת את הדאגה כממשית, כאשר המשתמש לא ביקש את הקריאה, שומרת על ה-deny — אפילו כאשר הפסק שלה הוא רק אזהרה, מכיוון שלפני קריאת כלי אזהרה לא עוצרת את ה-agent. וכאשר אותה בדיקה היא כזו שיכולה להכחיש (חשיפת סודות, כניסת אישורים, מחיקה הרסנית, ...), כלום לא מוקבע על קריאה זו. +- בלוק עדיין יכול להיות **אזהרה** כאשר הקריאה היא צעד של המשימה שנתתם ולא מגיעה הלאה: Jev משנה את ה-deny שלו לאזהרה, ואותה אזהרה — המתארת מה בעצם לא בסדר עם הקריאה — מחליפה את הבלוק של המדיניות. +- Jev יכול גם להתריע או להכחיש בעצמו, על נזק שאף regex לא מתאר. +- אם Jev לא יכול לענות (timeout, rate limit, שגיאת שרת, אין credits, גרסה מודל בלתי צפויה), קריאה זו מקבלת את תוצאת ה-regex, בדיוק כמו ללא Jev. +- Jev לעולם לא הופך קריאה למאפשרת יותר מהמדיניות שלכם בלבד אלא אם קרא את כל הקריאה ונשאל על הדאגה המדויקת. הכל פחות מזה — קריאה גדולה מדי לשליחה כמכלול, injection חשוד — משוך את ההסכמות ושומר על כל ה-deny. + + +ללא הגדרת Jev כלום לא משתנה: hooks מפעילים את מדיניות ה-regex בדיוק כפי שתמיד עשו. ההגדרה היא ה-opt-in כולה. + + + +על FailproofAI Cloud? אתה לא צריך מפתח משלך: מכונה המחוברת עם מפתח שנושא `jev:evaluate` יכולה להשתמש ב-Jev בתכנית הארגון שלך. ראה [Jev through FailproofAI Cloud](/he/policies/jev-cloud). + + +## בחר ספק + +Jev ניתן להשגה דרך חמש נתיבים. הביא מפתח לכל אחד מהם. + +| ספק | `--provider` | Endpoint | מודל ברירת מחדל | הערות | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | סיכום גרסה מדויק. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | הבקשות נתובות לנקודות קצה בעלות אפס שמירה של נתונים בלבד, ללא fallback לספק אחר. דו"ח גרסה בעלת תאריך כגון `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | שם Jev רק לפי כינוי, כך שהגרסה המשיבה נרשמת כלא מוודאת. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | צורך `--account-id`. כ-שש קריאות בשנייה לכל מפתח נמדדו לפני HTTP 429. | +| הendpoint שלך | `custom` | `/systemone` | `jev-1.13.0` | כל endpoint המקבל את גוף הבקשה של TypeSafe ודו"ח איזה מודל ענה. `https` בלבד; `http://localhost` רגיל מתקבל בשיטת shadow בלבד. | + + +עם תכונת bring-your-own-key של Vercel, בקשה שנכשלה תיחזור שוב בשתיקה עם אישורים של Vercel. אם אתה צריך כל קריאה חויבת ונראות לחשבון TypeSafe שלך בלבד, השתמש ב-TypeSafe ישירות. + + +## הגדר את זה + +פקודה אחת, ה-endpoint והמפתח: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### ה-URL בוחר את הספק + +אתה לא צריך לשם את הספק: **הוסט** של ה-URL הוא איזה אחד זה. + +| URL host | ספק | גם צריך | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| כל הוסט אחר | `custom` | — ה-URL שנתת הוא ה-base URL | + +שלוש דברים נובעים מזה: + +- **ה-URL של ה-API של הספק עצמו לא כותב override.** `--url https://api.typesafe.ai/v1` מייצר בדיוק את ההגדרה שיש `--provider typesafe`. תן נתיב או הוסט אחרים בספק ידוע וזה מאוחסן כ-base URL, כמו `--base-url` היה מאחסן אותו. +- **`--provider` עדיין דוחק את ההסקה**, וזו איך אתה מגיע לפרוקסי שמדבר ב-API של ספק מהוסט משלך: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **`--provider` שמתנגד להוסט מסורב**, לא ניחוש. `--provider openrouter --url https://api.typesafe.ai/v1` לא כותב כלום ואומר למה: שתי הכתיבות לא מסכימות היכן המפתח שלך עומד להישלח. אותו זוג מסורב מ-`jev setup --base-url` ומהדוח המחומד של Jev settings. (`--provider custom` אינו סתירה — זה אומר "התייחס ל-URL זה כלעצמו" — למעט בהוסט של Cloudflare, אשר מסלול custom לא יכול להגיע אל ה-endpoint per-account שלו.) + +`--url` מוודא בדיוק כמו ש-`baseUrl` בקובץ הגדרה הוא, והסרב באותם מילים: `https`, או `http://localhost` רגיל בשיטת shadow בלבד. + +### המפתח + +Pipe אותו עם `--key-stdin`, או הפעל את הפקודה בטרמינל בלעדיו והדבק את המפתח בשאילתה מוסווה. בכל מקרה הוא נכנס ישירות לקובץ ההגדרה ולעולם לא מודפס בחזרה. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` לוקח את אותו הדגלים וזה ה-longhand לכל זה: `setup --provider ` שם היית מעדיף לשם את הספק מאשר את ה-URL. + +### `--token`, ומה זה עולה + +`--token ` שם את המפתח בשורת הפקודה, שהיא הדרך הכי מהירה להגדיר מכונה וה-spelling היחידה שמשאירה את המפתח בכל מקום אלא בקובץ ההגדרה: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +ארגומנט של שורת פקודה נמצא בקובץ ההיסטוריה של ה-shell שלך לאחר מכן, וכאשר הפקודה פועלת זה נמצא ברשימת התהליכים — ניתן קריאה מ-`/proc` על ידי כל דבר שפועל כמוך. `setup` אומר כן בכל פעם ש-`--token` משמש. עדיף `--key-stdin` על מכונה שאתה משתף, בהפעלה מוקלטת, או בכל מקום שקובץ ההיסטוריה מסונכרן; סובב מפתח שהעברת בדרך זו אם זה משנה. + + +`--token`, `--key-stdin` ו-`--key-from-env` זה מוציא זה את זה: תן אחד. + +אחר כך שלח בקשה חיה אחת קטנה כדי לבדוק את המפתח, ה-endpoint ואיזה Jev ענה: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` יוצא 1, ואומר כן בכותרת שלו, כאשר התשובה מגיעה לאחר ה-timeout (כל hook היה חוזר לregex כ-`timeout`) או עונה לשאלת הבדיקה שלו בצורה שגויה. + +Hooks קוראים את ההגדרה בכל קריאת כלי, ולכן זה חל מהבאה. אין כלום להתחיל מחדש, עם או בלעדי ה-daemon. + +## בדוק מה זה עושה + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` מציג את הספק, ה-endpoint, המודל, המצב, קובץ ההגדרה וההרשאות שלו, ולעולם לא את המפתח. מתחתיו זה מסכם פעילות אחרונה: כמה קריאות Jev הערך, כמה פעמים זה חזר לregex ולמה, ה-latency שלו, ואילו מדיניות reviewable זה הנקה. + +## שיטת shadow + +`enforce` הוא ברירת המחדל. כדי לצפות ב-Jev מבלי לתת לו לשנות כל החלטה, עבור ל-`shadow`: Jev עדיין נשאל וההחלטות שלו נרשמות, אך תוצאת ה-regex היא מה שנאכף. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` שמור על ההגדרה — ה-endpoint והמפתח — ומפסיק לשאול את Jev: hooks מפעילים את מדיניות ה-regex בדיוק כמו ללא הגדרה, ו-`failproofai jev status` אומר "off (switched off)". חזור עם `--mode shadow` או `--mode enforce`. + +הפעלה חוזרת של `setup` באותו ספק שומרת על המפתח המאוחסן, כך שתחליף מצב הוא דגל אחד. החלפת ספק מתחיל מחדש ושואל עבור המפתח של הספק הזה. כמו כן `--base-url` שמעביר בקשות לוסט אחר: מפתח מאוחסן נשלח רק להוסט שהוא ניתן עבורו, או אל ה-API של הספק שלו. + +## קובץ ההגדרה + +הכל גר בקובץ אחד, `~/.failproofai/jev.json`, כתוב על ידי `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| שדה | משמעות | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` או `custom` — או `failproofai`, שלמפתח שלו מגיע מהחיבור של FailproofAI Cloud במקום קובץ זה (ראה [Jev through FailproofAI Cloud](/he/policies/jev-cloud)). | +| `apiKey` | נשלח כ-`Authorization: Bearer `. | +| `baseUrl` | נדרש עבור `custom`; מחליף את ה-API base של הספק בעל כן. חייב להיות `https`. `http` רגיל אל `localhost` מתקבל רק עם `mode: shadow`: כלום לא מאמת יציאה מקומית, כך שבעוד הפרוקסי שלך למטה כל תהליך במכונה, כולל ה-agent שנשפט, יכול לענות במקומו. | +| `accountId` | Cloudflare בלבד: 32 תווי hex קטנים. | +| `model` | מחליף את ה-model id של ברירת המחדל של הספק. ה-id של גרסה חייב לשם Jev 1.13. ערך בצורת API key סורב (ולא חוזר), כך שמפתח הדביק למעבר `--model` לעולם לא מאוחסן או נשלח כמודל. | +| `timeoutMs` | כמה זמן קריאת כלי מחכה אל Jev לפני שימוש בתוצאה regex. 100–10000, ברירת מחדל 3000. | +| `mode` | `enforce` (ברירת מחדל), `shadow`, או `off` (שמור את ההגדרה, הפעל ללא Jev). | + +שלוש כללים מגנים עליו: + +- **רק בעלים.** זה כתוב עם הרשאות `0600`. עותק שכל משתמש או קבוצה אחרת יכולה לקרוא או לכתוב הוא **סרוב**, hooks חוזרים לregex עד שתפעיל `chmod 600 ~/.failproofai/jev.json` או `setup` שוב. הספרייה בדוקה גם: `~/.failproofai` לא צריכה להיות **כתובה** על ידי מישהו אחר, כי מי שיכול לכתוב שם יכול להחליף את הקובץ כל הרשאות משלו. `setup` מסיר את הביטים כתוב אלו אם זה מוצא אותם. `failproofai jev status` אומר כאשר הגדרה סורבה ומראה את ה-endpoint שהקובץ מייצג: מישהו אחר יכול היה לשנות אותו, כך לבדוק זה שלך לפני שתוביל `chmod`. הפעלה חוזרת של `setup` על קובץ כזה נושאת את המפתח המאוחסן שלו רק אל ה-API של הספק; כל endpoint אחר שהוא שם צריך את המפתח שוב (`--key-stdin`), או `--base-url default` לשלוח בקשות חזרה אל הספק. +- **גלוברי בלבד.** מאגר לא יכול להפעיל את Jev, להצביע עליו בendpoint אחר או לבחור את המודל שלו: `.failproofai/jev.json` בתוך פרוייקט מתעלם, והספק, ה-URL, המודל והמזהה החשבון נקראים רק מקובץ זה — לעולם לא מהסביבה, שהגדרות agent של מאגר יכולות להגדיר. (`FAILPROOFAI_HOME` אינו דרך סביב זה: זה מעביר את כל ספריית failproofai, המדיניות שלך כלול, במקום להפנות Jev בעצמו.) +- **רק המפתח לבדו יכול להגיע מהסביבה.** אם לקובץ אין `apiKey`, `FAILPROOFAI_JEV_API_KEY` מספק אותו לאותה הפעלה (`setup --key-from-env` כותב קובץ כזה). זה לעולם לא מחליף מפתח שהקובץ מחזיק, וזה לא יכול להפעיל את Jev ללא הקובץ. כאשר המשתנה לא מוגדר, Jev היא פשוט כבוי עבור אותה מעטפת: `failproofai jev status` אומר כן, יוצא 0 ועוזב את ההגדרה לבדה (`status --json` מדווח `"status": "key-missing"` עם `"reason": "no-env-key"`). ה-daemon `failproofaid` לא רואה את סביבת ה-shell שלך, כך על מכונה המגודרת עם `failproofai config`, שמור את המפתח בקובץ. + +## איזה Jev עונה + +סף ההחלטה של Failproof AI כויל על Jev 1.13, כך תשובה משמשת רק כאשר היא מגיעה מאותה משפחה: `jev-1.13.x`, או OpenRouter של `typesafe/jev-1.13-`. כאשר ספק שם Jev רק לפי כינוי וא דו"ח ללא גרסה (Vercel, ו-Cloudflare כאשר זה לא אומר), התשובה משמשת ונרשמת כלא מוודאת. `custom` endpoint חייב לדווח את המודל שענה; החריג היחידי הוא `--model` שם לא גרסיון שהגדרת עבורו, אשר, הד בחזרה, נרשם כלא מוודא באותו הדרך. תשובה המדווחת כל גרסה אחרת, או תשובה `custom` שלא מדווחת כלום, אינה משמשת: קריאה זו חוזרת לregex עם הסיבה `model-mismatch`. + +## כאשר Jev לא יכול לענות + +כל אחד מאלה חוזר לתוצאת ה-regex עבור קריאה זו ורשום עם הסיבה שלו, אשר `failproofai jev status` סכומים: + +| סיבה | גורם | +| --- | --- | +| `timeout` | אין תשובה בתוך `timeoutMs`. | +| `http-429` | הספק rate-limited את המפתח. | +| `rate-limited` | ה-limiter של Failproof AI שלו עצר את הקריאה חזרה לפני שליחה: 5 בקשות בשנייה, בפרצים של עד 5, ואף אחד לרגע לאחר שהספק עונה `429`. לא הספק. | +| `http-500`, `http-502`, `http-503`, … | שגיאת שרת בספק. הסטטוס המדויק נרשם. | +| `out-of-credits` | HTTP 402: לחשבון הספק אין credits נותרו. | +| `provider-refused` | HTTP 402 מ-Cloudflare קריאה "Model execution failed (Payment error)": הספק סירב להריץ את המודל בבקשה זו. בדרך כלל לא חיוב, כך טעינה תזיז אותו. | +| `http-401`, `http-403` | המפתח סורב. | +| `http-404` | כלום לא משמש ב-`/systemone`, כך ה-base URL לא בסדר — `/systemone` מוסף אליו, וכל ספק משמש אותו בשורש גרסה שלו. `failproofai jev models` מציג מה ה-endpoint כן משרת. | +| `network` | לא היה אפשר להגיע ל-endpoint. | +| `http-301`, `http-302`, `http-307`, `http-308` | ה-endpoint ענה עם redirect. Redirects לא מעקבים, כך התשובה באה רק מה-URL בהגדרה שלך; קבע `--base-url` ל-URL הסופי. | +| `malformed` | ה-endpoint ענה, אך לא עם תשובה Jev — גוף שאינו JSON, או אחד בלא תשובות בו. | +| `cloudflare-error`, `cloudflare-incomplete` | מעטפת של Cloudflare דיווחה כשל, או עבודה שלא הסתיימה. | +| `model-mismatch` | גרסה Jev אחרת מ-1.13 ענתה, או `custom` endpoint לא אמר איזה מודל ענה. | +| `request-cut` | **לא הפסקה.** Jev ענתה; זה הוצג רק חלק מהקריאה, כך התשובה שלו נקתה כלום. ראה [כאשר Jev ענתה, אך לא על הקריאה כולה](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` יכול להציג כמה סיבות נדירות יותר גם כן, כגון `upstream-error` (התשובה נשאה את השגיאה של הספק שלו) או `config`, וסכומים כל סיבה שהוא לא יכול לשם כ-`other`. + +`request-cut` נמצא בטבלה זו כי `failproofai jev status` סוכם אותו עם השאר, ובגלל שגם זה משאיר כל ה-deny עומדות. זה סיבה היחידה כאן שלא אומרת כלום על הספק שלך: הבקשה הגיעה ו-Jev ענתה לה. בניגוד לכל שורה מעליו, התשובה הזו עדיין סופרת — ה-deny או ה-warning של Jev יחול על גבי תוצאת ה-regex במקום להיות מושלכת. כך ריצה של אלה אומר קריאות מגיעות להערך גדולה מדי לשליחה כמכלול, לא שה-endpoint שלך לא בסדר, וטעינה של credits או שינוי ה-URL לא יזיז את המספר. + +## כאשר Jev ענתה, אך לא על הקריאה כולה + +שני דברים נוספים יכולים לקרות, ואף אחד לא Jev כושל לענות. שניהם על כמה מהקריאה, או מהשיחה, התאימה לבקשה אחת. + +**חלק מהקריאה עצמה לא התאימה.** קריאה כלי נשלחת בתוך תקציב קבוע, וחריגה — `Write` גדולה מאוד, גוף MCP עצום, פקודה מרופדת עד הכיפה — נשלחת עם מה התאים. Jev עדיין עונה, והתשובה שלו עדיין סופרת: ה-deny או ה-warning שלו יחול כרגיל. מה זה לא יכול לעשות זה **קבוע** כלום, מכיוון שפסק נתון בחלק מקריאה אינו פסק בקריאה. כך כל ה-deny מדיניות עומדות, והקריאה נרשמת כ-fallback עם הסיבה `request-cut`, אשר `failproofai jev status` סוכמים לצד הסיבות לעיל. הכלל זה נותן לך: הגדלת קריאה יכול להוציא את ההסכמות שלו, וא פעם לא יכול לקנות אחד. + +**הודעה לא התאימה.** ביצוע ארוך שהדקת, הודעת ה-agent האחרונה, או פקודה מערך האחסון שלה הערך כבר כיפה. **כלום לא משתנה**: הקריאה נשפטת, נקתה ורשומה בדיוק כמו כל אחד אחר, וזה לא סופר כ-fallback. האורך של מה שאתה הקלדת לעולם לא מחליט אנו פסק, וקית לא יכול לייצור הסכמה: שם ביצוע הגיע כבר כיפה, "אתה לא ביקשת את זה" מפסיקה להיות מסקנה שיכול להיות מוצא ממנו בכלל, במקום להפוך לאחד. + +הקו בין השניים הוא מי כתב את הטקסט. הקריאה היא ה-agent, וכלל שתן אורך שלו להפחית חומרה יהיה כלל ה-agent יכול להשתמש; ביצוע שלך שלך, וטיפול באורך שלו כאות רק פעם אחת הענש הדביק מפרט או עקבת ערימה. + +## מה עוזב את המכונה + +עבור כל קריאה כלי Jev מערכי, בקשה אחת יוצא לספק שלך, נושא: + +- הקריאה עצמה, עם סודות כגון API keys, bearer tokens ו-`KEY=` הקצאות redacted; +- הביצוע הקרוב שהקלדת, עם טקסט ה-agent harness הוסיף הוסר; +- הודעת ה-agent האחרונה לפני הביצוע הקרוב שלך, מתויג כ-agent-written; +- עובדות מחושבות מקומי, כגון האם נתיב בתוך הפרוייקט — זה הפעלה במפגש שלה הראשון בדוק בדוק, [pinned לפעלה](/he/reference/jev-intent#the-project-root) — וסניף git הנוכחי. + +זה יוצא רק ל-endpoint בהגדרה שלך, תחת המפתח שלך. + +## כבה אותו + +```bash +failproofai jev remove +``` + +זה מחוק `~/.failproofai/jev.json`. מהקריאה הכלי הבאה, hooks מפעילים את מדיניות ה-regex בדיוק כמו לפני. ה-per-session מאחסן תחת `~/.failproofai/state/semantic/` (ביצוע נרשם ב-`sessions/`, שורשי פרוייקט ב-`roots/`) נשאר במקום וגיל החוצה. כדי להפסיק לשאול את Jev אך שמור את ההגדרה, השתמש `failproofai jev setup --mode off` במקום. + +## התייחסות לפקודה + +| פקודה | תוצאה | +| --- | --- | +| `failproofai jev --url --key-stdin` | הגדר אותו בפקודה אחת; הספק בא מהוסט של ה-URL | +| `failproofai jev --url --token ` | זהה, עם המפתח בשורת הפקודה — ההיסטוריה והרשימת התהליכים שלך ראה זה | +| `failproofai jev setup --provider --key-stdin` | כתוב את ההגדרה מ-key piped על stdin | +| `failproofai jev setup --provider ` | זהה, שאילתה עבור המפתח בשאילתה מוסווה | +| `failproofai jev setup --key-from-env` | אל תאחסן מפתח; קרא `FAILPROOFAI_JEV_API_KEY` לכל הפעלה | +| `failproofai jev setup --mode shadow` | חלופי מצב (`enforce`, `shadow` או `off`), שמור את המפתח המאוחסן | +| `failproofai jev setup --model ` / `--base-url ` | דרוס את המודל או ה-API base; `default` מנקה את הדרוס | +| `failproofai jev setup --timeout-ms ` | שנה את התקציב לכל קריאה | +| `failproofai jev status [--json]` | הגדרה, הרשאות ופעילות אחרונה; לעולם לא את המפתח | +| `failproofai jev test [--json]` | בקשה חיה אחת: latency וגרסה שענתה | +| `failproofai jev models [--provider ] [--url ] [--json]` | ה-model ids ש-`/models` של ה-endpoint מדווח, סימון ה-configured | +| `failproofai jev remove` | מחוק את ההגדרה; Jev כבוי | \ No newline at end of file diff --git a/docs/he/policies/jev-cloud.mdx b/docs/he/policies/jev-cloud.mdx new file mode 100644 index 000000000..5503fe569 --- /dev/null +++ b/docs/he/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev דרך FailproofAI Cloud" +description: "תן ל-Jev לשפוט את קריאות הכלים של האגנטים שלך דרך FailproofAI Cloud, בתוכנית של הארגון שלך, ללא חשבון TypeSafe או מפתח משלך." +icon: "cloud" +--- + +[Jev](/he/policies/jev-byok), המסווג של TypeSafe, קורא כל קריאת כלי מול מה שבאמת ביקשת וענה בצד המדיניות שלך, לעולם לא במקומן. דרך **FailproofAI Cloud**, מכונה מחוברת משתמשת ב-Jev עם אותו מפתח שבו היא כבר מתחברת: אין חשבון TypeSafe, אין מפתח שני, אין נקודת קצה להגדרה. כל קריאה מחויבת לקצבת התוכנית הקיימת של הארגון שלך. + +הכל שב-Jev עושה זה ללא שינוי מ[הגדרת הבאת-המפתח-שלך-שלך](/he/policies/jev-byok): מדיניות קשה נשארת סופית, הכחשון של מדיניות שניתן לבדוק מתבטל רק כאשר ל-Jev נשאלו בדיוק על אותה חשש, וכל כישלון חוזר לתוצאת regex עבור אותה קריאה. + + +דורש **failproofai 1.0.8-beta.0** או מאוחר יותר. ב-1.0.7 אין Jev, גם אם הוא מסתדר מעל ה-1.0.7 betas. ללא תצורת Jev שום דבר לא משתנה: hooks מריצים את מדיניות regex בדיוק כפי שתמיד עשו. + + +## הפעל זאת + +1. **צור מפתח עם Jev.** בלוח הבקרה של FailproofAI Cloud, פתח **Keys → Create key** ובחר בתשקול **machine**. הוא מעניק את שלוש ההרשאות שמכונה צריכה: `events:add` (שלח פעילות), `policies:pull` (קבל מדיניות) ו-`jev:evaluate` (Jev, מחויב לתוכנית של הארגון שלך). מפתח לא יכול לשאת `jev:evaluate` ללא השניים האחרים. +2. **חבר את המכונה** עם אותו מפתח: + + ```bash + failproofai config --token + ``` + + אם הארגון שלך מריץ את FailproofAI Cloud שלו בעצמו ולא את זה המתארח, הוסף את הכתובת שלו: `--url https://` (או יצא `FAILPROOFAI_CLOUD_URL`). ללא זה המפתח מוצפן בשירות המתארח וההתחברות נכשלת. אם התעודה של אותו מארח מגיעה מ-CA פרטית, התקן את ה-CA בחנות האמון של המערכת של המכונה (לדוגמה עם `update-ca-certificates`), לא רק ב-`NODE_EXTRA_CA_CERTS`: ה-daemon ששולח אירועים וקולע מדיניות קורא את חנות המערכת. ראה [Troubleshooting](/he/reference/troubleshooting). + +זה הכל. התחברות שומרת את המפתח וכאשר למכונה **אין** תצורת Jev עדיין, מפעילה Jev דרך FailproofAI Cloud במצב **shadow**: Jev נשאל על כל קריאת כלי סגור וגזרי הדין שלו מתועדים, אבל התוצאה של המדיניות שלך היא מה שמוכן. הפלט אומר כך: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**עם `--no-transcripts`, התחברות לא מפעילה Jev.** Jev שולח כל קריאת כלי בדוקה ואת ההנמקה האחרונה ל-FailproofAI Cloud, שזה יותר מחיבור החלטות בלבד שנשאל לשלוח. המפתח עדיין מאוחסן, והפלט אומר ש-Jev זמין והיכן להחליף אותו: + +```bash +failproofai jev setup --provider failproofai +``` + +זה גם לא מכבה את Jev. אם ה-`jev.json` של המכונה כבר מריץ את Jev דרך FailproofAI Cloud, הוא נשאר כשהוא, והפלט אומר שJev עדיין שולח כל קריאת כלי בדוקה והנמקה אחרונה, וש-`failproofai jev setup --mode off` מכבה אותו. + + +התחברות **לעולם לא משכתבת** `~/.failproofai/jev.json` קיים. אם אתה כבר משתמש בנקודת הקצה של Jev שלך, היא ממשיכה להיות בשימוש, והפלט אומר שהקובץ הושאר כמו שתצורן — וכאשר הקובץ הזה משאיר את Jev כבוי (סירוב, או מודגש כבוי), אומר כך והיכן לתקן. להחליף מכונה זו ל-FailproofAI Cloud, הרץ `failproofai jev setup --provider failproofai`. + + +## צל, אכוף או כבוי + +התחל בצל, צפה מה Jev היה עשוי על דף המדיניות, ואז תן לו לפעול: + +```bash +failproofai jev setup --mode enforce # Jev's verdicts apply: it may clear a reviewable deny and add its own +failproofai jev setup --mode shadow # Jev is asked and logged; your policies' result is enforced +failproofai jev setup --mode off # keep the config, stop asking Jev +``` + +אותו מתג נמצא בלוח הבקרה המקומי: **Settings → Jev** יש מתג הפעלה/כיבוי וצל/אכוף. הוא משכתב את המצב ולא יותר מכך. Hooks קוראים את התצורה בכל קריאת כלי, כך ששינוי חל מהבא, ללא הפעלה מחדש. + +## בדוק מה היא עושה + +```bash +failproofai jev status +failproofai jev test +``` + +`status` מציג את הספק כ-**FailproofAI Cloud**, מארח ה-Cloud שאליו התחברה המכונה, המצב, ומקור המפתח כ-**FailproofAI Cloud connection**, לעולם לא המפתח. כאשר `jev.json` של FailproofAI Cloud נמצא במקום אבל Jev לא יכול להריץ, הוא אומר למה: + +| `status` אומר | `status --json` | משמעות | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | המכונה מחוברת, אבל אין מפתח Jev שמור בשבילה: המפתח חסר `jev:evaluate`, או ההתחברות לא הצליחה לאשר. הרץ `failproofai config --token ` שוב עם אותו מפתח; אם היא חסרה את ההרשאה, השתמש במפתח **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | אין חיבור FailproofAI Cloud על מכונה זו שמפתח Jev שייך אליו. | + +לאחר `failproofai config --disconnect` אין עוד `jev.json` של FailproofAI Cloud (אלא אם כן הוא הודגש כבוי, שנשמר), כך ש-`status` פשוט דיווח על Jev כבוי. `status --json` נושא את אותם עובדות (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), גם כאשר התצורה היא הנעדרת או מורחקת. `permissions` הוא תמיד של `jev.json`; סירוב בנוגע ל-`credentials.json` מוסיף `credentialsPermissions`, ו-`fix` כאשר פקודה אחת תיקנה. `test` שולח בקשה חיה אחת וממציא את ההשהיה שלה וגרסת Jev שענתה. הוא יוצא 1, ויאמר כך בכותרת שלו, כאשר התשובה מגיעה לאחר timeout של hook (hooks היו רושמים `timeout`) או עונה לשאלת הבדיקה שלו בעיוות. + +לוח הבקרה של **Settings → Jev** מציג גם את **FailproofAI Cloud connection**: אילו ארגון המכונה דיווח אליו והאם המפתח שלו נושא Jev. הוא נקרא מהקבצים שלו של המכונה, ללא קריאת רשת. + +## מה מגיע לדף המדיניות + +המכונה כבר שולחת את פעילות ה-hook שלה ל-FailproofAI Cloud (`events:add`). עם Jev כן, רשומת כל קריאה סגורה אומרת גם איזה מעריך רץ, מה Jev החליט, אילו מדיניות הוא פנה, למה הוא חזר כשהוא עשה, ההשהיה שלו וה-model שענה — החלטות, קודים ושמות, לעולם לא הפקודה או ההנמקה שלך. בדף **Policies** של הארגון שלך: + +- קריאה שגזר הדין שלו של Jev הוא החליט (enforce mode) מיוחסת ל-**Jev**, וכאשר הבדיקה המחליטה באה מחבילה, הרשומה גם שם את החבילה ההיא וגרסה שלה; +- במצב צל, הכחשון או אזהרה של Jev מופיעים כ-**would-have**, לצד הרוליות שאתה מצפה; +- המדיניות שJev פנה, או היה פונה במצב צל, נספרות למדיניות. + +## כאשר Jev לא יכול לענות + +כל אחד מאלה חוזר לתוצאת המדיניות שלך עבור אותה קריאה, ורשום עם הסיבה שלו: + +| סיבה | סיבה | +| --- | --- | +| `out-of-credits` | הארגון שלך השתמש בקצבת התוכנית שלו. | +| `http-401`, `http-403` | המפתח בוטל, או לא נושא `jev:evaluate`. התחבר מחדש עם מפתח שעושה. | +| `http-429` | FailproofAI Cloud הוא הגבלת שיעור Jev בעבור הארגון שלך. עד שהזמן שהוא שואל עליו הוא מתום (שלו `Retry-After`, לכל היותר 60 שניות), המכונה לא שולחת לו כלום וכל קריאה חוזרת מייד. קריאות המתעכבות בדרך זו רשומות כ-`http-429`, או כ-`rate-limited` כאשר הגבלת השיעור של המכונה שלה מחזיקה אותן קודם לכן. | +| `http-429` (daily limit) | הארגון שלך השתמש בקריאות Jev היומיות שלו: **10,000 לכל יום UTC**, אלא אם כן מי שמתחזק את FailproofAI Cloud שלך קבע גבול אחר. כל קריאה חוזרת עד שהספירה מתאפס ב-00:00 UTC; המכונה עדיין שואלת שוב לכל היותר פעם בדקה, כך שהיא בוחרת את ההגדרה מחדש בתוך דקה. `failproofai jev test` אומר "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev סירב בקשת קריאה זו, בדרך כלל משום שקריאת הכלים הכילה טקסט צפוף (base64, hex, minified code) מעל תקציב הטוקן של Jev. אותה קריאה חוזרת בכל פעם; זה לא הפסקה. | +| `http-502` | Jev אינו זמין כרגע. | +| `http-503` | ה-Cloud זה לא יכול לשרת Jev בעבור ה-org שלך: אין שער מודל, ארגון שעדיין לא סופק, או השער כבוי. שאל את ה-admin שלך; hooks שואלים שוב לכל היותר פעם בדקה. | +| `http-404` | FailproofAI Cloud זה לא משרת Jev עדיין. | +| `timeout` | אין תשובה בתוך `timeoutMs` (ברירת מחדל 3000). | +| `model-mismatch` | גרסת Jev אחרת מאשר 1.13 ענתה. | + +## איפה המפתח חי, ולאן הוא הולך + +- המפתח מאוחסן פעם אחת, ב-`~/.failproofai/credentials.json` (`0600`, בספריה בבעלות בלבד), לצד עדויות FailproofAI Cloud אחרות. `jev.json` לא מחזיק מפתח לנתיב זה; אחד שנכתב שם הופך את התצורה לבלתי תקפה. +- אם `credentials.json` נושא **כל** הרשאה לכל אחד מלבדך (קבוצה או אחר, קרא או כתוב), או שספריית הספריה שלה ניתנת **כתיבה** על ידי מישהו מלבדך, היא **מורחקת**, לא קרא, ו-Jev כבוי עד שתתקן: `chmod 600` בקובץ, `chmod 700` בספריה (או התחבר מחדש, שמשכתב את הקובץ ב-`0600` ועושה את הספריה בעלות בלבד). ספריה שאחרים יכולים רק לקרוא היא בסדר; אחד שיכולים לכתוב בו מאפשר להם להחליף את הקובץ. +- המפתח סופר רק בעוד ההתחברות שהגיעה איתו נמצאת על המכונה: עדות מדיניות או דיווח בעבור FailproofAI Cloud **עם אותו מפתח**, באותו קובץ. מפתח Jev שנשאר מאחור ללא אחד אינו מתעלם, ו-Jev נשאר כבוי. זה קורה כאשר ה-`config --disconnect` של failproofai קדום משאיר את מפתח Jev במקום (הוא לא יודע להסיר אותו), או כאשר ה-`config --token` של failproofai קדום מתחבר עם מפתח אחר, שעל FailproofAI Cloud אולי שייך לארגון אחר. להחליף את Jev חזרה, התחבר שוב עם מפתח **machine**. +- המפתח לעולם לא משולח אלא למוצא ה-Cloud שהוא אומת נגדו. `jev.json` המכוון לכל מקום אחר מורחק. +- **אגנט על המכונה יכול לקרוא אותו.** `credentials.json` הוא בעלות בלבד, והאגנט רץ בבעלות ההיא. קריאת הקבצים שלו של failproofai עצמו מורשה בכוונה (רק שינוי אותם חסום, על ידי `block-failproofai-commands`), כך שהדבר היחיד בין אגנט לקובץ זה הוא `block-read-outside-cwd` — מדיניות **reviewable** — ומ-session שהחל בספריית הבית שלך, לא כלום. מפתח עם `jev:evaluate` מוציא את קצבת Jev של הארגון שלך (עד לכובעון היומי) מכל מקום בו הוא משמש, אז טרט מפתח מכונה כמו כל אישור הוצאות אחרות: אם אגנט אולי קרא אותו, בטל אותו בדף המפתחות וההתחברות מחדש עם מפתח חדש. +- רק הקבצים הגלובליים שלך קובעים זאת. מאגר לא יכול להפעיל Cloud Jev, להצביע לו במקום אחר או לספק את המפתח שלו, ו-`FAILPROOFAI_JEV_API_KEY` מתעלם לנתיב זה. +- עבור כל קריאה Jev מעריך, בקשה אחת הולכת ל-FailproofAI Cloud, נושאת מה שדף [bring-your-own-key](/he/policies/jev-byok#what-leaves-the-machine) מפרט (סודות מעדכנים). FailproofAI Cloud משדרת אותו ל-TypeSafe ולא רושמת או שומרת אותו. + +## כבה זאת + +| פקודה | תוצאה | +| --- | --- | +| `failproofai jev setup --mode off` | שמור את התצורה; Jev לא נשאל. **זה המתג שנמשך:** התחברות שוב לעולם לא משכתב `jev.json` קיים, כך ש-Jev נשאר כבוי עד שתהפוך אותו חזרה עם `--mode shadow`. | +| `failproofai jev remove` | מחק `~/.failproofai/jev.json`; Jev כבוי — עד ל-`failproofai config --token` הבא עם מפתח שנושא `jev:evaluate`, שמוצא לא `jev.json` ומפעיל Jev שוב במצב צל (אלא אם כן הוא רץ עם `--no-transcripts`). כדי להשאיר אותו כבוי, השתמש ב-`--mode off`. | +| `failproofai config --disconnect` | נתק את המכונה: המפתח מוסר, וכך גם `jev.json` כאשר הוא שם את FailproofAI Cloud ולא הודגש כבוי. `jev.json` בעבור נקודת הקצה שלך נשארת, וגם אחד הודגש כבוי, אז Jev נשאר כבוי כאשר אתה מתחבר שוב. | + +מהקריאה הבאה של הכלי, hooks מריצים את מדיניות regex בדיוק כמו לפני. \ No newline at end of file diff --git a/docs/he/policies/jev.mdx b/docs/he/policies/jev.mdx new file mode 100644 index 000000000..d44a7c576 --- /dev/null +++ b/docs/he/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "מדיניות Jev" +description: "הוסף סקירה חיה של Jev לקריאות כלי מגודרות, ואחר כך בדוק זאת לפני אכיפת ההחלטות שלה." +icon: "shield-check" +--- + +Jev קורא קריאת כלי מול מה שביקשו אדם מהסוכן לעשות. השתמש בה כאשר מדיניות התאמת מחרוזות חוסמת עבודה תקפה או מחמיצה פעולה מסוכנת הזקוקה להקשר. היא משיבה לצד המדיניויות שלך בשער `PreToolUse` או `PermissionRequest`. לניקוד **לאחר** סיום הפעילות, השתמש ב-[Jev evaluations](/he/evaluations/jev). + +## התחל במצב צפייה + +התקן את Failproof AI וצרף hooks ל-[harness נתמך](/he/reference/harnesses). השתמש בגרסה failproofai 1.0.8-beta.0 או חדשה יותר. + +Failproof AI אינו משלח בדיקות Jev. התקן אותן כחבילה, או ל-Jev אין מה לשאול ולעולם לא יוקרא: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +לאחר מכן בחר כיצד בקשות מגיעות ל-Jev: + +| נתיב | שלב ראשון | +| --- | --- | +| FailproofAI Cloud | התחבר עם מפתח **machine** הנושא `jev:evaluate`. במכונה ללא הגדרת Jev, `failproofai config` הופך את Jev למצב צפייה. | +| הספק שלך | בלוח הבקרה המקומי, פתח **Settings → Jev**, בחר בספק, הדבק את האסימון שלו, ובחר **observe**. או הריץ `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![הגדרות Jev של לוח הבקרה המקומי: ספק, endpoint, אסימון, ומצב צפייה לפני הפעלת Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` בודק את ה-endpoint. כדי לבדוק את נתיב ה-hook, בקש מסוכן בעל hooks להשתמש בכלי קריאת הקבצים שלו על `README.md`. אשר שקריאת הכלי הזו מופיעה בפעילות, ואחר כך בדוק **Policies → Activity** בלוח [הבקרה המקומי](/he/reference/local-dashboard#review-policy-activity). ספירת Jev ב`status` צריכה להיות גבוהה יותר. מצב צפייה מתעד את מה שJev הוא הוא היה מחליט בזמן שתוצאת המדיניות הקיימת שלך עדיין חלה. + +## החלט מתי לאכוף + +מדיניות **hard** תמיד יש את המילה האחרונה. Jev עשוי לחסל deny רק ממדיניות מסומנת בעליל **reviewable** ורק כאשר היא בדקה את ההשגחה המנויה של המדיניות הזו. ראה [policy authority](/he/policies/authority) לפני הסתמכות על קבלה. Jev יכול גם להזהיר או לחסום בעצמו. אם היא לא יכולה לענות, תוצאת המדיניות קובעת את הקריאה הזו. + +ברגע שתוצאות הצפייה נראות נכונות, עבור למצב אכיפה ב-**Settings → Jev** או הריץ: + +```bash +failproofai jev setup --mode enforce +``` + +עבור כתובות ספקי, מפתחות Cloud, הגדרה, fallbacks ונתונים שנשלחים עם כל בקשה, ראה את [Jev integration reference](/he/reference/jev). \ No newline at end of file diff --git a/docs/he/reference/custom-agents-typescript.mdx b/docs/he/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..8657e5240 --- /dev/null +++ b/docs/he/reference/custom-agents-typescript.mdx @@ -0,0 +1,428 @@ +--- +title: "Custom agents (TypeScript)" +description: "Configuration, the event catalog, the scopes and the framework adapters for @failproofai/sdk." +icon: "square-js" +--- + +כל הגדרה, שיטה ושדה ב-SDK של TypeScript. אם אתה מכשיר לראשונה, התחל בהנחיה — דף זה לחיפוש הערכים. + + + + התקנה, כשור, שיטות הירויים, דוגמה מעובדת וגם בעיות נפוצות. + + + אותם ירויים, אותו פורמט חוט, אותו ספול — מ-Python. + + + +Node 20.9 ומעלה. ESM ו-CommonJS. ללא תלויות זמן ריצה. + + + ה-SDK הזה ה-Python מכתיבים **אותם ירויים לאותו ספול**. fleet עם agents של Node ו-agents של Python מייצר קבוצת sessions אחת, לא שתיים, ודבר בלוח הבקרה לא מבחין ביניהם. בחר לפי שירות, לא לפי חברה. + + +## Install + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +מתאמי המסגרת משתלחים בחבילה עצמה. המסגרות הן **תלויות עמיתות אופציונליות** — מוצהרות כך שהטווחים הנתמכים גלויים, לא מותקנים בשמך, ויובאו רק כאשר קוראים ל-`instrument()`. + +## חבר את daemon של Failproof + +זהה ל-SDK של Python: צור מפתח `events:add` תחת **Admin → Keys**, ואז [חבר את daemon](/he/start/setup#connect-a-machine-to-cloud) על מכונת ה-agent. ה-SDK כותב לדיסק; ה-daemon משלח. + +## Configuration + +### OpenTelemetry spans (opt in) + +התקן OpenTelemetry בנפרד עם `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +לאחר מכן הוסף את FailproofAI למעבדי ספק שלך: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +לספק קיים, שמור על מעבדים אחרים שלו באותה רשימה. ספקים שחושפים `addSpanProcessor` יכולים במקום זאת להעביר כ-`{ provider }`. ללא אפשרויות, setup מרשם ספק חדש רק אם אין ספק שכבר רשום. +`OtelSpanExporter` יכול גם לשמש ישירות עם המעבד שלך. + +הייצוא עובר דרך ה-daemon של FailproofAI המחובר; ה-SDK לא שולח בקשות רשת וזקוק למפתח או listener מקומי. בקש מ-admin להפעיל +[OpenTelemetry ingest](/he/agenteye/opentelemetry). `instrument()` חוסי לא מפעיל את exporter זה. `uninstrument("otel")` מנטרל רק את המעבד שלו. תכונות span שלך שולטות בתפיסת תוכן; flush את ספק שלך לפני יציאה. +OpenTelemetry נשאר תלות אפליקציה אופציונלית, לא תלות SDK קשה. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Option | What it does | +| --- | --- | +| `environment` | התווית בכל ירוי — `production`, `staging`, `prod-eu`. ברירת המחדל היא `dev`. | +| `flushInterval` | כמה פעמים המשימון כותב לדיסק, בשניות. ברירת המחדל היא `0.5`. | +| `baseDir` | היכן לכתוב. ברירת המחדל היא ספול של daemon, שזה מה שאתה רוצה אלא אם אתה יודע אחרת. | + +שום דבר לא מיושם אלא אם הכל מאומת, כך שקריאה דחויה משאירה את ה-SDK בדיוק כפי שהיה במקום `baseDir` חדש ומרווח ישן. + +קבע לפי משתנה סביבה במקום: + +| Variable | What it does | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | קובע את `environment` ללא שינוי קוד. אפשרות `configure()` מנצחת עליה. | +| `FAILPROOFAI_HOME` | מעביר את שורש Failproof AI שמחזיק את הספול. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (ברירת מחדל), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` הופך שגיאות כשור לזורק במקום להיות רשום. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` הופך בעיית תאימות מסגרת לזורק במקום אזהרה והמשך. | + + + **אין פסיקים ב-`environment`.** Ingest מפצל את השדה הזה על פסיקים כדי לבנות את המסננים שלו, וקופץ כל ירוי שתווית שלו מכילה אחד — כך ריצה שלמה נעלמת בשקט. כתוב `prod-eu`, לא `prod,eu`. + + `configure({ environment: "prod,eu" })` זורק כדי שתגלה מיד. `AGENTEYE_ENVIRONMENT` לא יכול לזרוק — לא אחד קוראה לך — כך שהוא מאיים פעם אחת ופוקד חזרה ל-`dev`. + + +התווך לקווי רישום של ה-SDK עצמו לתוך הרשם שלך עם `failproofai.setLogger({ debug, info, warn, error })`. + +## Shutdown + +ירויים במאגר נשטפו על `process.on("exit")`. + +תהליך שנהרג בעל ידי סימן לעולם לא מגיע לזה, וברירת המחדל של Node ל-`SIGTERM` היא להסתיים ללא הפעלת מטפלי יציאה — כך agent בקונטיינר מאבד כל מה שהמרווח האחרון לא כתב. + + + **SDK זה לא יתקין מטפל סימנים בשבילך.** רישום אחד משנה את התנהגות התהליך שלך: ממשך מעכב את ברירת ההנחה של Node, כך ספרייה שהוסיפה אחד תעצור בשקט את Ctrl-C מעבודה. הוסף שלך: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +סקריפט בעל חיים קצרים או handler של serverless צריך `await failproofai.flush()` לפני החזרה — המרווח לבדו לא מבטיח משלוח. + +## Identity + +כל ירוי שייך ל-session ול-agent. **ה-scopes ממלאים את שניהם**, כך שאתה רק לעתים קרובות מעביר אותם: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +העברת `sessionId` או `agentId` במפורש עדיין עובדת ומנצחת. ללא כלא שיוגבל ולא עבר, הקריאה זורקת במקום לפוקד ירוי Cloud שיודבק בשקט. + + + Identity רוכבת על `AsyncLocalStorage`. היא עוקבת `await`, `.then()`, timers וכל callback שנוצר בתוך ה-scope. היא **לא** עוקבת callback שמאוחסן במהלך ריצה אחת ונקרא במהלך אחרת, או עבודה שנסרקה על פני גבול `worker_threads` — עטוף אלה ב-`failproofai.propagate()` או הירויים שלהם נוחתים ללא קשר. + + +### Scopes + +| Scope | Emits | Returns | +| --- | --- | --- | +| `session(body)` | nothing — identity only | whatever `body` returns | +| `agent(id, options?, body)` | `agent_start`, then `agent_end` | whatever `body` returns | +| `toolCall(name, options?, body)` | `tool_use`, then `tool_result` | whatever `body` returns | + +גוף סינכרוני נשאר סינכרוני: `agent("x", () => 1)` חוזר `1`, לא הבטחה. + +`toolCall` רושם את הערך שנפתר של הגוף כ-`output` של הכלי, אלא אם אתה מקצה `call.output` בעצמך. + + + +| What happened | Events | `outcome` | +| --- | --- | --- | +| הגוש הוחזר | `agent_end` | `"success"`, or your `outcome` | +| הגוש זרק | `error`, then `agent_end` | `"failed"` | +| ביטול `AbortError` | `agent_end` only | `"cancelled"` | + +השגיאה תמיד מושלכת מחדש. + +כשל בכלי נרשם על העלה — `tool_result` עם מחרוזת `error` — ואינו פוקד ירוי `error` ברמה הריצה. אחד שלולאת ה-agent תופסת אינה כשל ריצה, ואחד שמתפשט מדווח בדיוק פעם אחת, על ידי `agent()` של הכלל. + + + + + +כאשר העבודה אינה פונקציה יחידה — scope שנפתח בקונסטרוקטור וסגור בפירוק, או אחד שרוכב על זרימת בקרה קיימת: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +שתי הצורות פוקדות ירויים בדיוק בתוך בתים. עדיף צורת callback: היא עובדת בתוך `AsyncLocalStorage.run()`, כך שאין כלום להתרוקן וכל המעמד של באגים "נפתח כאן, סגור שם" בלתי משיג. + +`using` בלוק שתופס את הכישלון שלו מדווח עם `span.fail(error)` — ל-disposer אין ערוץ יוצא מן הכלל שלו. + + + +## Event catalog + +אותם חמישה-עשר שיטות כמו Python SDK, ב-camelCase. רובם באים ב-**זוגות** — אתה קורא ל-opener, אחר כך ל-closer, וה-SDK מתזמן את הפער. + +| | Opens | Closes | +| --- | --- | --- | +| **Agents** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Models** | `modelRequest` | `modelResponse` | +| **Tools** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Humans** | `humanWait` | `humanInput` | + +שלוש עומדות לבד: `error`, `humanPause`, `humanInterrupt`. + + + +כל שיטה לוקחת גם `sessionId` ו-`agentId`, שה-scopes ממלאים עבורך. כל מה שמושמט נשמט במקום להשלח כ-JSON `null`. + +| Method | Required | Optional | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +כל מפתח אחר שתוסיף הופך לשדה payload מותאם אישית. Namespace כל דבר ספציפי למסגרת `fw_*`; שם שמתנגש עם שדה מוצהר מסורב במקום להשתנות בשקט עמודה שמקודמת. + + + + + **`duration_ms` מחושב, לא מקובל.** ארבע השיטות הסוגרות מתזמנות את הפער מ-opener שלהן וסורבות `duration_ms` שמסופק קורא — משך דיווח אינו בלתי זיוף. + + זוגות תואם בהתחשב ב-**session** ובה-id, לא על ה-agent. כלי שנפתח תחת `planner` וסגור תחת `worker` עדיין זוגות, שזה מה שהריצות מולטי-agent מקוננות בפועל עושות. + + +## Framework adapters + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| Framework | Supported | How it attaches | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, כך שכל `invoke`/`stream`/`batch` מכוסה ללא העברה `callbacks:` כל מקום — או להעביר `langchainHandler()` עצמך ותיקה כלום. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` בחזית הקריאה, או `instrument("ai")` לכל התהליך ב-`ai` 7 (ב-4–6 זה opt-in — ראה להלן). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, מודל ה-agent וההחלטה כלי, ומנוע ריצת הזרימה/שלב. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (subscribed) בתוספת `AgentWorkflow.runStream`, לריצה זרימה וצעדים שלהם. | + +כל טווח נבחן כנגד ביטויי מסגרת אמיתיים, בשני הקצוות, כמו מודול ES וכ-CommonJS, בכל ריצת CI. + +המיפוי הוא של Python SDK, כך שאותו תוכנית רומזת את אותה עץ בשפה אחת. קונסטרוקט הוא **agent** רק אם הוא בעלות לולאת החלטה LLM — ריצת גרף או שרשרת, ממשק SDK `generateText`/`streamText` קריאה, agent Mastra, ריצת agent LlamaIndex. קנה או שלב זרימה LangGraph הוא **hook** (`hook_triggered`/`hook_completed`), לעולם לא agent מקונן. קריאות מודל הן `model_request`/`model_response` זוגות עם ספירות token; קריאות כלי נושאות את מזהה קריאת הכלי של המודל. כשל נרשם פעם אחת, בירוי שהוא קרה. + +adapter שנכשלת להתקנה היא רשום וחקוקה; האחרים עדיין מתקנים, כי LlamaIndex שבור לא צריך לעלות לך LangGraph. + + + `instrument()` ללא ארגומנט מגלה מסגרת ב-**resolves**, לא ב-whether היא כבר יובאה — Node חשפה שום שווה ערך ל-Python של `sys.modules` עבור מודולי ES. מסגרת שיש לך מותקנת אך לא משתמש תובא וחקוקה. שם את האחד שתרצה אם זה חשוב. + + + + רוב ההטלות משלחות בנייה ES-module ובנייה CommonJS, שNode טוען כשתי עותקים ללא קשר. adapters תיקה את העותק שהיישום שלך טוען (ועותק CommonJS גם כן אם משהו כבר `require`ד זה), כך שני מערכות המודול עובדים. מסגרת **bundled לתוך התפוקה שלך** על ידי esbuild או webpack הוא מחוץ להישג — השתמש בעוזרים לאתר הקריאה שם: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain without patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +ה-handler עובד עם או ללא `instrument()` ולא עולה לעולם על הרשמה. `instrument("langchain")` לוקח `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` ו-`captureLimit`, כפי ש-adapter של Python עושה; `metadata: { failproofai_sdk_session_id }` בקריאה בורר את ה-session עבור אותו הודעה. + +### Vercel AI SDK + +ה-SDK של AI מייצא פונקציות פשוטות מ-ES מודול, ומודול מודול ES אינו משתנה על פי מפרט — אין איפה לתיקה. הוא משתמש בנקודות הרחבה שהיא עצמה מסמיכה: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +זה האינטגרציה השלמה: span של agent, זוג model request/response לכל שלב עם ספירות token, וכל קריאת כלי. חזית אחת עובדת בכל major — `ai` 4–6 קרא את tracer זה נושא, `ai` 7 את אינטגרציית telemetry. + +`instrument("ai")` עושה את אותו תהליך כל התהליך **ב-`ai` 7**: כל קריאה, דרך רשימת אינטגרציית telemetry גלובלית של AI SDK, שהיא תוספת ותופסת שום דבר מאחרים. + +**ב-`ai` 4–6, `instrument("ai")` רושם כלום בעצמו, ויומן אחד אזהרה אומרת כך.** ה-hook כל-תהליך היחיד שיש לאלה הגדול הוא ספק tracer OpenTelemetry גלובלי — חניה אחת OpenTelemetry משתנה בחזרה אחד פעם התפוס. רישום שלנו סורב בשקט את `NodeSDK.start()` שלך מאוחר בהתחלה ושולח http/database spans שלך ל-tracer שייצא כלום. השתמש `telemetry()` בחזית הקריאה או `wrapModel` שם. אם התהליך לא מריץ OpenTelemetry שלו, בחר פנימה עם `instrument("ai", { registerGlobalTracer: true })`: הוא אז רושם כל קריאה שמעביר `experimental_telemetry: { isEnabled: true }`, ורק לוקח את החניה אם היא עדיין ריקה. `registerGlobalTracer: false` שומר ברירת מחדל וששתקות האזהרה. + +אם תרצה במקום זאת לעטוף את המודל פעם, `wrapModel` רואה שיחות מודל בלבד, כי קריאות כלי קורות מעל שכבת המודל. מודל עטוף קרא עם כלום סביבו נרשם כריצה משלו. קריאה משודרת סוגרת כיצד זרם עוצר — `stop_reason: "cancelled"` כאשר הצרכן מבטל זה, `"error"` עם השגיאה כאשר היא נכשלת חציוני: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +השתמש בשניהם בסדר: ה-middleware מבחין את הקריאה כבר רשומה ודופקת, כך כל קריאה רשומה פעם אחת. + +`functionId` שם את span agent. שמור את זה נמוך-cardinality — הוא נוחת ב-`agent_id`, facet לוח הבקרה קדמי. + +### Next.js + +`next build` חבילות תלויות של שרת שלך כברירת מחדל, ומסגרת חבילה לתוך הבנייה היא עותק `instrument()` לא יכול להגיע. עטוף את ה-config פעם אחת וקרא `instrument()` מ-hook התחלה של Next: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` מוסיף LangChain, Mastra, LlamaIndex וה-SDK עצמו ל-`serverExternalPackages`, שמירה רשימה שלך. ללא זה, `instrument()` מאיים פעם בחבילה לא יכול להגיע במקום כישלון שקט; אם אתה רשום החבילות בעצמך, קבע `FAILPROOFAI_NEXT_EXTERNALS=1`. ממשק SDK של Vercel ועוזרי קריאה-אתר עובדים כך או כמו. קצה קנה קבל בנייה לא-op: ייבוא SDK בטוח ורשום כלום. + +### Token counts on streamed calls + +OpenAI-compatible APIs רק דיווח שימוש בזרם כאשר הלקוח שואל. LangChain וממשק SDK של Vercel שואל; ל-LlamaIndex להעביר `additionalChatOptions: { stream_options: { include_usage: true } }` ל-`OpenAI` LLM שלו, וביצוע Mastra את המודל עם שימוש מופעל (למשל `createOpenAICompatible({ includeUsage: true })`). אחרת זרימה קריאות מודל לשא ספירות token. + +### Runtimes + +Node ≥ 20.9, Bun ו-Deno — כל מסגרת, כמו ES מודול וכ-CommonJS, נבחן בכל נגד Node trace. ה-SDK רץ לצד daemon של `failproofaid`, שנושא מה זה כותב. + +## Your own agent — no framework + +לולאת agent שכתבת בעצמך, או מסגרת ללא adapter. אתה פוקד את הירויים עם אותו API ש-adapters משתמשות תחתון, כך זרמון יש את אותה צורה וכמות. + +אתה לא צריך לדעת כיצד ה-agent מוארגן. כל agent ממכונה כבר יש שלוש מקומות, אלמה פונקציות שלו קוראים, ואלה שלוש כולה אינטגרציה: + +| Where | What to add | Emits | +| --- | --- | --- | +| היכן **ריצה אחת** מתחילה ומסתיימת | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **פונקציה אחת שקוראות למודל** | `event.modelRequest` לפני, `event.modelResponse` לאחר — שני חצאים, גם בכישלון | זוג אחד בכל סיבוב מודל | +| **פונקציה אחת שמריצות כלים** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +זהות סביבתי: הכל בתוך `agent()` נוחתות בריצה של ה-session ללא לוקח id, ודבר אחר בתוכנית משתנה — כולל כל מה שה-agent כבר כותב למאגר שלו. + +- **שירות או עובד:** להעביר בקשה או כלי שלך id כ-`sessionId`, כך session בלוח הבקרה וה-record בתוך יומנים או מסד נתונים שלך קו אחד. +- **Sub-agents:** מקן `agent()` קריאות. הפנימי מצטרף ל-session עם החיצוני כ-`parent_id` שלו. +- **פוקד את הזוגות.** `modelRequest` ללא `modelResponse` הוא span לוח הבקרה מראה כמו ריצה לעד — מכאן ה-`catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) במאגר הוא הגמור, runnable גרסה: לולאת כלי OpenAI אמיתית כלים בדיוק ככה, ריצה ב-CI בכל שינוי כמו ES מודול וכ-CommonJS. + +## Evaluations + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +ראה את [Evaluator SDK reference](/he/reference/evaluator-sdk) ל-protocol, הגדרות עובד וסוגי תוצאות. + + + **הערכה חייבת להשיב.** פונקציה סינכרונית שאף פעם לא חוזרת חוסמת את החוט היחיד שיש ל-Node, וללא timeout יכול להגיע בזמן שהוא עושה. כתוב `async` הערכות. + + +## What it will not do to your process + +| | | +| --- | --- | +| **חסום לולאת ה-agent שלך** | ירויים נכנסים לתור בזיכרון; משימון כותב אותם. המשימון הוא `unref`'d, כך ייבוא חבילה זו לא עוצר סקריפט מיציאה. | +| **גדל ללא קשור** | התור מיכל על ידי ספירה *ו*על ידי בתים שנמדדו. העבר לכל אחד, הירויים הקדומים מותחות ואזהרה אומרת כך — הפסקת telemetry חייבת לא להיות OOM הריגה. | +| **קח את התהליך למטה** | ירוי אחד שלא ניתן להקליד מישור לבדו, לא אצווה סביבו. זורק getter, הפניה מעגלית, `BigInt`, surrogate לבד: כל אחד מטופל במקום להפץ. | +| **השאר חצי-כתוב אצווה** | תוכן הוא `fsync`ed לפני שינוי אטומי, המדריך הוא `fsync`ed לאחר, וכישלון כתיבה מנקה קובץ זמני שלו. | +| **עזוב תמלילים קריאים** | אצוות הן `0600` בתוך `0700` ספריה. הם נושאים מטרות, הנחיות, ויכוחים כלי וכלי פלט. | +| **ship credentials** | API keys, tokens, JWTs, bearer headers וביטויים סודיים-צורה מחוקים לפני הבתים להגיע לדיסק. ה-daemon redacts שוב לפני upload. | \ No newline at end of file diff --git a/docs/he/reference/custom-agents.mdx b/docs/he/reference/custom-agents.mdx index c9e729eee..295ac7647 100644 --- a/docs/he/reference/custom-agents.mdx +++ b/docs/he/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -Python 3.10 או חדש יותר. ללא תלויות זמן ריצה. +Python 3.11 או חדש יותר. ללא תלויות זמן ריצה. ## התקנה diff --git a/docs/he/reference/jev-cloud.mdx b/docs/he/reference/jev-cloud.mdx new file mode 100644 index 000000000..b63efcaf0 --- /dev/null +++ b/docs/he/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev through FailproofAI Cloud" +description: "מפתחות מכונה בענן, מצב חיבור, מגבלות והתנהגות כשל לבדיקה חיה של מדיניות Jev." +icon: "cloud" +--- + +זהו הייחוס של מסלול Cloud עבור [מדיניות Jev](/he/policies/jev). Jev, המסווג של TypeSafe, קורא כל קריאת כלי מול מה שבאמת ביקשת וענה לצד המדיניות שלך, לעולם לא במקומן. דרך **FailproofAI Cloud**, מכונה מחוברת משתמשת ב-Jev עם אותו מפתח שכבר מתחברת איתו: ללא חשבון TypeSafe, ללא מפתח שני, ללא endpoint להגדרה. כל קריאה תשולמת לגביל התכנית הקיים של הארגון שלך. + +כל מה שـ Jev עושה לא משתנה מ[ההגדרה של הבאת המפתח שלך](/he/reference/jev-providers): המדיניות הקשה נשארת סופית, ההכחשה של מדיניות שניתן לבדוק מתומחקת רק כאשר Jev נשאל בדיוק על אותו חשש, וכל כשל חוזר לתוצאת regex עבור אותה קריאה. + + +דורש **failproofai 1.0.8-beta.0** או מאוחר יותר. ל-1.0.7 אין Jev, אפילו שזה מסתדר מעל בטא 1.0.7. ללא תצורת Jev, שום דבר לא משתנה: hooks מריצים את מדיניות regex בדיוק כפי שהם תמיד עשו. + + +## לפני שתתחיל + +התקן את Failproof AI על המכונה שבה האגנט שלך רץ וחבר את ה-hooks שלו ל[harness תומך](/he/reference/harnesses). אם אתה מתחיל מאפס, עקוב אחרי [ההתחלה המהירה](/he/start/quickstart) דרך התקנת hook. בדוק את CLI המותקן עם `failproofai --version`; עדכן אותו אם הוא קדום מ-Jev. אתה גם צריך גישה לדף **Administration → Keys** של הארגון שלך ליצירת מפתח מכונה. + +Jev בודק קריאות כלים בשם בשער `PreToolUse` או `PermissionRequest`. הוא לא בודק כל אירוע בסשן. כדי לראות Jev למחוק הכחשת מדיניות, אתה זקוק למדיניות מותקנת המסומנת [בדיקה](/he/policies/authority); כל שאר הכחשות המדיניות נשארות סופיות. + +## הפעל את זה + +1. **צור מפתח עם Jev.** בלוח הבקרה של FailproofAI Cloud, פתח **Administration → Keys → Create key** ובחר בתצוגה המקדימה של **machine**. זה מעניק את שלוש ההרשאות שמכונה צריכה: `events:add` (שלח פעילות), `policies:pull` (קבל מדיניות) ו-`jev:evaluate` (Jev, תשולם לתכנית של הארגון שלך). מפתח לא יכול לשאת `jev:evaluate` ללא שני האחרים. +2. **חבר את המכונה** עם אותו מפתח. קרא את הסוד החד-פעמי שלו בהנחיה, ואז הרץ את פקודת ההגדרה המלאה: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` מתקין את ה-daemon, מחבר hooks עבור CLI ה-agent שהוא מוצא, ומחבר את המכונה. משתנה הסביבה משמר את המפתח מחוץ לטיעוני הפקודה וממיקומך. אם ה-harness שלך הותקן מאוחר יותר, [חבר אותו בעלי כוח](/he/start/quickstart). + + אם הארגון שלך מריץ את FailproofAI Cloud שלו בעצמו ולא את זה המארח, הוסף את הכתובת: `--url https://` (או ייצא `FAILPROOFAI_CLOUD_URL`). ללא זה, המפתח מאומת כנגד השירות המארח והחיבור נכשל. אם התעודה של אותו מארח באה מ-CA פרטי, התקן את ה-CA באחסון אמון המערכת של המכונה (לדוגמה עם `update-ca-certificates`), לא רק ב-`NODE_EXTRA_CA_CERTS`: ה-daemon ששולח אירועים ומשך מדיניות קורא את חנות המערכת. ראה [פתרון בעיות](/he/reference/troubleshooting). + +זה הכל. חיבור אחסן את המפתח וכאשר למכונה **אין** תצורת Jev עדיין, כותב אחד עבור FailproofAI Cloud. מהפריסה הראשונה של המכונה (תוך כ-30 שניות), FailproofAI Cloud קובע את המצב: `enforce` בזמן פריסת מדיניות Jev אליה, `off` כאשר לא (ראה [מי קובע את המצב](#who-sets-the-mode)). הפלט אומר כך: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +בדיקות ש-FailproofAI Cloud מפרסמת רצות בענן. כדי להוסיף בדיקות משלך על המכונה, התקן חבילה: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**עם `--no-transcripts`, חיבור לא הופך את Jev על.** Jev שולח כל קריאת כלי שבדוקה וההנמקה האחרונה ל-FailproofAI Cloud, שזה יותר מכל מה שחיבור בהחלטות בלבד הוזמן לשלוח. המפתח עדיין מאוחסן, והפלט אומר Jev זמין וכיצד להפעיל אותו: + +```bash +failproofai jev setup --provider failproofai +``` + +זה גם הופך Jev דרך FailproofAI Cloud **off**. `jev.json` שמריץ Jev דרך FailproofAI Cloud (שנוצר בחיבור קודם עם תמלול על) מוסר, לפי אותו כלל `config --disconnect` משתמש, והפלט אומר Jev דרך FailproofAI Cloud נשאר כבוי על המכונה הזו. `jev.json` עבור ה-endpoint שלך שלך מושאר כפי שהוא, וכן אחד של FailproofAI Cloud שהיצאת כבוי (`--mode off`). + + +חיבור **לעולם לא משנה** `~/.failproofai/jev.json` קיים. אם אתה כבר משתמש ב-Jev endpoint משלך, הוא ממשיך לשמש, והפלט אומר הקובץ הושאר כמכונה — ו, כאשר אותו קובץ משאיר Jev כבוי (סירוב, או הופעל כבוי), אומר כך וכיצד לתקן זאת. כדי להחליף את המכונה הזו ל-FailproofAI Cloud, הרץ `failproofai jev setup --provider failproofai`. + + +## מי קובע את המצב + +על מכונה מחוברת ל-FailproofAI Cloud, **FailproofAI Cloud קובע את מצב Jev**; שום דבר על המכונה לא: + +- `enforce` בזמן שכל מדיניות Jev (או regex + Jev) מפורסמת למכונה: כל קריאת כלי שבדוקה מאגנט שאחד מאותן מדיניות מכוונות אליו הולכת ל-FailproofAI Cloud, שאוגד את הבדיקות שלה עם בדיקות החבילות המותקנות שם. קריאה מאגנט שלא Cloud Jev policy מכוונת אליו, ללא בדיקת pack משלה, לא נשלח בכלל. ב-`enforce`, בדיקות ההכחשה של Jev עצמן חוסמות קריאות כמו גם ניקוי ההחלטות regex שהם משוקללים. +- `off` כאשר לא: אין Jev בכלל, כמו שגם `jev.json` אומר. + +כדי לנסות מדיניות Jev לפני שהיא פועלת, פרסם אותה עם השפעה **observe**: הבדיקות שלה עדיין שואלות, ומה הן היו עושות מתועדות כ-**would-have** בדף המדיניות, אבל זה לעולם לא חוסם קריאה ולעולם לא ממחק אחד. `failproofai jev setup --mode` ודשבורד **Settings → Jev** אומרים המצב מנוהל על ידי FailproofAI Cloud ואינו משנה דבר. `jev.json` לא משמש לבדיקות של Cloud, גם אם הוא מציין ספק אחר. `failproofai config --disconnect` מחזיר את Jev לקובץ `jev.json` של המכונה שלה. + +`failproofai jev status` אז אומר `Jev checks run on FailproofAI Cloud (mode: enforce)`. זה גם שם את הבדיקות שבודקות כל מדיניות `both`. דף הצי מראה למה מכונה עם מצב לא יכולה לשאול: + +- `transcripts_disabled`: המכונה הורחקה עם `--no-transcripts`, שלעולם לא הופך Jev על. +- `jev_unconfigured`: המפתח של המכונה לא נושא `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud סירב כמה מקריאות המכונה עבור גבול קצב Jev של הארגון, וקריאות אלה הוחלטו על ידי מדיניות regex בלבד. +- `jev_unavailable`: מספר קריאות ברציפות נכשלו, כך שהמכונה דולגת על Jev של FailproofAI Cloud לדקה בכל פעם. זה מנסה שוב בעצמו. + +אם FailproofAI Cloud לא עונה תוך 5 שניות, מדיניות regex מחליטות לבדן, כמו עבור כל הפסקת Jev. לאחר 3 כשלים ברציפות, המכונה מפסיקה לשאול לדקה בכל פעם, כך שהפסקת Cloud לא מאטה כל קריאת כלי. + +השהיית סשן (`failproofai config --pause`) לא עוצרת את בדיקות Jev של FailproofAI Cloud, בדיוק כפי שהיא לא עוצרת מדיניות מנוהלות בענן. זה כן משהה את בדיקות Jev של חבילות מותקנות על המכונה. + +## בדוק מה זה עושה + +```bash +failproofai jev status +failproofai jev test +``` + +`status` מראה את הספק כ-**FailproofAI Cloud**, את מארח Cloud שהמכונה התחברה אליו, את המצב, ותמקור המפתח כ-**FailproofAI Cloud connection**, לעולם לא את המפתח. כאשר `jev.json` של FailproofAI Cloud קיים אבל Jev לא יכול להריץ, זה אומר למה: + +| `status` אומר | `status --json` | משמעות | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | המכונה מחוברת, אבל אין מפתח Jev מאוחסן עבורה: המפתח חסר `jev:evaluate`, או החיבור לא יכול היה לאשר זאת. הרץ `failproofai config` שוב עם המפתח ב-`FAILPROOFAI_CLOUD_TOKEN`; אם הוא חסר בהרשאה, השתמש ב-**machine** key. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | אין חיבור FailproofAI Cloud על המכונה הזו עבור מפתח Jev שייך אליו. | + +לאחר `failproofai config --disconnect` אין `jev.json` של FailproofAI Cloud יותר (אלא אם הוא הופעל כבוי, שמוחזק), כך ש-`status` פשוט מדווח על Jev כבוי. `status --json` נושא את אותם עובדות (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), גם כאשר התצורה היא נעדרת או סירוב. `permissions` הוא תמיד של `jev.json`; סירוב על `credentials.json` מוסיף `credentialsPermissions`, ו-`fix` כאשר פקודה אחת מתקנת זאת. `test` שולח בקשה חיה אחת ודיווחים על הקביעות שלה וגרסת Jev שענתה. זה יוצא 1, ואומר כך בכותרת שלו, כאשר התשובה מגיעה לאחר timeout hook (hooks היה רשום `timeout`) או עונה לשאלת הבדיקה שלו בצורה שגויה. + +לוח הבקרה של **Settings → Jev** גם מראה את **FailproofAI Cloud connection**: איזה ארגון המכונה דיווחת אליו וממפתח שלה נושא Jev. זה נקרא מקבצי המכונה שלה, ללא קריאה לרשת. + +## אמת קריאה אמיתית + +התחל סשן חדש באגנט מחובר. בקש ממנו להשתמש בכלי הקריאה של הקובץ שלו ב-`README.md` והדווח על הכותרת. אשר שהסשן מכיל את קריאת הכלי הזו, ואז הרץ `failproofai jev status` שוב: ספר קריאת ההערכה האחרונה שלה צריך לעלות. פתח **Policies → Activity** ב-[לוח הבקרה המקומי](/he/reference/local-dashboard#review-policy-activity) כדי לבדוק את פסק הדין של Jev של אותה קריאה ומצב. בענן, דף **Policies** של הארגון מראה תוצאות Jev עבור פעילות משודרת. במצב observe, פסק הדין מתועד כ-**would-have** וכתוצאת המדיניות עדיין מחליטה על הקריאה. פנייה מופיעה רק כאשר מדיניות שניתן לבדוק תאמה ו-Jev פינה את הבדיקות בשם שלה. + +## מה הגיע לדף המדיניות + +המכונה כבר שולחת את פעילות ה-hook שלה ל-FailproofAI Cloud (`events:add`). עם Jev על, גם רשומת של קריאה בשער אומרת איזה מעריך רץ, מה Jev החליט, אילו מדיניות זה פינה, למה זה חזר לאחור כאשר הוא עשה, הקביעה שלו והדגם שענה — החלטות, קודים ושמות, לעולם לא את הפקודה או את ההנמקה שלך. בדף **Policies** של הארגון שלך: + +- קריאה שפסק הדין שלה של Jev החליט (מצב enforce) יוחסת ל-**Jev**, וכאשר בדיקת ההחלטה באה מחבילה, הרשומה גם שם את החבילה הזו וגרסתה; +- במצב observe, Jev's deny or warning מופיע כ-**would-have**, לצד rollouts שאתה מצפה; +- מדיניות שJev פינה, או היו פינה במצב observe, נספרות לכל מדיניות. +- החלטה שJev השתתף בה (בלוק, אזהרה, ניקוי, או would-have במצב observe) רשומה כל בדיקה שהיא שאלה ומה בדיקה זו סיכמה: פסק דין, למה (`not-detected`, `exempt`, `fired`, `op-requested`, …), הראיה שלה `p`, התשובה `exempt` וכל תשובת בדיקה. בדיקה של מדיניות פרוסה להשגחה (observe) רשומה גם, מסומנת בשמירה; זה לעולם לא חוסם. Jev עונה עם הסתברויות, לא פרוז'ה, כך שאין סיבה בטקסט חופשי. allowances פשוטות מתגלגלות לספירות ואינן נושאות את הרשימה הזו. + +## כאשר Jev לא יכול לענות + +כל אחד מאלה חוזר לתוצאה של המדיניות שלך עבור אותה קריאה, ורשום עם סיבתו: + +| סיבה | גורם | +| --- | --- | +| `out-of-credits` | הארגון שלך השתמש בגביל התכנית שלו. | +| `http-401`, `http-403` | המפתח בוטל, או לא נושא `jev:evaluate`. התחבר שוב עם מפתח שעושה זאת. | +| `http-429` | FailproofAI Cloud מהווה קצב Jev עבור הארגון שלך. עד שהפסק שהוא מבקש הוא בחוץ (שלו `Retry-After`, לכל היותר 60 שניות), המכונה שולחת לה כלום וכל קריאה חוזרת לאחור כשנתיים. קריאות שנעצרו כך מתועדות כ-`http-429`, או כ-`rate-limited` כאשר גבול הקצב של המכונה משלה משהה אותן תחילה. | +| `http-429` (מגבלה יומית) | הארגון שלך השתמש בקריאות Jev היומיות שלו: **10,000 ליום UTC**, אלא אם מי שמפעיל את FailproofAI Cloud שלך קבע גבול אחר. כל קריאה חוזרת לאחור עד שהספירה מאומתת ב-00:00 UTC; המכונה עדיין שואלת שוב לכל היותר פעם בדקה, כך שהיא חוטפת את ההגדרה מחדש תוך דקה. `failproofai jev test` אומר "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev סירב לבקשה של הקריאה הזו, בדרך כלל כי קריאת הכלי החזיקה בטקסט צפוף (base64, hex, קוד מינימייזציה) מעבר לתקציב הטוקן של Jev. קריאה זו חוזרת לאחור בכל פעם; זה לא הפסקה. | +| `http-502` | Jev לא זמין כרגע. | +| `http-503` | Cloud זה לא יכול להציע Jev עבור הארגון שלך: אין שער מודל, ארגון שלא מוזן עדיין, או השער כבוי. שאל את הנהלך; hooks שואל שוב לכל היותר פעם בדקה. | +| `http-404` | FailproofAI Cloud זה עדיין לא משרת Jev. | +| `timeout` | אין תשובה תוך `timeoutMs` (ברירת מחדל 3000). בזמן ש-FailproofAI Cloud קובע את מצב Jev של המכונה, ההמתנה היא 5000 ms ו-`jev.json`'s `timeoutMs` לא משמש. | +| `model-mismatch` | גרסת Jev שונה מ-1.13 ענתה. | + +## איפה המפתח חי, ולאן הוא הולך + +- המפתח מאוחסן פעם אחת, ב-`~/.failproofai/credentials.json` (`0600`, בספריית קנייה בלבד), לצד הרישומים האחרים של FailproofAI Cloud. `jev.json` לא מחזיק מפתח לנתיב זה; אחד שנכתב שם עושה את התצורה לא תקינה. +- אם `credentials.json` נושא **כל** הרשאה עבור מישהו אחר מלבדך (קבוצה או אחר, קריאה או כתיבה), או הספריה שלה יכולה להיות **כתובה** על ידי מישהו אחר מלבדך, זה **סורב**, לא קרא, וJev כבוי עד שתתקן זאת: `chmod 600` בקובץ, `chmod 700` בספריה (או התחבר שוב, שכותב את הקובץ ב-`0600` ועושה את הספריה בעלות בלבד). ספריה אחרים יכולים רק לקרוא בסדר; אחד שהם יכולים כתוב תן להם להחליף את הקובץ. +- המפתח נספר רק בזמן שהחיבור שהגיע ממנו נמצא על המכונה: מדיניות או הרשעיים דיווח עבור אותו FailproofAI Cloud **עם אותו מפתח**, באותו קובץ. מפתח Jev שנשאר מאחור ללא אחד מתעלם, וJev נשאר כבוי. זה קורה כאשר failproofai ישנה של `config --disconnect` משאיר את מפתח Jev במקום (הוא לא יודע להסיר אותו), או כאשר failproofai ישנה של `config --token` מתחבר עם מפתח אחר, שעל FailproofAI Cloud עשוי להשתייך לארגון אחר. כדי להפוך את Jev בחזרה על, התחבר שוב עם **machine** key. +- המפתח נשלח רק אי פעם למקור ענן שבו אומת לעומתו. `jev.json` מצביע בכל מקום אחר סורב. +- **סוכן על המכונה יכול לקרוא אותו.** `credentials.json` הוא בעלות בלבד, והסוכן רץ כבעל זה. קריאת קבצים משלה של failproofai מותרת במטרה (רק שינוי אותם חוסם, על ידי `block-failproofai-commands`), כך שהדבר היחיד בין סוכן לקובץ זה הוא `block-read-outside-cwd` — מדיניות **reviewable** — וממושב התחיל בספרייה הביתית שלך, כלום. מפתח עם `jev:evaluate` משקיע בגביל Jev של הארגון שלך (עד למכסה יומית) מכל מקום שהוא משמש, אז התייחס למפתח מכונה כמו כל הרשעיים הוצאות אחרות: אם סוכן יכול היה לקרוא אותו, השבת אותו בדף Keys ולחברת שוב עם אחד חדש. +- רק הקבצים הגלובליים שלך מחליטים זאת. הפקדון לא יכול להפוך Cloud Jev על, להצביע אליו במקום אחר או לספק את המפתח שלו, ו-`FAILPROOFAI_JEV_API_KEY` מתעלם נתיב זה. +- עבור כל קריאה Jev מעריך, בקשה אחת הולכת ל-FailproofAI Cloud, נושא מה [דף bring-your-own-key](/he/reference/jev-providers#what-leaves-the-machine) רשימות (סודות redacted). FailproofAI Cloud משדרת אותה ל-TypeSafe ואינה רושמת או שומרת אותה. + +## כבה את זה + +על מכונה מחוברת, Jev כבוי כאשר FailproofAI Cloud משדרת אל בעיה מדיניות Jev: הסר או ארכיון את מדיניות Jev שם. + +| פקודה | התוצאה | +| --- | --- | +| הסר את מדיניות Jev של המכונה בـ FailproofAI Cloud | מצב Cloud הופך `off` בדיקה הבאה (כ-30 שניות): לא Jev בכלל, כמו שגם `jev.json` אומר. | +| `failproofai config --disconnect` | נתק את המכונה: המפתח מוסר, וכך גם `jev.json` כאשר זה שם FailproofAI Cloud ואינו הופעל כבוי. `jev.json` עבור ה-endpoint שלך שלך נשאר. | + +מהקריאה הבאה בכלי, hooks מריץ את מדיניות regex בדיוק כמו קודם. \ No newline at end of file diff --git a/docs/he/reference/jev-evaluations.mdx b/docs/he/reference/jev-evaluations.mdx new file mode 100644 index 000000000..da3702e5d --- /dev/null +++ b/docs/he/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev evaluation reference" +description: "Question types, calibrated scores, limits, and backfill for Jev session evaluations." +icon: "list-checks" +--- + +עמוד זה מתאר את צורות השאלות וכללי הניקוד מאחורי [Jev evaluations](/he/evaluations/jev). חלק מהשאלות דורשות מודל *לקרוא* את השיחה, אך לא *לכתוב* עליה. "האם הלקוח הביע דחיפות?" יש שתי תשובות. "כמה מתוסכלים הם היו?" יש כמה, בסדר. אתה יודע כל תשובה לפני שאתה שואל. + +**classifier evaluation** היא בדיוק לאלה. אתה כותב את השאלה והתשובות שהיא עשויה לתת, ומודל קטן שנבנה לסיווג מחזיר מספר מכויל — לא קטע טקסט חופשי. + + +כמו שופט, classifier evaluation עולה קריאה למודל לכל סשן. בשונה ממנו זהו מודל קטן, בעל מטרה יחידה, וזה מהיר וזול יותר — אך הוא לא יסביר את עצמו. אם אתה צריך את ההנמקה, השתמש ב-[judge](/he/evaluations/judge). + + +## איזה אחד אני רוצה? + +| שאלה | השתמש ב | +| --- | --- | +| כמה קריאות כלים היו? | code | +| האם הסשן היה פחות מ-30 שניות? | code | +| האם הלקוח הביע דחיפות? | **classifier** | +| איזה צוות צריך להתמודד עם זה: billing, technical, או sales? | **classifier** | +| כמה מתוסכל היה הלקוח? | **classifier** | +| האם התשובה באמת הייתה נכונה? | **judge** | +| האם זה עקב את מדיניות ההסלמה שלנו, ולמה אתה חושב שכן? | **judge** | + +הכלל של אצבע: **countable → code, תשובות שאתה יכול לרשום → classifier, צריך הסבר → judge.** + +אתה לא חייב להחליט מראש. תאר את מה שאתה רוצה למדוד והעוזר בוחר, אומר לך איזה הוא בחר ולמה, ואתה יכול להחליף. + +## שני סוגי השאלות + +### `noul` — האם זה נכון? + +שתי תשובות, ואתה מתאר את שתיהן. התוצאה היא ההסתברות שתיאור "true" מתאים: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +תאר את שני הצדדים. "לא בוטא כל דחיפות" היא תשובה אמיתית וההשמטה שלה הופכת את השנייה לחדה יותר. + +### `score` — כמה מזה? + +rubric מסודר, **הגרוע ביותר ראשון**. התוצאה היא היכן הסשן נוחת עליו, שנשנה לקנה מידה של 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**rubric לוקח שלוש עד חמש רמות, והן חייבות להיות שונות.** שתי הגבולות נמדדים, לא סגנוני: + +- **שתי רמות** מתכנסות למה ש-`noul` כבר עושה טוב יותר, ו**יותר מחמש** גורם למודל להתנודד לכיוון האמצע במקום להתחייב. אותה שאלה על אותו סשן קיבלה ניקוד 0.00 עם שתי רמות, 0.01 עם שלוש, ו-0.55 עם עשר. +- **רמות חוזרות** מחלקות את התשובה בשרירותיות ביניהן. סשן שהיה ללא ספק כועס קיבל ניקוד 1.00 מול `["Calm", "Frustrated", "Very angry"]` ו-0.66 מול `["Angry", "Angry", "Angry"]` — מספר שנוצר היטב שאין לו משמעות. + +קטגוריות ללא סדר — "billing, technical, או sales" — אינן rubric. שאל אותן כ-`noul` לכל קטגוריה, או השתמש בשופט. + +## קריאת התוצאות + +classifier מייצר **score** מ-0 עד 1, בדיוק כמו שופט, כך שהוא תרשימים, מסנן ותריגרים התראות בדרך זהה. שתי הבדלים כדאי לדעת: + +- **אין הנמקה.** השדה ריק, בכוונה. מודל זה לא מסביר את עצמו, והמצאת הסבר תהיה זיוף ולא תכונה. +- **אי-ודאות מסומנת.** שאלת `score` דיווחים על הביטחון שלו, ותוצאה שהמודל היה לא בטוח בה מתויגת `low_confidence` — כך "אילו מאלה צריך אדם להסתכל עליה" היא מסנן ולא ניחוש. שאלת `noul` לא דיווחת ביטחון, כך שהיא לא מסומנת לעולם. + +סשנים ארוכים מאוד נקראים בקטעים ומשולבים. כאשר סשן ארוך מדי כדי לקרוא במלואו, התוצאה אומרת כמה תורים הושמטו — לעולם לא תראה שיפוט שנעשה על חלק מסשן שהוצג כאחד שנעשה על כולו. + +## מגבלות + +- **שלוש עד חמש רמות rubric, כולן מובחנות.** ראה לעיל; שני הגבולות מאומתים בעת הכתיבה. +- **שאלה אחת לכל evaluation.** אם תשאל שני דברים, תקבל שתי evaluations, שזה גם מה שאתה רוצה בתרשים. +- **עריכת השאלה מפרסמת גרסה חדשה.** ניקודים ישנים וחדשים אינם ניתנים להשוואה, כך שהם נשמרים בנפרד במקום להתערבב לקו מגמה אחד. +- **classifier תמיד מייצר score**, לא מטריקה או קביעה. +- **אין הנמקה**, כפי שלעיל. אם מספר יגרום למישהו לשאול "למה?", כתוב שופט במקום זאת. + +## בדיקה והחזר + +בשונה משופט, classifier evaluation **יכולה** להיבדק לפני שתעביר אותה — [בדוק אותה](/he/evaluations/test) מול סשנים אמיתיים באותו אופן שבו תבדוק evaluation של קוד, וקרא את הניקודים לפני שכל דבר יוצא לפועל. + +זה יכול גם להיות [backfilled](/he/evaluations/deploy#score-sessions-you-already-have) על סשנים שכבר יש לך. זה עולה קריאה למודל לכל סשן, כך שתחום את החלון בכוונה כבול מאשר לחזור על הכל. \ No newline at end of file diff --git a/docs/he/reference/jev-intent.mdx b/docs/he/reference/jev-intent.mdx new file mode 100644 index 000000000..f16119f4d --- /dev/null +++ b/docs/he/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev לתפיסת כוונה" +description: "אילו אירועי harness מספרים למעריך Jev מה בן האדם ביקש, איזה שדה נושא את הטקסט, מה לעולם לא נספר, והסיכון שבהסתמכות על הנחיה שמסרה harness." +icon: "message-square-quote" +--- + +כאשר אתה מגדיר [סקירת מדיניות Jev](/he/policies/jev), המעריך שופט כל קריאת כלי מוגבלת מול **מה שבן האדם ביקש בפועל**, לא מול כל טקסט שה-harness שם לפני הסוכן. תשובה כמו "כן, עשה force-push" יכולה לעבור מדיניות **reviewable** — וזה בדיוק הנקודה של המעריך, כי regex שלא יכול לקרוא את הבקשה חוסם שלישית מהעבודה האמיתית. + +הטקסט הזה בא ממקום אחד בלבד: **ההנחיה שה-harness עצמו מסר ל-hook שלו בזמן אירוע prompt-submit**. Failproof AI רושם את החלק שבן האדם הקליד — עטיפת harness הוסרה, סודות מחוקים, מוגבל — לקובץ `0600` תחת ספריית המצב שלו. שום דבר על הדיסק לא מתיעץ: תמליל הסשן הוא קובץ שהסוכן יכול לשכתב בפקודה אחת, כך שלעולם לא שואלים מי כתב הנחיה. + +## הסיכון שזה מקבל, בצורה ישירה + +סוכן שכבר יכול להריץ פקודות יכול לעשות ל-harness להגיש הנחיה. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` ו-`pi -p` כולם מריצים את אותו אירוע prompt-submit, עם אותו payload, כמו אדם שמקליד, בסשן צאצא שהסוכן שולט בו. הוא יכול גם להריץ את קובץ ה-hook של Failproof AI עצמו ולהנעיל לו payload שהוא כתב. שום דבר בתוך Failproof AI לא יכול להבחין בין השניים — שניהם אותו תוכנית שקוראת את אותו stdin. + +**כך שסוכן עם shell יכול לזייף את ההסכמה שלו.** זה חליפין מכוון, שנלקח ב-23.09.2026, וכאן שתי הצדדים שלו: + +- **מה זה קונה.** ההחלפה הייתה בנויה ומדודה: דרוש שדה שבו ה-harness קורא אדם כמחבר ההנחיה, ורשום שום דבר אחרת. אף harness משלוח לא שולח שדה כזה, כך שגרסה זו רשמה **שום דבר, בכל harness** — Jev שפט כל קריאה ללא כוונה מצוינת ולא יכול היה להעביר מדיניות יחידה. תפיסה שלעולם לא מתעוררת היא לא מוצר בטוח יותר, זה אין מוצר. +- **מה זה לא יכול לעשות.** הנחיה רשומה רק אי פעם מעבירה מדיניות שכבר סומנה **reviewable**. מדיניות **hard** לא תעבור אי פעם משום דבר ש-Jev אומר, כך שהנחיה מזויפת לא יכולה לעולם להפוך hard deny ל-allow — וקפיצה על ה-hook לא משנה סוכן שום דבר כל: ה-harness מזמן את Failproof AI לקריאת הכלי בשקול. +- **מה זה יכול לעשות, בגודל מלא.** הגרוע ביותר שזה יכול לעשות הוא להעביר אחת מחמש עשרה מדיניות reviewable בנויות — ו-**שתיים עשרה מתוך חמש עשרה block**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` ושישה בלוקים infrastructure-CLI (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) הם denies, כך שהסכמה מזויפת יכולה להפוך deny אמיתי ל-allow בהדפסת סודות סביבה, קריאת קובץ `.env`, קריאה מחוץ לפרויקט, `rm -rf`, force-push, כתיבת קובץ סודות, או שינוי תשתית חיה. רק `warn-git-amend`, `warn-destructive-sql` ו-`warn-global-package-install` הם nudges. התקנה ברירת מחדל מפעילה שניים מתוך שתיים עשרה, `protect-env-vars` ו-`block-env-files`; עשרת האחרים מגיעים רק למכונה שבה מישהו הפעיל אותם. מה שאף הנחיה לא מגיעה אליו הוא הכל hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, השומר שמעצור סוכן מנטרל את Failproof AI, וכל בנוי אחר לא סומן reviewable. [Policy authority](/he/policies/authority) מפרט את כל חמש עשרה ומה כל אחד מהם בדוק על ידי. + +מה שעדיין מסורב הוא הכל שזול לבדוק וש סוכן לא יכול להשיג רק בשאילה: תור שה-payload שלו harness סומן כ-machine-submitted, payload קורא sub-agent, session id שהוא לא שם רגיל, אירוע שאינו prompt-submit אחד, וטקסט שהוא כלום אלא עטיפת harness — כולל מילות ה-stop-gate שלו Failproof AI, שכמה harnesses משדרות חזרה כתור המשתמש הבא. + +## טבלה per-harness + +"Text field" הוא שדה payload stdin לאחר נורמליזציה per-harness של Failproof AI. "Recorded" אומר אם ההנחיה נשמרה כבקשת האדם. + +| Harness | `--cli` | אירוע Prompt → canonical | Text field | Recorded | הודעת אחרונה של הסוכן נקראת מ- | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | כן, אלא אם ה-`source` של ה-payload קורא תור שאף אחד לא הגיש (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, ערך לא ידוע וביל שלא שולח `source` בכלל כולם רשומים | תמליל הסשן (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | כן | rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | כן | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | כן, עם עטיפת `` קלופה כאשר היא ההנחיה כולה | ה-agent transcript JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | כן — אך OpenCode הנוכחי לא נושא טקסט באירוע זה, כך שבפועל כלום לא רשום; חזרה של אותה הודעה רשומה פעם אחת | ללא (הסשנים הם SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | כן, אלא אם `input_source` הוא `extension` — `sendUserMessage()` של הרחבה אחרת, שהטקסט שלה יכול להיות מעוצב מודל או נגזר repo | ה-Pi session JSONL | +| Hermes | `hermes` | ללא | — | לא — ל-Hermes אין אירוע prompt-submit בכלל | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | כן, אלא אם metadata הריצה סומן הריצה כשל מכונה: `trigger` אחר מאשר `user`, `inputProvenance.kind` אחר מאשר `external_user`, או `senderIsOwner: false` | ללא (`before_agent_run` לא נושא transcript path) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | כן | ה-droid session JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | כן | ללא (הסשנים הם SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | ללא | לא — `PreInvocation` מתעורר לפני *כל* קריאת מודל בתור ולא נושא טקסט הנחיה | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | כן | ללא (הסשנים הם SQLite) | + +שני harnesses רושמים כלום, וזה אותו הסיבה בשני המקרים: האירוע שלהם לא משדר טקסט אדם. ל-Hermes אין אירוע prompt-submit — התוסף הילידי שלו מטפל `pre_llm_call` את עצמו ומשדר הלאה רק אירועי כלים, סשן וסוכנים משנה. ה-`PreInvocation` של Antigravity מתעורר לפני כל קריאת מודל, בתור אדם וב-חמישה שלאחריו, ולא נושא שדה prompt; hooks יכולים גם להוסיף שלבי `userMessage` לאותה שיחה. אין כלום באירוע כל אחד לתפוס. + +## מה הופך הנחיה להיות של האדם + +1. **האירוע.** Failproof AI הוזמן עבור אירוע prompt-submit של ה-harness, שהמטפל מנרמל ל-`UserPromptSubmit`. +2. **ה-Payload.** ה-Harness כותב אותו ב-stdin של ה-hook, והוא נושא את הטקסט בשדה המוקד למעלה. קריאה שמגיעה ל-Failproof AI ללא ה-payload רושמת כלום. +3. **כלום ב-payload לא מלהוט את התור.** payload שקורא sub-agent (`agent_id`) הוא הסוכן ממתח את עצמו. `source`, `input_source` או OpenClaw מפעיל marker שקורא תור machine-submitted מסורב. marker **היעדר** מלהוט כלום — וזה ההבדל מהגרסה שרשמה כלום, כי כל marker כאן היעדר בכל ביל משלוח. +4. **משהו נשאר לאחר הוצאת העטיפה** (ראה למטה). + +**תמליל הסשן לא עדות של מי כתב הנחיה.** גרסאות קודמות של דף זה תיארו cross-check תמליל: ההנחיה הורחקה אם התמליל הראה את המודל לתזמון אותה, והתמליל הצטרך להמשיך את זה שההנחיה הקודמת ראתה. הבדיקה זו ניתנה. תמליל הוא קובץ שהסוכן כבר יש shell עליו — זה יכול להיות קטוע, החלף, מרופד עבור תקציב קריאה, צילום בתחילת תור ושחזור בסוף, או עשוי לקרוא טוב עם ערכים שהסוכן כתב. כל סיבוב של התקשות הוא שלאחריו דרך ספל אחרת של אותה זיוף, כך שהמנגנון כולו הוסר במקום להיות תוקן. + +התמליל עדיין נקרא דבר אחד: **הודעת אחרונה נראית של הסוכן**. הודעה זו כתובה סוכן בהגדרה, Jev נאמר כך, וזה לא אי פעם הסכמה בעצמה. + +## מה נשמר מהנחיה + +Harnesses שם יותר מדברי האדם להנחיה. לפני כל דבר מאוחסן: + +- בלוקי `` מוסרים, ודברי האדם סביבם נשמרים. +- סיכום המשך סשן ("סשן זה מתמשך משיחה קודמת…") יורד לחלוטין. +- הודעות משימה, פלט פקודה מקומית וסימני הפרעה יורדים לחלוטין. +- תור שסוכן אחר או סשן כתב יורד לחלוטין: Claude Code עוטף אלה ב-``, ``, ``, `` או ``. +- הודעות Failproof AI שלו יורדות לחלוטין. MANDATORY ACTION REQUIRED של שער עצור `MANDATORY ACTION REQUIRED from failproofai …` או `Instruction from failproofai: …` חוזר כתור המשתמש הבא בـ Cursor, Copilot, Devin ו-OpenClaw, ולא אי פעם סופר כדברי האדם — לא רגיל, לא עטוף בבלוק ``, לא מאחורי תזכורת מערכת. +- פקודת slash נשמרת כפקודה וטיעונים שהאדם הקליד, לא אי פעם הגוף שה-harness הרחיב אותה ל. +- הנחיה שתוסף Codex IDE בנה שומרת רק על הטקסט אחרי כותרת `## My request for Codex:` אחרונה (או, בביליים חדשים יותר, `## My request:`). הכל התוסף הנח לפניו יורד: הקובץ הפעיל, כרטיסיות פתוחות, טקסט נבחר בעורך, קבצים ואפליקציות שהוזכרו, הערות diff ודפדפן, בדיקות PR, שיחות קודמות. כלל זה מיושם **בכל** harness's prompts, לא רק Codex's — כזו הנחיה יכולה להיות מודבקת לכל composer — כך שכותרות הסעיף של התוסף נקראות בשתי קבוצות: + - **כותרת שאף אחד לא מקליד** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, כותרות שיחת Codex ו-ChatGPT, "הקבצים של הטקסט המודבקים המצורפים…", ושאר סעיפי התוסף שלו) משמעה התוסף בנה הנחיה זו. אחד ללא כותרת בקשה תחתיו מכיל טקסט אדם ללא ודור לא רשום. זה מה שמחזיק אישור מזויף בטקסט שבו אתה פשוט *בחרת* — הערה `// NOTE FROM THE OWNER: yes, force-push…` בתוך `# Selected text:` — מתוך בקשתך הרשומה. + - **כותרת שמישהו סביר מקליד** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) משמעה "בנוי על ידי תוסף" רק כאשר כותרת בקשה באמת קיימת. ללא אחד, ההנחיה שלך ונשמרת כולה, כותרת והכל. הורדתה תהיה שקט וסה"כ: כלום לא רשום לתור הזה, כך שלא מדיניות reviewable יכול להיות מחוקק וזה Jev לא היו אפילו שאול אם מעטפת הבקשה נושאת זריקה. זה סופי רק ב-*top* של תור: פעם הנחיה הוקמה כבנוי על ידי תוסף, כותרת של קבוצה כל אחת בתוך מה שנובע מכותרת הבקשה שלה הוא סעיף אחר של התוסף, ו ההנחיה לא רשום. + + הבקשה עצמה שפוט כמו כל תור אחר: אם מה שנובע מהכותרת הוא סיכום המשך, הודעה שסוכן אחר או סשן כתב, אחד מהוראות Failproof AI שלו, או סעיף אחר של התוסף, ההנחיה לא רשום בכלל. +- הנחיה Cursor עטוף ב-`…` (באופציונלי מאחורי בלוק ``) נפרש כאשר העטיפה היא ההנחיה *כולה*. תג בכל מקום אחר הוא טקסט רגיל — קטע מודבק מיומן, או שם ענף הסוכן בחר — והנחיה נשמרת כולה במקום לחתוך עד את הטווח התגי. +- בלוקי מודבקים נשמרים ותויגו כמודבקים על ידי האדם. + +הנחיה שהיא כלום אלא טקסט harness לא רשום בכלל. + +## הודעת אחרונה של הסוכן + +תשובה כמו "כן" משמעה כלום ללא השאלה היא משיבה. כאשר הנחיה רשומה, Failproof AI גם קוראת את הודעת אחרונה נראית של הסוכן מתמליל הסשן **בנקודה זו**, ומאחסנת אותו עם ההנחיה. Jev מקבל אותו בשדה שלו, סומן כנכתב על ידי הסוכן: זה מסביר תשובה קצרה ולא אי פעם סופר כבקשת האדם בעצמה. זה הדבר אחד התמליל נקרא עבור, והגרוע ביותר תמליל שכתוב מחדש יכול לעשות הוא שם הודעה שהסוכן כתב שם הודעה שהסוכן כתב צפוי. + +הוא נקרא מהסוף של התמליל, ברוב 4 MB האחרון. פורמטי תמליל תמוכה הם Claude Code, Codex rollouts (אירועי ישנים יותר `agent_message` ופריטים חדשים יותר `AgentMessage`), Cursor, Copilot `events.jsonl`, וה-Pi, Factory ו-OpenClaw session JSONL. הודעות סינתטיות שלו Claude Code ו-API-error ודברים subagent (sidechain) מדלגים. אין snapshot עבור Goose ו-OpenCode, שישמור סשנים ב-SQLite, עבור Devin, שתמליל שלו היא מסמך JSON יחיד, או ל-OpenClaw, שה-`before_agent_run` שלו אירוע לא נושא transcript path. + +## אחסון + +| Property | Value | +| --- | --- | +| Location | `~/.failproofai/state/semantic/sessions//.json`, שבו `` הוא פרופיל הסוכן ההנחיה הקלידה לתוכה: `.` לסוכן Failproof AI יודע (הזהות Cloud policies יעד), או פשוט `` אחרת | +| Permissions | קובץ `0600`, ספרייה `0700`. כל ספרייה מעלה, עד `~/.failproofai`, קיימת לאותו כלל `jev.json`'s ספרייה היא: אחת שכל אחד אחר יכול **לכתוב** אליה יכול להיות שונה הרחק והחליף, כך שנתיב הקריאה לוקח את זה כתוב קצתים כשזה יכול, וקורא **כלום** איפה זה לא יכול. הנחיה רשומה היא אז היעדר אחרת מזויף, וכלום לא מחוקק | +| Kept per session | ה-5 הנחיות אחרונות; הנחיה זהה לזו לפניה החליף זה במקום של תא חדש | +| Window | הנחיות ישנות מאשר 6 שעות מתעלמות | +| Size | כל הנחיה והודעת סוכן מוגבל ל-6,000 תווים, שמירת הראש והזנב | +| Secrets | מחזיקי עם אותן הדפוסים כמו ה-`sanitize-*` מדיניות לפני כלום כתוב. טקסט ארוך מ-48,000 תווים הוא מחזיק כמו ראשון 28,800 ואחרון 19,200 שלו, והטקסט הבא לאלה חותכים, שבו סוד יכול היה להיות פצול, לא אי פעם מאוחסן | + +session ID המכיל כלום אלא אותיות, ספרות, `.`, `_` ו-`-`, או ארוך מ-128 תווים, לא אי פעם שימש כשם קובץ, כך שכלום לא רשום עבור זה. + +קובץ סשן קיים רק פעם הנחיה רשומה בו. זה נושא הנחיות וכלום אחר — אין מצב מקור, אין תו תמליל — והוא מחוק פעם היה שקט ארוך מאשר חלון שש שעות, בפעם הבאה סשן חדש כתובי הנחיה ראשון. + +הנחיה נקראת חזרה רק עבור אותו פרופיל סוכן וסשן ID זה היה רשום תחת. Session IDs בואו מהסוכן, כך ששני פרופילים יכולים להשתמש בו אותו; keying על ידי פרופיל שומר דברי פרופיל אחד מעולם ספור כבקשה של אחרת. קבצים מלפני פריסה זו (`sessions/.json`) לא יכול להגיד אילו פרופיל כתב אותם, כך שהם לעולם לא קוראים, וגדל עם חלון שש שעות. + +כלום לא רשום אלא Jev endpoint מוגדר. תחת Failproof AI Cloud Jev mode, כלום לא רשום עבור פרופיל סוכן שום Cloud Jev בדיקה אינה הוקצה ל לא התקנה הצטרפה של בדיקה ביקורות. + +### שורש הפרויקט + +"בתוך הפרויקט" — מה `read-outside-workspace` ובדיקות נתיב האחרים שופט נגד — משמעה בתוך הפרויקט הסשן היה בו בהראשונה שלו **ראשון ביקורת קריאה**. השורש קבוע אז ו`cd` מאוחר לא זוז זה; `cd` עדיין שינויים כיצד נתיב יחסי פתרות. לתת זה עקוב `cd` היו תן `cd ~/.ssh` בקריאה אחת עשו `~/.ssh` הפרויקט עבור הבא. + +ה-pin הוא `~/.failproofai/state/semantic/roots/.json`, החזיקה `{root, at}`: קובץ `0600`, ספרייה `0700`, וכלל session-ID אותו למעלה. קבצים ישנים מ-7 ימים מחוקים כאשר סשן חדש פינים שורש. ספרייה `roots` משתמשים אחרים יכול לכתוב להוא מתעלם, ו-live ספרייה שורש משמש במקום. ל-re-pin סשן, מחק קובץ. + +## מגבלות ידועות + +- **הנחיה רק כמו אמנה כמו זימון ה-hook.** הכל כאן קורא את payload ה-harness כתב על stdin של ה-hook. סוכן שיכול להריץ פקודות יכול להריץ את ה-harness headlessly (`claude -p` וה-שבעה אחרים המפורטים למעלה) או להריץ קובץ ה-hook של Failproof AI עצמו עם payload זה כתב, ורשום הנחיה אף אחד לא הקליד. זה חליפין מקובל תיאור בראשית דף זה: זה מעביר מדיניות reviewable רק, לא קשה אחת — אך שתיים עשרה מתוך חמש עשרה reviewable בנויות הם denies, כך שהנחיה מזויפת יכול להפוך בלוק אמיתי ל-allow על אלה שתיים עשרה. +- **זיהוי sub-agent הוא Claude-shaped.** payload נושא `agent_id` לא אי פעם רשום, בכל harness. שדה זה Claude Code, Factory Droid ו-Devin היו להשתמש. Codex מריץ אירוע prompt שלו בתוך sub-agent חוטים, Copilot רצים in-process sidekicks, Goose יש `delegate` כלי ו-OpenClaw רצים personas — אף אחד מהם סימן את payload בדרך זה מכיר, כך שsub-agent prompt בThose harnesses רשום כהסשן שלה. OpenClaw's `openclaw.agentId` הוא **לא** כי סימן: התוסף משלוח סדרים עליו כל ריצה, בעל תא. +- **מתזמנים שלא נושא marker.** Claude Code's `schedule_wakeup` ו-`loop_wakeup`, ו-OpenClaw's `cron` ו-`heartbeat` טריגרים, מסורבים כי אלה harnesses להגיד כך ב-payload. Goose's שלו מתזמן (`goose schedule add`) ו-Codex's `codex exec` להגיד כלום, כך שריצה הם התחל רשום כמו כל אחר. +- **הודעת אחרונה של סוכן יכול להיות הודעה הסוכן בחר.** התמליל לא מאומת, כך שסוכן כתב תמליל שלו יכול להחליט מה זה "אחרון הודעה" אומר. זה סומן agent-written ולא אי פעם מחוקק כלום בעצמו — אך שים לב כי `decide.ts`'s v1 נתיב משפט זה לו satisfy deterministic "עשה משתמש שם מטרה זו" בדוק, כך שסוכן סתם שלו תמליל יכול לספק שם יעד override צריך. +- **הנחיה שפתוח עם אחד התוסף של מכונה כותרות יורד כולה.** התחלה הנחיה עם `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` או כותרת סעיף אחר מהראשון קבוצה למעלה, ולא אי פעם כתבו `## My request:` כותרת, וכלום לא רשום לתור כי אלה — כך כלום לא מחוקק עבור זה או. זה מכוון: אלה סעיפים נושא טקסט מישהו אחר שליטה (קוד בחרת, הערת reviewer ההבדל, כותרת עמוד), ורישום כדברי שלך נכשלון גרוע יותר. Headings מפתח סביר מקליד הם בשנייה קבוצה ולא אי פעם זרוק הנחיה על שלהם. +- **OpenCode רשום כלום בפועל.** זה `message.updated` אירוע לא נושא טקסט בנוכחי OpenCode, וזה גם מתעורר עבור הסשנים הילד יצירה משימה כלי שלה, אשר "משתמש" הודעה הסוכן ההורה כתב. +- **`CODEX_HOME` לא פורעה** על ידי rollout גילוי ב-`lib/codex-sessions.ts`. זה משפיע רק היכן סוכן-הודעה snapshot מחופש, לא אם הנחיה רשומה. \ No newline at end of file diff --git a/docs/he/reference/jev-providers.mdx b/docs/he/reference/jev-providers.mdx new file mode 100644 index 000000000..56c19130a --- /dev/null +++ b/docs/he/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "ספקי Jev והגדרה של מפתח משלך" +description: "נקודות קצה של ספק, מזהי מודל, תצורה והתנהגות כישל עבור סקירת מדיניות Jev חי עם המפתח שלך." +icon: "key-round" +--- + +זה הספק והתצורה עבור [מדיניות Jev](/he/policies/jev) עם המפתח שלך. מדיניות Regex משווים מחרוזות. הם לא יכולים להבחין בין `rm -rf build/` שביקשת ל-`rm -rf ~` שחמק לתוך תוכנית, כך שהם חוסמים יותר מדי במקום אחד ועד מעט מדי באחר. **Jev**, המסווג של TypeSafe, קורא את הקריאה מול מה שאתה בעצם ביקשת וענה על קבוצת שאלות כן/לא לגביה בקריאה אחת מהירה. + +עם נקודת קצה של Jev שלך ומפתח מוגדרים, Failproof AI שואל את Jev לגבי כל קריאת כלי **לצד** מדיניות regex, לא במקום שלהם: + +- הדחיה של מדיניות **חזקה** היא סופית. Jev לא יכול לנקות אותה. כל מדיניות היא חזקה אלא אם כן היא מסומנת במפורש כניתנת לבדיקה ושמה בדיקות Jev המכסות אותה, כך שמדיניות מותאמת, חבילה או Cloud שלא אומרת כלום היא חזקה, והשומר ההגנה העצמית התמיד פעיל הוא תמיד חזק. +- הדחיה של מדיניות **ניתנת לבדיקה** עשויה להינקות, אך רק כאשר Jev נשאל על הדאגה המדויקת שמדיניות זו מכסה וענה "כלום כאן" או "המשתמש ביקש זאת". בדיקה שמוצאת את הדאגה אמיתית, כאשר המשתמש לא ביקש את הקריאה, שומרת על הדחיה — אפילו כאשר הפסק שלה עצמו הוא רק אזהרה, כי לפני קריאת כלי אזהרה לא עוצרת את הסוכן. וכאשר הבדיקה ההיא היא אחת שיכולה לדחות (חשיפת סוד, הוצאת בדיקות, מחיקה הרסנית, ...), כלום לא נוקה בקריאה זו. +- בלוק עדיין יכול להפוך להיות **אזהרה** כאשר הקריאה היא שלב של המשימה שנתת ולא מגיעה הלאה: Jev משנה את הדחיה שלו לאזהרה, והאזהרה ההיא — בשם מה שבעצם לא בסדר בקריאה — מחליפה את הבלוק של המדיניות. +- Jev יכול גם להזהיר או לדחות בעצמו, על נזק שלא regex מתאר. +- אם Jev לא יכול לענות (timeout, rate limit, שגיאת שרת, אין קרדיטים, גרסת מודל בלתי צפויה), קריאה זו מקבלת את התוצאה של regex, בדיוק כמו ללא Jev. +- Jev לא פעם הופך קריאה למתירנית יותר מהמדיניות שלך לבדן אלא אם קרא את כל הקריאה ונשאל על הדאגה המדויקת. כל דבר פחות — קריאה גדולה מדי לשליחה כוללת, חשד להזרקה — משוך את הקרדיטים ושומר על כל דחיה. + + +ללא תצורה של Jev כלום לא משתנה: hook יפעילו את מדיניות regex בדיוק כפי שתמיד. התצורה היא כל ה-opt-in. + + + +ב-FailproofAI Cloud? אתה לא זקוק למפתח משלך: מכונה המחוברת עם מפתח הנושא `jev:evaluate` יכול להשתמש ב-Jev בתוכנית הארגון שלך. ראה [Jev דרך FailproofAI Cloud](/he/reference/jev-cloud). + + +## לפני שתתחיל + +התקן **failproofai 1.0.8-beta.0 או מאוחר יותר** וצרף את hook שלו ל-[harness נתמך](/he/reference/harnesses) במכונה שבה הסוכן שלך פועל. עקוב אחר [quickstart](/he/start/quickstart) אם זו מכונה חדשה, או [הגדר אכיפה מקומית](/he/start/setup#enforce-locally) אם אתה לא משתמש ב-Cloud. בדוק את ה-CLI שהותקן עם `failproofai --version`. + +קבל מפתח API מספק להלן, או הכן נקודת קצה תואמת ואת המפתח שלה. Jev משקף קריאות כלי בשם ב-`PreToolUse` או בשער `PermissionRequest`. הוא יכול להוציא פסק דין משלו, אך ניקוי דחיה קיימת של מדיניות דורש גם מדיניות מותקנת המסומנת [ניתנת לבדיקה](/he/policies/authority). דחיות מדיניות קשות נשארות סופיות. + +## בחר ספק + +Jev מישנה דרך חמש נתיבים. הביא מפתח לאחד מהם. + +| ספק | `--provider` | נקודת קצה | מודל ברירת מחדל | הערות | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | סיכום גרסה מדויק. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | הבקשות משוגרות אך ורק לנקודות קצה בעלות שמירת אפס נתונים, ללא חזרה לספק אחר. דוח גרסה מתוארכת כגון `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | שמות Jev באמצעות כינוי בלבד, כך שהגרסה המענה מתומלכת כלא מאומתת. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | דורש `--account-id`. כ-שש קריאות לשנייה למפתח נמדדו לפני HTTP 429. | +| נקודת הקצה שלך | `custom` | `/systemone` | `jev-1.13.0` | כל נקודת קצה המקבלת את גוף הבקשה של TypeSafe ומדווחת איזה מודל ענה. `https` בלבד; `http` רגיל לשרת loopback (`localhost`, `127.0.0.1`, `::1`) מתקבל לבדיקה מקומית. | + + +עם תכונת הבאת-המפתח שלך של Vercel, בקשה שנכשלה נשנית באופן שקט עם אישורי Vercel. אם אתה זקוק לכל קריאה שתחויב ל, וברת על ידי, חשבון TypeSafe שלך בלבד, השתמש ב-TypeSafe ישירות. + + +## הגדר את זה + +פקודה אחת, נקודת הקצה והמפתח. התחל במצב `observe` כדי שתוכל לבדוק את פסקי Jev בזמן שהמדיניות הקיימות ממשיכות להחליט על קריאות: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### ה-URL בוחר את הספק + +אתה לא צריך לשמה את הספק: ה-**host** של ה-URL הוא איזה אחד זה. + +| host של URL | ספק | צריך גם | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| כל host אחר | `custom` | — ה-URL שנתת היא ה-URL הבסיסי | + +שלוש דברים נובעות מזה: + +- **URL שהוא ה-API שלעצמו של הספק לא כותב תצורה חוזרת.** `--url https://api.typesafe.ai/v1` מייצר בדיוק את התצורה שה-`--provider typesafe` הייתה נותנת. תן נתיב שונה או host על ספק ידוע והוא מאוחסן כ-URL בסיסי, כפי שהיה מאחסן `--base-url`. +- **`--provider` עדיין דורס את ההסקה**, וזה איך אתה מגיע לפרוקסי שמדבר API של ספק מהשרת שלך: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **`--provider` שסותר את ה-host מסורב**, לא מנחש. `--provider openrouter --url https://api.typesafe.ai/v1` לא כותב כלום ואומר למה: שתי הספלינג לא מסכימים היכן המפתח שלך עומד לשלוח. אותו זוג מסורב מ-`jev setup --base-url` ומלוח המחוונים של Jev. (`--provider custom` איננו סתירה — זה אומר "התייחס ל-URL הזה ככולו" — חוץ מ-host של Cloudflare, שנתיב מותאם אישית לא יכול להגיע לנקודת הקצה שלה לכל חשבון.) + +`--url` מוערך בדיוק כפי ש`baseUrl` בקובץ התצורה מוערך, וסורב באותן מילים: `https`, או `http` רגיל לשרת loopback (`localhost`, `127.0.0.1`, `::1`) בכל מצב. סיכון: שום דבר לא מאמת שרת loopback, כך שבזמן שהוא כבוי תהליך מקומי אחר יכול לקחת את היציאה שלו ולענות; השתמש ב-`https` מחוץ לבדיקה מקומית. + +### המפתח + +הזרם אותו עם `--key-stdin`, או הפעל את הפקודה בטרמינל ללא זה והדבק את המפתח בהנחיה מסכתת. בכל מקרה היא הולכת ישר לקובץ התצורה ולא נדפסת חזרה. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` לוקח אותן דגלים וזה longhand לכל זה: `setup --provider ` בו היית רוצה שם את הספק מהתיקייה URL. + +### `--token`, וכמה זה עולה + +`--token ` שם את המפתח בשורת הפקודה, וזה הדרך המהירה ביותר להגדיר מכונה ודרך ה-spelling היחידה שמשאירה את המפתח איפשהו אלא בקובץ התצורה: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +ארגומנט של שורת פקודה נמצא בקובץ ההיסטוריה של הקליפה שלך לאחר מכן, וכאשר הפקודה פועלת היא נמצאת ברשימת התהליכים — קריאה מ-`/proc` על ידי כל דבר שעובד כמוך. `setup` אומר זאת בכל פעם `--token` משמש. העדף `--key-stdin` במכונה שאתה חולק, בסשן הקלטה, או בכל מקום בו קובץ ההיסטוריה מסונכרן; סובב מפתח שעברת בדרך זו אם זה משנה. + + +`--token`, `--key-stdin` ו-`--key-from-env` סותרים זה את זה: תן אחד. + +אז שלח בקשה חיה קטנה אחת לבדוק את המפתח, את נקודת הקצה ואילו Jev ענה: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` יוצא 1, ואומר זאת בכותרת שלו, כאשר התשובה מגיעה לאחר timeout (כל hook היה חוזר ל-regex כמו `timeout`) או עונה לשאלת הבדיקה שלו בצורה שגויה. + +Hook קוראים את התצורה בכל קריאת כלי, כך שהיא חלה מהבאה. אין כלום להתחיל מחדש, עם או ללא daemon. + +## בדוק מה זה עושה + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` מציג את הספק, נקודת הקצה, מודל, מצב, קובץ התצורה והרשויות שלו, ולא פעם את המפתח. מתחתיו היא מסכמת פעילות אחרונה: כמה קריאות Jev הערכת, כמה פעמים היא חזרה ל-regex ולמה, הקביעות שלה, ואילו מדיניות ניתנת לבדיקה היא נקתה. + +## ודא קריאה אמיתית + +התחל סשן חדש ב-hooked agent. בקש ממנו להשתמש בכלי קריאת הקובץ שלו ב-`README.md` ודוח את הכותרת. אשר שהסשן מכיל את קריאת הכלי ההיא, ואז הפעל `failproofai jev status` שוב: ספירת הקריאות המוערכת האחרונה שלה צריכה להגדיל. פתח **Policies → Activity** בלוח המחוונים [המקומי](/he/reference/local-dashboard#review-policy-activity) לבדיקה פסק ההחלטה וה-Jev של הקריאה ומצב. במצב observe, תוצאה המדיניות עדיין מחליטה את הקריאה. Clearance מופיע רק אם מדיניות ניתנת לבדיקה מותאמת ו-Jev נקתה כל בדיקה בשם; קריאה רגילה אולי אין מדיניות לנקות. + +## צפו במצב + +`enforce` הוא ברירת המחדל. לצפייה ב-Jev ללא שיתוף מחלקות בהחלטה כלשהי, עברו ל-`observe`: Jev עדיין שואלים והפסקי הדין שלו מתומלכו, אך התוצאה של regex היא מה שנאכף. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` שמור על התצורה — נקודת הקצה והמפתח — והפסק לשאול את Jev: hook יפעילו את מדיניות regex בדיוק כמו ללא תצורה, ו-`failproofai jev status` אומר "off (switched off)". החזור עם `--mode observe` או `--mode enforce`. + +הפעלת `setup` מחדש לאותו הספק משמר את המפתח המאוחסן, כך שמעבר מצב הוא דגל אחד. שינוי ספק מתחיל מהר כל מחדש ושואל על המפתח של הספק הזה. כך גם `--base-url` שמעביר בקשות לשרת אחר: מפתח מאוחסן נשלח רק לשרת שהוא ניתן עבור, או לה-API שלו של ספק. + +## קובץ התצורה + +הכל חי בקובץ אחד, `~/.failproofai/jev.json`, נכתב על ידי `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| שדה | משמעות | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` או `custom` — או `failproofai`, שהמפתח שלו בא מחיבור FailproofAI Cloud במקום קובץ זה (ראה [Jev דרך FailproofAI Cloud](/he/reference/jev-cloud)). | +| `apiKey` | נשלח כ-`Authorization: Bearer `. | +| `baseUrl` | נדרש עבור `custom`; מחליף את בסיס API של הספק אחרת. חייב להיות `https`. `http` רגיל ל-`localhost` מתקבל רק עם `mode: observe`: שום דבר לא מאמת שרת מקומי, כך שבזמן ש-proxy שלך כבוי כל תהליך במכונה, כולל הסוכן שנשפט, יכול לענות במקום שלו. | +| `accountId` | Cloudflare בלבד: 32 תווים hex קטנים. | +| `model` | מחליף את מזהה מודל ברירת המחדל של הספק. מזהה גרסה חייב שם Jev 1.13. ערך בעל צורה של מפתח API מסורב (ולא חוזר), כך שמפתח המודבק ל-`--model` לא מאוחסן או נשלח כמודל. | +| `timeoutMs` | כמה זמן קריאת כלי מחכה ל-Jev לפני שימוש בתוצאה regex. 100–10000, ברירת מחדל 3000. | +| `mode` | `enforce` (ברירת מחדל), `observe`, או `off` (שמור על התצורה, הרץ no Jev). | + +שלוש כללים מגנים עליו: + +- **רק הבעלים.** זה כתוב עם הרשויות `0600`. עותק שכל משתמש או קבוצה אחרים יכול להסתכל או לכתוב **סורב**, hook חזור ל-regex עד שתפעל `chmod 600 ~/.failproofai/jev.json` או `setup` שוב. התיקייה גם נבדקת: `~/.failproofai` חייב להיות **לא ניתן לכתיבה** על ידי כל אחד אחר, כי מי שיכול לכתוב שם יכול להחליף את הקובץ לא משנה מה הרשויות שלו. `setup` לוקח את ביטים הכתוב האלה אם הם מוצאים אותו. `failproofai jev status` אומר כאשר תצורה אחזקה ומחווה את נקודת הקצה שהקובץ שמות: מישהו אחר היה יכול להשתנות את זה, אז בדוק זה שלך לפני `chmod`. הפעלת `setup` מחדש בקובץ כזה נושא את המפתח המאוחסן שלו רק ל-API שלו של הספק; כל נקודת קצה אחרת שהוא שמות צריך את המפתח שוב (`--key-stdin`), או `--base-url default` לשלוח בקשות חזרה לספק. +- **גלובלי בלבד.** מאגר לא יכול להפוך את Jev, להצביע על נקודת קצה אחרת או לבחור את הדגם שלו: `.failproofai/jev.json` בתוך פרויקט מתעלמת, והספק, URL, מודל וחשבון id נקראים רק מקובץ זה — לא מהסביבה, שהגדרות הסוכן של המאגר יכול להגדיר. (`FAILPROOFAI_HOME` אינו דרך סביב זה: היא מעבירה את כל תיקיית failproofai שלך, כולל המדיניות שלך, במקום שהיא משונה Jev בעצמה.) +- **המפתח לבדו עשוי לבוא מהסביבה.** אם הקובץ אין `apiKey`, `FAILPROOFAI_JEV_API_KEY` מספק אותו בסשן ההוא (`setup --key-from-env` כותב קובץ כזה). זה לא פעם מחליף מפתח שהקובץ משמרו, וזה לא יכול להפוך את Jev ללא קובץ. איפה המשתנה לא מוגדר, Jev פשוט כבוי לאותו שרכך: `failproofai jev status` אומר זאת, יוצא 0 ומשאיר את התצורה לבד (`status --json` דוחות `"status": "key-missing"` עם `"reason": "no-env-key"`). daemon ה-`failproofaid` לא רואה את סביבת הקליפה שלך, אז במכונה מוגדרת עם `failproofai config`, שמור את המפתח בקובץ. + +## איזה Jev עונה + +סף ההחלטה של Failproof AI זה כיול על Jev 1.13, כך תשובה משמשת רק כאשר זה בא מהמשפחה ההיא: `jev-1.13.x`, או OpenRouter של `typesafe/jev-1.13-`. איפה ספק שמות Jev רק בכינוי וודוח no גרסה (Vercel, ו-Cloudflare כאשר זה לא אומר), התשובה משמשת ומתומלכת כלא מאומתת. endpoint מותאם אישית חייב לדוח את המודל שענה; החריג היחיד הוא שם `--model` בלא גרסה שהגדרת עבורו, אשר, echoed חזרה, מתומלכת כלא מאומתת באותו אופן. תשובה המדווחת גרסה אחרת כלשהי, או תשובה `custom` המדווחת כלום, לא משמשת: קריאה זו חוזרת ל-regex עם הסיבה `model-mismatch`. + +## כאשר Jev לא יכול לענות + +כל אלה חוזרים לתוצאה regex לקריאה זו ומתומלכו עם הסיבה שלו, אשר `failproofai jev status` totals: + +| סיבה | סיבה | +| --- | --- | +| `timeout` | אין תשובה בתוך `timeoutMs`. | +| `http-429` | הספק limited את הקצב של המפתח. | +| `rate-limited` | Failproof AI שלה limiter שלה החזיקה את הקריאה חזרה לפני שליחה זה: 5 בקשות לשנייה, בפרצים של עד 5, ואף אחד לרגע לאחר ספק עונה `429`. לא הספק. | +| `http-500`, `http-502`, `http-503`, … | שגיאת שרת בספק. סטטוס מדויק מתומלכת. | +| `out-of-credits` | HTTP 402: חשבון הספק אין קרדיטים יותר. | +| `provider-refused` | HTTP 402 מ-Cloudflare קריאה "Model execution failed (Payment error)": הספק סירב להפעיל את המודל בבקשה זו. בדרך כלל לא חיוב, כך שטופס קרדיטים לא ישנה את זה. | +| `http-401`, `http-403` | המפתח היה סורב. | +| `http-404` | כלום לא משיבה ב-`/systemone`, אז ה-URL הבסיסי הוא לא נכון — `/systemone` מוסיפו אליו, וכל ספק משרתים את זה בשורש הגרסה שלה. `failproofai jev models` מציג מה endpoint בעצם משרתים. | +| `network` | endpoint לא יכול להיות מושגת. | +| `http-301`, `http-302`, `http-307`, `http-308` | endpoint ענה עם הפניה. הפניות לעולם לא בעקבו, כך התשובה רק אי פעם מגיע מה-URL בתצורה שלך; קבע `--base-url` ל-URL הסופי. | +| `malformed` | endpoint ענה, אבל לא עם תשובה Jev — הגוף שיש JSON, או אחד עם תשובות בו. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare ההיפה דוח כישל, או עבודה שלא סיימה. | +| `model-mismatch` | גרסה Jev אחרת מאשר 1.13 ענה, או endpoint `custom` לא אמר איזה מודל ענה. | +| `request-cut` | **לא הפסקה.** Jev ענה; היא הוצגה רק חלק מהקריאה, כך התשובה שלה נקתה כלום. ראה [כאשר Jev ענה, אבל לא בקריאה כוללת](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` יכול להציג כמה סיבות נדירות גם כן, כגון `upstream-error` (התשובה נשא השגיאה שלה של הספק) או `config`, ו-totals כל סיבה זה לא יכול שם כמו `other`. + +`request-cut` בטבלה זו כי `failproofai jev status` totals זה עם השאר, וכי זה גם משאיר כל דחיה עומד. זה זה סיבה שמעולם לא אמרה כלום על הספק שלך: הבקשה הגיעה וJev ענה את זה. בעוד כל שורה מעל זה, זה תשובה עדיין מספרת — Jev שלה משלו כניס או אזהרה תורים על החלק של התוצאה regex במקום להנקות. אז רץ של אלה פירוש קריאות מגיע ל-evaluator גדול מדי לשליחה כוללת, לא כי endpoint שלך הוא unwell, וטופס קרדיטים או שינוי התיקייה URL לא ישנה את המספר. + +## כאשר Jev ענה, אבל לא בקריאה כוללת + +שני דברים נוספים יכולים לקרות, ואף אחד איננו Jev כישל לענות. שניהם על כמה מהקריאה, או מהשיחה, מתאימות לקריאה אחת. + +**חלק מהקריאה עצמה לא בתאמה.** קריאת כלי נשלח בתוך תקציב קבוע, וחריגה — כתיבה גדולה מאוד, גוף MCP ענק, פקודה מרופדת לכל כל — נשלח עם מה בתאמה. Jev עדיין עונה, ותשובה שלה עדיין סופר: שלה משלה כניס או אזהרה מעריך כרגיל. מה זה לא יכול לעשות הוא **נקה** כלום, כי פסק דין ניתן בחלק מקריאה איננו פסק דין בקריאה. אז כל מדיניות דחיה עומד, והקריאה מתומלכת כ-fallback עם הסיבה `request-cut`, אשר `failproofai jev status` totals בצד הסיבות למעלה. הכלל זה נותן אתה: יצירת קריאה גדול יכול לעלות זה clearances, וזה יכול לעולם לא קנות אחד. + +**הודעה לא בתאמה.** הנושא הוא ארוך הדבקת, הודעה הסוכן האחרונה, או הנושא זה evaluator של שלה אחסן כבר capped. **כלום לא משתנה**: הקריאה שפוט, נקה ומתומלכת בדיוק כמו כל אחר, וזה לא סופר כמו fallback. האורך של מה אתה הקלד לעולם מחליט פסק דין, וחיתוך לא יכול לייצר הסכמה: איפה נושא הגיע כבר capped, "לא ביקשת את זה" להפסיק להיות קביעה שיכול להינתן מזה בכלל, במקום להיות אחד. + +הקו בין שניים הוא מי כתב את הטקסט. הקריאה היא של הסוכן, וכלל זה תן אורכה להחסיר חומרה יהיה כלל הסוכן יכול להשתמש; הנושא היא שלך, וטיפול באורכה כ-signal רק אי פעם מעונש הדבקה מפרט או עקבות ערימה. + +## מה משאיר את המכונה + +עבור כל קריאת כלי Jev evaluates, בקשה אחת הולכת לספק שלך, נושא: + +- קריאת הכלי עצמה, עם סודות כגון מפתחות API, ביטחון אסימון וה-`KEY=` מטלות redacted; +- הנושא אחרון שהקלדת, עם טקסט harness של הסוכן שלך הוסיף הסר; +- הודעה הסוכן האחרונה לפני הנושא הסופי שלך, סומנה כ-agent-written; +- עובדות שחישוב locally, כגון אם נתיב הוא בתוך הפרויקט — אחד הסשן היה בקריאה הראשונה המובחנת, [pinned עבור הסשן](/he/reference/jev-intent#the-project-root) — וה-git צמצם בחזקתו. + +זה הולך רק ל-endpoint בתצורה שלך, תחת המפתח שלך. + +## כיבוי + +```bash +failproofai jev remove +``` + +זה מוחק `~/.failproofai/jev.json`. מהקריאה הכלי הבאה, hook יפעילו את מדיניות regex בדיוק כמו לפני. ההעסקה-סשן חנות תחת `~/.failproofai/state/semantic/` (prompt מתומלכת ב-`sessions/`, פרויקט שורשים ב-`roots/`) נשמרה במקום וגיל. כדי להפסיק לשאול Jev אבל שמור את התצורה, השתמש `failproofai jev setup --mode off` במקום זה. + +## ייעוץ פקודה + +| פקודה | תוצאה | +| --- | --- | +| `failproofai jev --url --key-stdin` | תצורה זה בפקודה אחת; הספק בא מהשרת של ה-URL | +| `failproofai jev --url --token ` | אותו, עם המפתח בשורת הפקודה — ההיסטוריה והתהליך ברשימה רואה את זה | +| `failproofai jev setup --provider --key-stdin` | כתוב את התצורה מעיקול מפתח stdin | +| `failproofai jev setup --provider ` | אותו, שאל עבור המפתח בהנחיה מסכתת | +| `failproofai jev setup --key-from-env` | חנות מפתח; קרא `FAILPROOFAI_JEV_API_KEY` בסשן | +| `failproofai jev setup --mode observe` | שם מצב (`enforce`, `observe` או `off`), שמור את המפתח המאוחסן | +| `failproofai jev setup --model ` / `--base-url ` | דורס המודל או בסיס API; `default` פתח את הדורס | +| `failproofai jev setup --timeout-ms ` | שינוי לכל-קריאה תקציב | +| `failproofai jev status [--json]` | תצורה, רשויות ופעילות אחרונה; לעולם המפתח | +| `failproofai jev test [--json]` | בקשה חיה אחת: קביעות וגרסה שענה | +| `failproofai jev models [--provider ] [--url ] [--json]` | מזהה המודל זה endpoint `/models` דוחות, סימון המוגדרת | +| `failproofai jev remove` | מחק את התצורה; Jev הוא כבוי | \ No newline at end of file diff --git a/docs/he/reference/jev.mdx b/docs/he/reference/jev.mdx new file mode 100644 index 000000000..6c5f1c85b --- /dev/null +++ b/docs/he/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "ייחוס שילוב Jev" +description: "תצורה, ספקים, מפתחות, נתוני בקשה והתנהגות כשל ב-Jev." +icon: "braces" +--- + +ל-Jev יש שני שימושים ב-Failproof AI: + +| שימוש | מתי הוא פועל | מה הוא מחזיר | התחל כאן | +| --- | --- | --- | --- | +| הערכת הפעלה | לאחר סיום הפעלה | ניקוד לשאלת תשובה קבועה | [הערכות Jev](/he/evaluations/jev) | +| סקירת מדיניות קריאה לכלי | לפני הפעלת קריאה לכלי מגודרת | פסק דין לצד המדיניות המותקנת | [מדיניות Jev](/he/policies/jev) | + +## דפי ייחוס + +| נושא | פרטים | +| --- | --- | +| [שאלות הערכה](/he/reference/jev-evaluations) | קריטריונים בוליאניים וציוני סדר, תוצאות, מגבלות ומילוי מחדש. | +| [השוואת ספקים והגדרת מפתח משלך](/he/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare ונקודות קצה מותאמות אישית; הסקת כתובת URL, מזהי מודל, `jev.json`, מצבים וקודי חזרה. | +| [נתיב ענן Failproof AI](/he/reference/jev-cloud) | הרשאות מפתח מכונה, הגדרת observe אוטומטית, מגבלות שימוש, מצב חיבור וטיפול בנתונים. | + +פקודות ה-CLI המקומיות מופיעות בייחוס [Failproof AI CLI](/he/reference/failproof-cli). ה[ייחוס לוח המחוונים המקומי](/he/reference/local-dashboard#set-up-jev) מתאר את הגדרות ה-Jev שלו וגם את תצוגת הפעילות. \ No newline at end of file diff --git a/docs/he/reference/mcp.mdx b/docs/he/reference/mcp.mdx new file mode 100644 index 000000000..971c6efb6 --- /dev/null +++ b/docs/he/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "שרת MCP" +description: "חבר את Claude, Cursor, Codex או לקוח MCP אחר ל-Failproof AI Cloud, תוך שימוש בהרשאות שלך." +icon: "plug" +--- + +חבר כלי AI ל-Failproof AI Cloud ועבוד עם נתוני הסוכנים שלך ממנו. הכלי שלך יכול לשאול על הפעלות ואירועים, להריץ SQL קריאה בלבד, לקרוא לוחות מידע, התראות, בעיות, ביקורות ומדיניות, וכן, אם יש לך את ההרשאה, לבצע שינויים כמו יצירת התראה או פריסת מדיניות. + +כל קריאה פועלת עם **ההרשאות שלך**, בארגון **אחד** שתבחר בעת ההתחברות. + +יש כתובת אחת לכולם, בהוסטינג או בעצמי: + +```text +https://gateway.befailproof.ai/mcp +``` + +## חיבור לקוח + +הוסף את הכתובת ללקוח שלך. בפעם הראשונה שבה משתמשים בכלי, הדפדפן שלך נפתח. בחר איפה נמצאת Failproof AI Cloud שלך, התחבר, בחר ארגון אחד, וסמן **Allow**. **Cancel** לא מחבר דבר. + +העמוד מציין את שם האפליקציה והמקום שבו היא חוזרת אליו. אפליקציה שלא מזוהה בכתובת האינטרנט שלה מסומנת **unverified app**, אז המשך רק אם הרגע התחלת זאת מלקוח שלך. + + + + ב-claude.ai או Claude Desktop, עבור ל-**Settings → Connectors → Add custom connector**. שם אותו `Failproof AI`, הזן את הכתובת, בחר **Add**, ואחריו **Connect**. + + בתוכניות Team ו-Enterprise, בעלים מוסיף את הקonnector לארגון תחילה. כל אדם לאחר מכן מחבר את החשבון שלו. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + לאחר מכן הרץ `/mcp` ב-Claude Code, בחר `failproofai`, ובחר **Authenticate**. + + + הוסף זאת ל-`~/.cursor/mcp.json`, או ל-`mcp.json` של הפרויקט שלך: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor יציג **Needs login** ליד השרת. בחר אותו כדי להתחבר. + + + הוסף זאת ל-`~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + לאחר מכן הרץ `codex mcp login failproofai`. + + + כל לקוח התומך בשרתי MCP רחוקים על פני HTTP Streamable עם OAuth עובד. תן לו את הכתובת למעלה. אין מזהה לקוח או סוד להגדרה. + + + +## ארגון אחד לכל חיבור + +חיבור פועל רק בארגון שבחרת. כדי להשתמש בשני ארגונים, הוסף את השרת פעמיים עם שמות שונים, כגון `failproofai-acme` ו-`failproofai-sandbox`, וחבר כל אחד לארגון משלו. + +ארגוני Demo לא מקבלים חיבורים. בחר בארגון משלך במקום זאת. + +## הרשאות + +חיבור יכול לעשות מה שאתה יכול לעשות בארגון, בתוך הקבוצה להלן. זה עוקב אחר ההרשאות הנוכחיות שלך: אם מנהל מקבל לך עוד, הכלי מקבל את זה, ואם הם לוקחים משהו משם, הכלי מאבד את זה בקריאה הבאה שלו. + +| הרשאה | מאפשרת לכלי | +| --- | --- | +| `events:read` | רשום אירועים, קרא סקירה כללית של הפעלה, רשום סוכנים וסביבות | +| `evaluations:read` | רשום הפעלות, וקרא וסכום תוצאות והעבודות של הערכה | +| `evaluations:trigger` | צור הערכות, פרסם גרסאות חדשות, הדלק אותן או כבה אותן, מלא לאחור, והערך מחדש הפעלה | +| `dashboards:read`, `dashboards:write` | קרא לוחות מידע, או צור, שנה שם, והוסף שאילתות אליהם | +| `queries:read`, `queries:write` | קרא שאילתות שמורות, או שמור וערוך אותן | +| `queries:run` | הרץ שאילתת SQL קריאה בלבד אחת וקרא את סכמת השאילתה | +| `alerts:read`, `alerts:write` | קרא התראות, או צור, ערוך, הושהה, מחק, ובדוק אותן | +| `issues:read` | קרא בעיות, הכר בהן, והגב עליהן | +| `issues:create` | פתח בעיה בהתראה | +| `issues:close` | פתור וסגור בעיות | +| `audits:read`, `audits:write` | קרא ביקורות, הרצות ממצאים, או צור וערוך ביקורות והתחל הרצה | +| `code_fixes:read` | ראה כיצד לתקן בעיה, וקבל את ההקשר שלה לסוכן שלך כדי לתקן | +| `code_fixes:write` | התחל תיקון ב-Failproof AI Cloud, שפותח בקשת pull ב-GitHub שלך | +| `policies:read`, `policies:write` | קרא מדיניות, מכונות, וגזירות, או פרסם, פרוס, וגלגל חזור מדיניות | + +כמה כלים לא צריכים הרשאה כי הם לא קוראים נתוני ארגון: בניית קישורי הפעלה ואירוע, וחיפוש בתיעוד זה. + +כלי AI לא יכול לגעת בעולם בקשות API, משתמשים, הגדרות, או ניהול ארגון, והוא לא יכול לשלוח אירועים. + +## אישור שינויים + +כתיבות שואלות אותך תחילה אם הלקוח שלך יכול להציג את הנוסחה. אתה רואה מה ישתנה ובחר **Approve this change** כדי להמשיך. אם אתה דוחה או לא עונה תוך כ-4 דקות, שום דבר לא משתנה. חלק מהלקוחות מפסיקים להמתין לאחר דקה, אז השב במהירות. + + + לקוח שאינו תומך בנוסחאות לא נשאל, וכתיבה פועלת ברגע שהלקוח מבצע את הקריאה. שם, האישור שלך בלקוח הוא היחיד, אז שמור עליו מופעל לכלי כתיבה. + + +## אפליקציות מחוברות וביטול + +**Settings → Integrations → MCP** רשום את האפליקציות המחוברות שלך בארגון הנוכחי, עם ההרשאות שלהן והשימוש האחרון. **Revoke** מנתק אפליקציה מיד. הסרת השרת בלקוח שלך גם מביטלת את החיבור. + +אתה יכול להיות עם עד 5 אפליקציות מחוברות לכל ארגון. חיבור של אותה אפליקציה שוב מחליף את החיבור הקודם שלה. + +## פריסות בעצמי + +בחר **Self-hosted Failproof AI Cloud** בעת ההתחברות, והזן את הכתובת שבה אתה מתחבר. הפריסה שלך חייבת להיות נגישה על פני HTTPS ציבורי. + +קריאות כלים והתוצאות שלהם עוברות דרך שער Failproof AI המוזמן בדרכן בין כלי AI שלך לפריסה שלך. השער לא שומר אותן. + +## מה קורה לנתונים שלך + +התוצאות הולכות לכלי AI שחיברת, וספק הכלי של הכלי מטפל בהם תחת התנאים שלו. עבור כל קריאת כלי, Failproof AI עוקב אחר שם הכלי, התוצאה שלו, כמה זמן זה לקח, והארגון, לעולם לא הטיעונים או התוצאות. ראה את [מדיניות הפרטיות](https://befailproof.ai/privacy/). + +## פתרון בעיות + +| מה אתה רואה | מה לעשות | +| --- | --- | +| "Started in another browser" | סיים את ההתחברות בדפדפן שהלקוח פתח, עם קוקיז מורשה, והתחל שוב מהלקוח | +| שגיאה לאחר **Allow** | הקישור עובד פעם אחת ופג תוקף אחרי 10 דקות, אז התחל שוב מהלקוח | +| כלי שציפית לו חסר | אין לך את ההרשאה שלו בארגון זה. שאל מנהל. אתה לא צריך להתחבר מחדש ברגע שיש לך את זה | +| הלקוח ממשיך לבקש ממך להתחבר | החיבור בוטל, עזבת את הארגון, או הוא לא בשימוש 90 ימים. התחבר שוב | +| "You have 5 connected apps" | בטל אחת תחת **Settings → Integrations → MCP**, ואחריה התחבר שוב | + +עדיין תקוע? שלח דוא"ל [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/he/reference/otel.mdx b/docs/he/reference/otel.mdx new file mode 100644 index 000000000..3b2f1cb02 --- /dev/null +++ b/docs/he/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "הצטרף ל-OTEL עבור סוכני קידוד, בדוק את המסירה והשב את ההגדרות הקודמות שלך." +icon: "radio" +--- + +`failproofai otel` מגדיר דיווח OpenTelemetry אופציונלי ל-FailproofAI Cloud. תחילה חבר את המכונה שלך עם `failproofai config` והבקש מממנהל הארגון להפעיל את **Settings → OpenTelemetry**. + +ההגדרה האינטראקטיבית שואלת על OpenTelemetry לאחר שדה Cloud key ובוחר הסוכן. השלב האופציונלי ברירת המחדל שלו היא No. בחר Yes כדי לבחור סוכני OTEL; אותו קוד הפעלה פועל לאחר שכתבת את החיבור. Esc לפני שההגדרה משלימה לא תשנה דבר. הגדרה ללא השגחה, מפתח שסופק, מצב קוד פתוח, שמירת חיבור שמור לא משויכים אותך. + +## הפעל סוכן + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +הסוכנים הנתמכים הם `claude`, `codex` ו-`copilot` (VS Code). הגדרת Copilot דורשת קובץ הפעלה של VS Code או הרחבת Copilot מותקנת. ספריית הגדרות שנותרה בלבד אינה מספיקה; ההגדרה דילגה על Copilot כאשר אף אחד מהם לא נמצא. + +`--local` שולח ליחידת הממסר המקומית במקום ישירות לענן. Copilot משתמש בממסר באופן אוטומטי מכיוון שההגדרות שלו לא יכולות לאחסן את כותרת התימוכין. + +הממסר מקשיב רק על המכונה שלך. ה-daemon של FailproofAI המחובר שלך חוטף את השינוי תוך שניות; אתה לא צריך להפעיל אותו מחדש. אם יישום אחר בעלות על יציאת הממסר, דוח המצב משנה אותה כ-off והדאימון ממשיך להפעיל. + + +לכידת טקסט היא ברירת מחדל. הוסף `--no-content` כדי להשמיט הנחיות פרטי כלים. גרסאות סוכן יכולות להחשוף בקרות תוכן שונות; בדוק מה הסוכן שלך מיצא לפני שבו משתמש עם נתונים רגישים. + + +Codex מיצא יומני שיחה בלבד, לא עקבות זמן ריצה פנימי או מדדים. `log_user_prompt = false` מפורש בתצורת Codex שלך נשאר כבוי; הפעלה מודפסת הערה כאשר היא שומרת על בחירה זו. + +### בחר נתיב דיווח אחד + +אם דיווח תמלול הוא פעיל עבור סוכן, ההגדרה שואלת: + +> failproofai כבר שולח Claude Code הפגישות לענן. לשלוח אותם עם OTEL במקום? העלאת תמלול עבור Claude Code עוצרת. + +ברירת המחדל היא No. `--yes` מקבל את הגיבוש ללא הנחיה. סוכנים אחרים אכיפת מדיניות לא מושפעים. + +הגדרת Codex מחכה לדאימון לאשר את שינוי אספן לפני שכתיבת הגדרות מייצאה שלה. אם אישור פוקס, הגדרה מעניקה לך הערה להמתין לפני שתפעל את Codex. + +Config v2 שומר על רשימת ההתחקות הנזכרת ב-`agents.selected` (וההיסטוריה של גילוי ב-`agents.seen`). ההעדפה תמלול לכל סוכן נשארת ב-`collector.agents..sessions`, בעלות OTEL ב-`otel.agents` והגדרות הממסר ב-`collector.otlp.enabled` / `collector.otlp.port`. מפתחות נפרדים אלה שומרים על תצורות OTEL ישנות קריאות: ההגדרה יכולה לשנות את רשימת ההתחקות ללא אובדן העדפת התחבורה או המדינה הדרושה להשבת הגדרות הסוכן שלך. + +## בדוק הגדרה + +```bash +failproofai otel status +``` + +הסטטוס מציג כל סוכן, אם ההגדרות שלו מנוהלות על ידי FailproofAI, יעדו, קבלת הארגון, מצב הממסר ותוצאת ההעלאה האחרונה של הממסר. + +`unknown` עבור קבלת הארגון פירושו השרת לא סיפק אותו או לא היה ניתן להגיע אליו. זה לא טעות ולא מונע תצורה בגרסה ענן ישנה יותר. + +אם Cloud עדיין לא תומך ב-OTEL, הממסר שומר על יצוא דחוי במקום להשליך אותו. אם קבלת ארגון כבויה, `enable` לא כותבת דבר ויוצא עם שגיאה; בקש מממנהל להדליק אותו תחילה. + +## הדפס תצורה עבור יישום + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +הפלט הוא בלוק סביבה של מעטפת עבור OTLP/HTTP מיצואר. פלט ענן קובע את `OTEL_EXPORTER_OTLP_ENDPOINT` לבסיס OTLP של ענן, `https:///otel`, והמיצואר מוסיף `/v1/`; משתנה לכל-אות כמו `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` זקוק את הפלט `https:///otel/v1/logs`. הפלט המקומי מציע את הממסר, `http://127.0.0.1:`. פלט ענן כולל את מפתח API המחובר; התייחס אליו כסוד. פלט מקומי משמיט את המפתח. כדי להשתמש בפלט מקומי, תחילה הפעל סוכן מקומי כך שהממסר פועל. + +## השב את ההגדרות הקודמות + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable משחזר רק את ההגדרות ש-FailproofAI כתב, שומר על שינויים לא קשורים, והשיב את בחירת דיווח התמלול הקודמת של כל סוכן. כאשר סוכן מקומי מנוהל אחרון מכובה, הממסר מפסיק לקבל יצוא. + +עבור Codex, disable גם רשומות `collector.agents.codex.sessions_resume_after` (epoch אלפיות שניות). בתים של rollout קיימים מטופלים כמו מסירה כך שהפגישות שנתפסו עם OTEL לא יועלו שוב; appendices מאוחרות עדיין זורמות דרך דיווח תמלול. + +כל פקודה תומכת ב-`--help`. ראה [OpenTelemetry בענן](/he/agenteye/opentelemetry) לדוגמאות יישום וסוכן קידוד. \ No newline at end of file diff --git a/docs/he/reference/slack.mdx b/docs/he/reference/slack.mdx new file mode 100644 index 000000000..734204923 --- /dev/null +++ b/docs/he/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "אפליקציית Slack" +description: "שאל את עוזר Failproof מ-Slack, קבל תרשימים בשרשור, ואשר שינויים בלחיצת כפתור." +icon: "slack" +--- + +שאל את [עוזר Failproof](/he/sessions/assistant) מ-Slack. אזכר את האפליקציה בערוץ, שלח לה הודעה ישירה, או השתמש ב-`/failproof `. התשובות משתמשות **בהרשאות שלך שלך** של Failproof AI, תרשימים מגיעים בשרשור, וכל דבר שיוביל לשינוי מבקש ממך אישור תחילה. + +יש אפליקציה רשמית אחת. היא עובדת אותו הדבר בין אם ה-Failproof AI Cloud שלך מתוגמל או מאורח בעצמך. + + + תשובות נוצרות על ידי מודלים של AI ויכולות להיות שגויות. בדוק כל דבר חשוב בעומת נתוני המקור המקושרים. + + +## חבר workspace + +אתה זקוק להרשאת `settings:write` ב-Failproof AI וב-Slack, להיות מנהל workspace או בעלים, או האדם שמוסיף את האפליקציה. + + + + 1. עבור ל-**Settings → Integrations** ובחר **Add to Slack**. + 2. אשר את האפליקציה ב-Slack. + 3. חזור ל-Failproof AI וחזק על חיבור workspace לארגון שלך. + + + 1. הוסף את האפליקציה, ואז פתח את הלשונית **Home** שלה. + 2. בחר **Continue with FailproofAI Cloud**, או **Use my own URL** והכנס את הכתובת שבה אתה נחתם. + 3. בחר את כפתור ההמשך, התחבר, בחר את הארגון, וחזק. הקישור עובד פעם אחת ותוקף אחרי 10 דקות. + + + +workspace אחד מתחבר לארגון אחד, וארגון אחד ל-workspace אחד. + +אין לך חשבון? [צור אחד](https://app.befailproof.ai/login) תחילה, ואז התחבר. + +## מי אתה ב-Slack + +בפעם הראשונה שאתה שואל, האפליקציה מוצאת איזה חבר אתה: + +- **באופן אוטומטי, לפי דוא"ל**, כאשר אתה חבר מלא של ה-workspace המחובר, דוא"ל Slack שלך מאומת, וחבר בדיוק אחד של הארגון משתמש בדוא"ל זה. +- **אחרת**, אתה מקבל כפתור **Link your account** פרטי שפותח את Failproof AI ומקשר את משתמש Slack שלך לחשבון שלך. + +## שאל שאלה + +| איפה | איך | +| --- | --- | +| ערוץ | אזכר את האפליקציה. הגיב בשרשור שלה כדי להמשיך, ללא צורך באזכור | +| הודעה ישירה | שלח הודעה לאפליקציה | +| הודעה ישירה קבוצתית שהאפליקציה בה | אזכר אותה, ואז הגיב בשרשור שלה כדי להמשיך | +| ערוץ Slack Connect | אזכר את האפליקציה | +| כל שיחה שהאפליקציה בה | `/failproof ` מתחיל שרשור עם התשובה | +| `/failproof help` | ראה מה האפליקציה יכולה לעשות | +| `/failproof status` | ראה איזה ארגון מחובר ולמי אתה קשור | +| `/failproof link` | ראה איזה חשבון Failproof AI אתה קשור אליו | + +שרשור אחד זה שיחה אחת. עמיתים יכולים להזכיר את האפליקציה באותו שרשור, והיא עונה לכל אחד מהם בהרשאות שלהם שלהם. רק האדם שהתחיל את השרשור ממשיך אותו ללא אזכור. + +כאשר התשובה היא נתונים, האפליקציה מפרסמת תרשים או טבלה עם קישור כדי לפתוח אותה ב-Failproof AI. + +## אשר שינויים + +כל שינוי שהעוזר עושה מראה כפתורים **Approve** ו-**Cancel** תחילה, ו-Slack שואל עוד פעם לפני **Approve**. רק האדם ששאל יכול לענות עליהם, הכפתורים תוקף אחרי 5 דקות, והשינוי נעשה בהרשאות של האדם הזה. + +מ-Slack, העוזר יכול לשנות שאילתות שמורות וחשבונות, הערכות, התראות, ביקורות, בעיות, ומדיניויות, וקבע תיקוני קוד, כל אחד אם יש לך את ההרשאה. זה לא יכול לשנות מפתחות API, משתמשים, או הגדרות. + +## תצוגה מקדימה של קישורים + +קישורי בעיה, סשן, והערכה של Failproof AI שהודבקו ב-Slack לא מתפתחים לכרטיסים על Failproof AI Cloud המתוגמל. כרטיס מראה רק מה האדם שגירה אותו יכול לראות. קישורים לכתובת מאורחת בעצמך לא מתפתחים, אם כי כרטיסים בתשובות של העוזר עצמו עדיין מופיעים. + +## ערוצי Slack Connect + +אנשים מ-workspace אחר יכולים להשתמש באפליקציה אם הם חברים של הארגון, לאחר קישור החשבון שלהם. התשובות גלויות לכולם בשיחה, כולל אנשים שאינם חברים בארגון שלך, אז שאל איפה כולם יכולים לראות את התשובה. + +האפליקציה עונה רק פעם אחת לכל workspace אחר בערוץ יש מישהו קשור לארגון. עד אז, היא אומרת לאדם ששואל למה. + +## הרשאות שהאפליקציה מבקשת + +| הרשאת Slack | למה | +| --- | --- | +| `app_mentions:read` | דע מתי מישהו אזכר את האפליקציה | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | קבל הודעות ישירות והגבים בשרשורי האפליקציה. האפליקציה מתעלמת מהודעות אחרות, ולעולם לא קוראת הודעות עבר של שיחה | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | בדוק איזה סוג שיחה היא, כדי שיידע מי יכול לראות תשובה | +| `chat:write` | פרסם תשובות וכפתורי אישור | +| `commands` | ספק `/failproof` | +| `files:write` | פרסם תרשימים | +| `links:read`, `links:write` | הצג תצוגות מקדימות של קישורי Failproof AI שהודבקו | +| `users:read`, `users:read.email` | התאם אותך לחשבון Failproof AI שלך, והצג שמות | + +## התנתק + +עבור ל-**Settings → Integrations** ובחר **Disconnect**, השתמש **Disconnect** בלשונית **Home** של האפליקציה, או הסר את האפליקציה מ-Slack. + +כל אחד מאלה מוחק את חיבור ה-workspace, אסימון הבוט, חשבונות קשורים, ורשומות שרשור. שיחות Slack בעבר נשארות קריאות בחשבונות. הארגון יכול אז לחבר כל workspace מיד. + +## נתונים ופרטיות + +שאלות ותשובות נשמרות כשיחות בחשבונות הארגון שלך, תחת האדם שהתחיל את השרשור. נתונים של Slack לעולם לא משמשים לאימון מודלים של AI. ראה את [מדיניות הפרטיות](https://befailproof.ai/privacy/) למה האפליקציה מקבלת וכמה זמן היא נשמרת. + +## פתרון בעיות + +| מה אתה רואה | מה לעשות | +| --- | --- | +| "workspace זה לא מחובר ל-FailproofAI Cloud עדיין." | מנהל workspace פותח את הלשונית **Home** של האפליקציה ובוחר אחת | +| "קישור זה תוקף או כבר שימש." | בחר את ה-Cloud שלך שוב בלשונית **Home** כדי קבל קישור חדש | +| "org זה כבר מחובר ל-workspace של Slack." | התנתק אותו בהגדרות תחילה | +| "workspace של Slack זה מחובר לארגון אחר." | התנתק אותו מהארגון זה תחילה | +| "קשר את החשבון שלך כדי להשתמש בעוזר." | בחר את הכפתור וחזק ב-Failproof AI | +| האפליקציה לא עונה בהודעה ישירה קבוצתית | הוסף את האפליקציה ל-Slack שוב כדי תן הרשאות קבוצה. החיבור שלך נשמר | +| "לא אפרסם תשובות מהארגון שלך כאן" | מישהו ב-workspace זה שהוא חבר של הארגון אזכר את האפליקציה וקשור את החשבון שלו | + +עדיין תקוע? שלח דוא"ל ל-[support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/he/sessions/sentiment.mdx b/docs/he/sessions/sentiment.mdx new file mode 100644 index 000000000..48a9496d9 --- /dev/null +++ b/docs/he/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "ניתוח סנטימנט" +description: "מצא הודעות מתוסכלות, מבולבלות והיומיות עם ציוני הסנטימנט של Jev." +icon: "smile" +--- + +Jev נותן לכל הודעה שאדם שולח לאגנטים שלך ניקוד בין 0 ל-100 עבור ארבע רגשות — **כעוס**, **מתוסכל**, **שמח** ו**מבולבל** — וגם שלוש אותות שמראות איך האגנט מתנהל: + +- **Correcting**: האדם אומר שהאגנט טעה במשהו. +- **Resolved**: האדם מאשר שהאגנט פתר את הבעיה שלהם. +- **Doubtful**: האדם מטיל ספק בנכונות התשובה של האגנט, או בשאלה אם באמת הוא ביצע את העבודה. + +השתמש בניתוח סנטימנט כדי למצוא שיחות שבהן אנשים מאבדים סבלנות, אגנטים שאנשים מתקנים בהם שוב ושוב, והודעות שמגיעות טוב. זהו ניקוד Jev מובנה; אתה לא צריך לכתוב הערכה. לשאלת התשובה הקבועה שלך, [צור הערכת Jev](/he/evaluations/jev). + + + הסנטימנט כבוי עד שמנהל מפעיל אותו לארגון. Jev מבצע בקשת ניקוד אחת לכל הודעה ומקבל את ההודעה הזו עם תשובת האגנט לפניה. הניקוד משתמש בתקציב המודל של הארגון שלך. + + +## הפעל זאת + +1. עבור ל**Administration → Settings**. +2. תחת **Human input sentiment**, הפעל את זה **on** וחסוך. + +הודעות מהיום האחרון מקבלות ניקוד ראשון. לאחר מכן, הודעות חדשות מקבלות ניקוד תוך דקה או שתיים מהגעתן. + +## מצא שיחה לסקירה + +פתח **Observe → Sentiment**. סנן לפי זמן, סביבה, אגנט או מזהה הפעלה. הכותרת סוספרת הודעות והפעלות, מראה כמה הודעות מסומנות **flagged**, ומנמיק את האות העליון. הודעה מסומנת כאשר ציון כעוס, מתוסכל, מתקן, מבולבל או ספקני מגיע ל-35 מתוך 100. + +![לוח הסנטימנט המציג ספירות הודעות והפעלות, הודעות מסומנות וציוני Jev לאורך זמן.](/images/dashboard/sentiment-overview.png) + +השתמש ב**Score over time** להשוואת אותות. בחר את הציונים להצגה, ואז בחר נקודה כדי לראות את הודעות דלי הזמן הזה. הטבלה **By agent** מראה היכן אות מרוכזת. ב**Messages**, מיין לפי הציון השלילי החזק ביותר או בחר ציון יחיד. פתח הודעה בהפעלה שלה כדי לקרוא את השיחה המקיפה לפני כן שתחליט מה נכשל. + +![רשימת ההודעות של Sentiment מוסדרת לפי הציון השלילי החזק ביותר, עם קישור לכל הפעלה מקור.](/images/dashboard/sentiment-messages.png) + +## איזה הודעות מקבלות ניקוד + +רק הודעות שאדם כתב: + +- הודעות שהאגנטים המותאמים שלך מתעדים כקלט אנושי עם ה-SDK. +- הנושאים שהוקלדו ל-Claude Code, Codex, OpenCode, pi, Hermes ו-OpenClaw, כאשר תרשימי ההפעלה נשלחים (ברירת המחדל). משימות מתוזמנות, הוראות מוזרקות, העברות תת-אגנט וטקסט אחר שריאנט של האגנט עצמו כותב אינם מקבלים ניקוד. ולא גם הפעלות שאינן אינטראקטיביות כגון `claude -p`, `codex exec` ו-`hermes -z`: סקריפט כתב את הנושאים האלה, לא אדם. + +הניקוד שופט את המילים של האדם עצמו. הוראה קצרה וישירה כגון "fix it" לא נספרת כעוס, והשאלת שאלה לא נספרת כבלבול. בקשה חדשה אינה תיקון, והודאות בעצמן לא נספרות כממומשות. \ No newline at end of file diff --git a/docs/he/start/use-jev.mdx b/docs/he/start/use-jev.mdx new file mode 100644 index 000000000..33daac6e8 --- /dev/null +++ b/docs/he/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "שימוש ב-Jev" +description: "הגדר הערכות Jev עבור שיעורים שהסתיימו או מדיניויות Jev לבדיקת קריאות כלים בזמן אמת." +icon: "sparkles" +--- + +Jev עוזר בשתי נקודות במהלך ריצת agent: הערכת שיעור שהסתיים מול תשובות ידועות, או בדיקת קריאת כלי בהקשר של מה שביקשת מה-agent לעשות. + + + + השתמש בהערכת Jev כאשר שיעור שהסתיים יכול להיות מדורג מול שאלה עם כמה תשובות ידועות, כגון "האם הלקוח ביקש זיכוי? ענה כן או לא." זה עוזר לך למצוא דפוסים על פני שיעורים. + + ## יצירת הערכה + + בלוח המחוונים של Cloud, פתח את **Analyze → eval authoring → new eval**. הזן שאלה עם תשובה אחת קבועה, בחר **draft**, ובדוק שהוא בחר ניקוד מסווג. [בדוק אותה](/he/evaluations/test) על שיעורים אמיתיים, ואז פרוס אותה. + + ![טופס יצירת הערכות משותף שבו אתה מתאר שאלה, בוחן את ההטיוטה ופורס אותה. צילום המסך הזה מראה טיוטת קוד; השתמש בשאלה עם תשובה קבועה עבור Jev.](/images/dashboard/eval-authoring-draft.png) + + ## קריאת הניקודות + + לאחר השלמת שיעור חדש, פתח את **Observe → Evaluations** או השתמש ב-Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + ה-CLI קורא ניקודות; יצירת הערכת Jev כרגע משתמשת בלוח המחוונים. ראה [הערכות Jev](/he/evaluations/jev) לסוגי שאלות ודוגמאות. + + + השתמש בבדיקת מדיניות Jev כאשר מדיניות התאמה מחרוזות צריכה את ההקשר של בקשתך כדי להחליט אם קריאת כלי בטוחה. התחל במצב **observe** כך שתוכל לבדוק את התשובות של Jev בזמן שהמדיניויות המותקנות שלך עדיין קובעות כל קריאה. + + הבדיקות של Jev מגיעות מחבילה; Failproof AI לא משלחת אף אחת. עד שתתקין אותן, Jev לא שואל כלום, אפילו כאשר הוא מוגדר: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## הגדרת Cloud Jev + + בלוח המחוונים של Cloud, פתח את **Administration → Keys** וצור מפתח עם ההגדרה המוקדמת **machine**. השתמש בו עם `failproofai config` כפי שמוצג ב[quickstart](/he/start/quickstart). במכונה ללא תצורת Jev קיימת, זה מאפשר Cloud Jev במצב observe. בדוק את החיבור עם: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## שימוש בנקודת הקצה שלך + + בלוח המחוונים המקומי, פתח את **Settings → Jev**. בחר את ספק השירותים, הדבק את האסימון שלו, בחר **observe**, והפעל את Jev. + + ![לוח ההגדרות המקומי של Jev עם ספק, שדה אסימון, ומצב observe שנבחר.](/images/dashboard/jev-settings.png) + + או קצה ובדוק את נקודת הקצה שלך מטרמינל: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + בקש מ-agent מחובר להשתמש בכלי קריאת הקבצים שלו ב-`README.md`. אשר שקריאה זו מופיעה בשיעור, ואז בדוק אותה תחת **Policies → Activity** בלוח המחוונים המקומי. ברגע שתוצאות ה-observe נראות נכונות, [מדיניויות Jev](/he/policies/jev) מסבירות מתי להטיל. לפרטי ספק וקונפיגורציה, ראה את [הפניה לאינטגרציה](/he/reference/jev). + + \ No newline at end of file diff --git a/docs/hi/admin/product-analytics.mdx b/docs/hi/admin/product-analytics.mdx new file mode 100644 index 000000000..c4cd5c4fe --- /dev/null +++ b/docs/hi/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "उत्पाद विश्लेषण" +description: "Failproof AI Cloud जो उपयोग टेलीमेट्री भेजता है, क्या कभी एकत्र नहीं किया जाता है, और इसे कैसे बंद किया जाए।" +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud **सॉफ़्टवेयर के बारे में** उपयोग टेलीमेट्री अपने रखरखाव कर्ताओं को भेजता है। इसमें कभी आपके agents का डेटा शामिल नहीं होता है। Self-hosted install पर यह डिफ़ॉल्ट रूप से चालू होता है, और आप इसे बंद कर सकते हैं। + +## क्या एकत्र किया जाता है + +प्रत्येक event में पाँच dimensions होते हैं और कुछ भी ऐसा नहीं जो किसी व्यक्ति की पहचान करे: + +| Dimension | उदाहरण | यह क्या है | +| --- | --- | --- | +| `product` | `agenteye` | कौन सा उत्पाद इसे भेजा | +| `component` | `dashboard`, `server`, `cli` | उत्पाद का कौन सा हिस्सा इसे भेजा | +| `app_version` | `0.0.1-beta.81` | आप जो build चला रहे हैं | +| `deployment_kind` | `self_hosted` | क्या यह customer install है, हमारा demo है, हमारा QA है, या dev machine है | +| `org_id` | एक UUID | कौन सी organization में action हुआ, एक opaque identifier के रूप में | + +उन पर, events **क्या use किया गया था, कभी क्या इसमें था नहीं**: कौन सा पृष्ठ देखा गया (एक route pattern जैसे `/:org/sessions/:id`, कभी असली URL नहीं), कितने filters किस प्रकार के लागू किए गए, क्या एक action सफल रहा, और इसमें कितना समय लगा। + +Slack app workspace connections और disconnections, account links, पूछे गए सवाल, posted charts, approval decisions, और एक fixed category से failures को record करता है। इसमें कभी Slack workspace, user, या channel IDs, email, सवाल, जवाब, SQL, या tokens शामिल नहीं होते। + +### आपकी organization का नाम + +Opaque `org_id` के साथ-साथ, हम आपकी organization का नाम, URL slug, और dashboard address एक बार record करते हैं, हर event पर नहीं बल्कि एक organization record पर। यह हमें बताता है कि जब हम adoption को देखते हैं या आपके द्वारा रिपोर्ट की गई समस्या की जांच करते हैं तो कौन सा pattern किस account का है। यह एक ही पहचान करने योग्य जानकारी है जो उत्पाद आपके बारे में भेजता है। + +### आपके उपयोग की कुल संख्या + +Server प्रत्येक organization के metered usage totals को report करता है, वही संख्याएं जो आप Usage page पर देखते हैं। ये केवल counts हैं: events, sessions, agents, environments, evaluation runs, scores, audit runs, saved queries, dashboards, alerts, issues, API keys, और members, साथ ही metering window की तारीखें। इनमें कोई identifiers, names, या query text नहीं हैं, और वे तब भी आते हैं जब कोई signed in न हो। + +## क्या कभी एकत्र नहीं किया जाता है + +- **कोई prompts, model responses, या event content नहीं**, न text के रूप में, न prefix, न ही hash +- **कोई session, agent, या trace identifiers नहीं** +- **कोई evaluator score names नहीं** +- **कोई error messages, exception text, या response bodies नहीं**, केवल एक status code और एक fixed list से एक category +- **कोई tool arguments, SQL, या query text नहीं** +- **कोई connected-app details नहीं।** एक MCP client को connect या revoke करना अधिकतम एक permission count भेजता है, कभी app का नाम या कोई token नहीं +- **कोई email addresses नहीं** +- **कोई referrer URLs या query strings नहीं** +- **कोई screen recording, DOM capture, या click और cursor tracking नहीं** + +## Self-hosted install पर इसे बंद करें + +Dashboard और server दोनों पर `DO_NOT_TRACK=1` set करें। वे अलग से decide करते हैं, इसलिए केवल एक पर सेट करने से दूसरा reporting छोड़ देता है। Change को apply करने के लिए server को restart करें। + +आपकी release README अन्य opt-out settings और telemetry बंद होने की पुष्टि कैसे करें इसका वर्णन करती है। + +## Opt out करने पर एक ping + +यदि आप `DO_NOT_TRACK` के बजाय एक product setting के साथ opt out करते हैं, तो dashboard **एक anonymous ping** भेज सकता है जो record करता है, प्रति process start पर 1 में 1000 की probability के साथ। यह हमें बताता है कि कितने operators telemetry को बंद कर देते हैं। इसमें कोई identifiers नहीं हैं: कोई organization, user, hostname, URL, या IP नहीं, केवल product, component, version, deployment kind, और reason। Opted-out server कुछ नहीं भेजता है। + +यह कभी नहीं भेजा जाता है जब आप `DO_NOT_TRACK` use करते हैं, यही कारण है कि वह setting use करने के लिए है यदि आपकी policy किसी भी outbound telemetry को forbid करती है। + +## यह कहाँ जाता है + +PostHog (`us.i.posthog.com`) को TLS पर port 443 पर। यह एक hostname है, इसलिए आप इसे एक single egress rule से भी block कर सकते हैं। + +हम व्यक्तिगत जानकारी को अधिक व्यापक रूप से कैसे handle करते हैं, के लिए [privacy policy](https://befailproof.ai/privacy/) देखें। \ No newline at end of file diff --git a/docs/hi/agenteye/opentelemetry.mdx b/docs/hi/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..b07688966 --- /dev/null +++ b/docs/hi/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "FailproofAI Cloud को OTLP के साथ coding-agent और application telemetry भेजें।" +icon: "radio" +--- + +OpenTelemetry आपको standard OTLP/HTTP protocol का उपयोग करके agent traces, logs, और metrics को FailproofAI Cloud में भेजने देता है। यह optional है। आपके existing FailproofAI integrations इसे enable किए बिना काम करते रहते हैं। + +## अपने organisation के लिए ingest चालू करें + +एक organisation admin **Settings → OpenTelemetry** खोलता है और ingest को चालू करता है। `events:add` permission के साथ एक Cloud API key का उपयोग करें, वही permission जो agent reporting के लिए उपयोग किया जाता है। + +अगर ingest बंद है, तो Cloud OTLP exports को अस्वीकार करता है, इसलिए `failproofai otel enable` कुछ नहीं बदलता और आपके agents सामान्य तरीके से sessions भेजते रहते हैं। Organisation switch को जांचने के लिए `failproofai otel status` चलाएं, और किसी admin से इसे चालू करने के लिए कहें। + +## एक coding agent को कनेक्ट करें + +`failproofai config` के साथ अपनी machine को कनेक्ट करें, फिर एक agent चुनें: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +Setup command Claude Code, Codex, और Copilot को support करता है और जैसा उपयुक्त हो Cloud या एक local authenticated relay को चुनता है। Copilot स्वचालित रूप से local relay का उपयोग करता है। Relay का उपयोग करने से पहले अपने configured FailproofAI daemon को start करें। + +अगर FailproofAI पहले से ही एक agent की session transcripts भेजता है, तो setup पूछता है कि क्या उस agent को OTEL पर switch करना है। डिफ़ॉल्ट No है। स्वीकार करने से उस agent के लिए transcript uploads बंद हो जाते हैं; यह policy enforcement या अन्य agents से reporting को नहीं बदलता। + +## एक application को कनेक्ट करें + +इन environment variables के साथ अपने application के OpenTelemetry instrumentation का उपयोग करें: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +Endpoint Cloud की OTLP base है, `https://app.befailproof.ai/otel`; आपका exporter स्वयं `/v1/traces`, `/v1/logs`, या `/v1/metrics` को जोड़ता है। Per-signal variables जैसे `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` को वैसे ही उपयोग किया जाता है, इसलिए उन्हें पूर्ण path की आवश्यकता होती है, उदाहरण के लिए `https://app.befailproof.ai/otel/v1/logs`। + +`` को अपने API key से replace करें। secret को shell history, screen recordings, और committed configuration से दूर रखें। एक configured machine के लिए, `failproofai otel env --service my-agent` अपने existing key के साथ block को print करता है। इसके output में एक credential होता है। + +Cloud protobuf या JSON के रूप में, gzip-compressed requests सहित, traces, logs, और metrics के लिए OTLP/HTTP exports को स्वीकार करता है। यह OTLP/gRPC को स्वीकार नहीं करता। + +Metrics को exporter compatibility के लिए acknowledge किया जाता है लेकिन store या display नहीं किए जाते। Supported agent traces और coding-agent logs sessions बन जाते हैं; जो fields agent export नहीं करता वे अनुपस्थित रहते हैं। + +## Prompt text को capture करें + + +Text capture में prompts, tool arguments, और अन्य sensitive content शामिल हो सकता है। `failproofai otel enable` इसे चालू करता है। Prompt और tool-detail capture को बंद रखने के लिए `--no-content` जोड़ें। + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +एक agent के लिए जिसे आप manually configure करते हैं, इसके अपने content-capture controls का उपयोग करें: + + + + इन variables को अपने agent के environment में ऊपर दिए गए application block के साथ जोड़ें: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Prompts और tool details को capture करने से बचने के लिए दोनों content variables को `0` पर सेट करें। + + + Codex के user configuration में, इसके OTEL settings का उपयोग करें: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Codex conversation content logs में है; internal runtime traces और metrics को disabled रखें। Codex आपके द्वारा प्रदान किए गए complete endpoint का उपयोग करता है। Prompts को छोड़ने के लिए `log_user_prompt` को `false` पर सेट करें; setup command एक explicit `false` को preserve करता है। + + + Local relay के साथ Gemini के telemetry settings का उपयोग करें: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI को `failproofai otel enable` द्वारा support नहीं किया जाता है। इसे manually अपने authenticated collector के साथ configure करें। Prompt capture के लिए `logPrompts` को `false` पर सेट करें। + + + इन VS Code user settings का उपयोग करें: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Authenticated relay को enable करने के लिए `failproofai otel enable copilot` चलाएं। Content को छोड़ने के लिए `captureContent` को `false` पर सेट करें। + + + +## Setup को check या undo करें + +Relay temporary network और server failures के माध्यम से telemetry को retain करता है और recovery के बाद retry करता है। एक permanent `400` rejection, जिसमें एक event शामिल है जो store करने के लिए बहुत बड़ा है, payload को correct करने की आवश्यकता है। Relay rejected batch को repeatedly भेजने के बजाय inspection के लिए रखता है। + +`401` या `403` के बाद, credential को उसी organisation के लिए `events:add` देने वाली key से replace करें। Reconnecting स्वचालित रूप से retained OTLP exports को फिर से नहीं भेजता जो credentials के लिए refused हुए हैं; अपने operator से उन batches को recover करने के लिए कहें। उन्हें उनके original organisation में रखें। + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status FailproofAI द्वारा managed settings को उन telemetry से अलग करता है जिन्हें आपने अन्य places पर configure किया है। Disable पिछली managed settings को restore करता है और agent की पिछली transcript-upload choice को restore करता है। + + + Command options, local relay setup, और troubleshooting। + \ No newline at end of file diff --git a/docs/hi/evaluations/jev.mdx b/docs/hi/evaluations/jev.mdx new file mode 100644 index 000000000..42429f42a --- /dev/null +++ b/docs/hi/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev मूल्यांकन" +description: "एक समाप्त सत्र को ज्ञात उत्तरों के साथ एक प्रश्न के विरुद्ध स्कोर करने के लिए Jev का उपयोग करें।" +icon: "list-checks" +--- + +एक Jev मूल्यांकन एक **समाप्त सत्र** को पढ़ता है और 0 से 1 तक का स्कोर देता है। इसका उपयोग तब करें जब उत्तर पहले से ज्ञात हो, जैसे "क्या ग्राहक ने तत्कालता व्यक्त की?" या "ग्राहक कितना निराश था?" यह आपको चलन के पार पैटर्न खोजने में मदद करता है; यह एक उपकरण कॉल को रोकता नहीं है। **से पहले** किए गए निर्णयों के लिए एक उपकरण चलता है, [Jev नीतियां](/hi/policies/jev) का उपयोग करें। + +## डैशबोर्ड में एक बनाएं + +1. **Analyze → eval authoring** खोलें और **new eval** चुनें। +2. एक प्रश्न और उसके संभावित उत्तरों का वर्णन करें। उदाहरण के लिए: "क्या एजेंट ने रिफंड नीति की जांच करने से पहले रिफंड का वादा किया? हां या नहीं का उत्तर दें।" **draft** चुनें और समीक्षा करें कि परिणाम एक वर्गीकरण स्कोर है। +3. हाल के सत्रों पर [इसका परीक्षण करें](/hi/evaluations/test), फिर [इसे तैनात करें](/hi/evaluations/deploy)। नए समाप्त सत्र स्कोर किए जाते हैं; यदि आपको इतिहास की भी आवश्यकता है तो [backfill](/hi/evaluations/deploy#score-sessions-you-already-have) करें। + +![साझा किया गया eval authoring फॉर्म, जहां आप एक निश्चित-उत्तर प्रश्न का वर्णन करते हैं, ड्राफ्ट की समीक्षा करते हैं, और परीक्षण के बाद तैनात करते हैं। दिखाया गया उदाहरण एक कोड मूल्यांकन है; एक Jev प्रश्न समान authoring प्रवाह का उपयोग करता है।](/images/dashboard/eval-authoring-draft.png) + +सहायक कोड, Jev वर्गीकरण, और एक [judge](/hi/evaluations/judge) के बीच चयन कर सकता है। तैनात करने से पहले इसकी पसंद की जांच करें। Jev गद्य तर्क के बिना एक स्कोर देता है; जब आपको व्याख्या की आवश्यकता हो तो एक judge चुनें। प्रश्न प्रकारों और स्कोर सीमाओं के लिए [Jev मूल्यांकन संदर्भ](/hi/reference/jev-evaluations) देखें। + +## स्कोर पढ़ें + +**Observe → Evaluations** खोलें एजेंट और समय के आधार पर परिणाम चार्ट करने के लिए। एक टर्मिनल से, Cloud CLI समान परिणाम पढ़ सकता है: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI परिणाम पढ़ता है; authoring और deployment डैशबोर्ड में होते हैं। फ़िल्टर के लिए [Cloud CLI संदर्भ](/hi/reference/cloud-cli#evaluations) देखें। \ No newline at end of file diff --git a/docs/hi/evaluations/judge.mdx b/docs/hi/evaluations/judge.mdx new file mode 100644 index 000000000..f02411fd4 --- /dev/null +++ b/docs/hi/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLM न्यायाधीश" +description: "सत्रों को उन चीजों पर स्कोर करें जिन्हें कोड माप नहीं सकता — सटीकता, टोन, क्या एजेंट ने नीति का पालन किया — यह वर्णन करके कि अच्छा क्या दिखता है और एक मॉडल को बातचीत पढ़ने देकर।" +icon: "scale" +--- + +एक होस्ट किया गया Python मूल्यांकन गिनती और तुलना कर सकता है: कितने टूल कॉल, कितनी त्रुटियां, एक सत्र में कितना समय लगा। यह आपको नहीं बता सकता कि क्या उत्तर *सही* था, क्या उत्तर असभ्य था, या क्या एजेंट ने कार्य करने से पहले किसी नीति की जांच की थी। + +एक **LLM न्यायाधीश** कर सकता है। आप सादी भाषा में वर्णन करते हैं कि अच्छा क्या दिखता है, और एक मॉडल सत्र को पढ़ता है और 0 से 1 तक का स्कोर अपने तर्क के साथ वापस करता है। + + +एक न्यायाधीश हर सत्र के लिए एक मॉडल कॉल की लागत करता है जिस पर वह चलता है, और एक कोड मूल्यांकन की कोई लागत नहीं है। एक न्यायाधीश का उपयोग केवल उन प्रश्नों के लिए करें जिन्हें बातचीत को *समझने* की आवश्यकता है — और इसे एक शर्त दें, ताकि यह उन सत्रों पर चले जिनके बारे में प्रश्न वास्तव में है। + + +## मुझे कौन सा चाहिए? + +| प्रश्न | उपयोग करें | +| --- | --- | +| क्या इसने एक ही टूल को दो बार कॉल किया? | कोड | +| कितनी त्रुटियां थीं? | कोड | +| क्या सत्र 30 सेकंड से कम था? | कोड | +| क्या ग्राहक ने तात्कालिकता व्यक्त की? | [classifier](/hi/evaluations/jev) | +| ग्राहक कितना निराश था? | [classifier](/hi/evaluations/jev) | +| क्या उत्तर वास्तव में सही था? | **न्यायाधीश** | +| क्या उत्तर असभ्य या खारिज करने वाला था? | **न्यायाधीश** | +| क्या इसने रिफंड का वादा करने से पहले रिफंड नीति की जांच की? | **न्यायाधीश** | + +अंगूठे का नियम: **गिनती योग्य → कोड, उत्तर जिन्हें आप पहले से सूचीबद्ध कर सकते हैं → [classifier](/hi/evaluations/jev), व्याख्या की जरूरत है → न्यायाधीश।** एक न्यायाधीश वह है जो उस चीज के बारे में गद्य लिखता है जो उसे दिखी; इसे तब चुनें जब संख्या से कोई "क्यों?" पूछेगा। + +आपको अग्रिम रूप से निर्णय लेने की आवश्यकता नहीं है। वर्णन करें कि आप क्या मापना चाहते हैं और सहायक चुनता है, फिर बताता है कि इसने कौन सा चुना और क्यों। आप इसे स्विच कर सकते हैं। + +## एक लिखें + +1. **Analyze → eval authoring** पर जाएं और **new eval** चुनें। +2. वर्णन करें कि आप क्या परखना चाहते हैं, और **draft** चुनें। +3. **criteria**, **threshold**, और **condition** की समीक्षा करें, फिर तैनात करें। + +### Criteria + +एक या दो वाक्य, एक सवाल के बजाय एक आवश्यकता के रूप में लिखे गए: + +> सहायक को बिना पहले रिफंड नीति की जांच किए रिफंड का वादा या अनुमोदन नहीं करना चाहिए। + +विशेष रूप से बताएं कि क्या इसे *विफल* कर देगा। "क्या प्रतिक्रिया अच्छी थी?" आपको एक संख्या देता है जिसका कोई मतलब नहीं है; ऊपर का वाक्य आपको एक देता है जिस पर आप कार्य कर सकते हैं। + +### Threshold + +वह स्कोर जिस पर या उससे ऊपर सत्र पास हो जाता है। `0.7` एक समझदारी भरा शुरुआती बिंदु है। पूर्ण 0-से-1 स्कोर हमेशा संग्रहीत रहता है, इसलिए थ्रेसहोल्ड केवल पास/फेल तय करता है — आप वितरण देख सकते हैं और समायोजित कर सकते हैं। + +### Condition + +किसी अन्य मूल्यांकन के समान Python शर्त, और यह यहां कहीं अधिक महत्वपूर्ण है। बिना किसी के, न्यायाधीश आपके संगठन के **हर** सत्र पर चलता है, हर एक पर एक मॉडल कॉल की लागत: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +डैशबोर्ड आपको चेतावनी देता है यदि आप बिना शर्त के एक न्यायाधीश तैनात करते हैं। यह कभी-कभी सही है — एक कम-वॉल्यूम एजेंट जिसे आप पूरी तरह से परखना चाहते हैं — लेकिन यह एक निर्णय होना चाहिए, दुर्घटना नहीं। + +## न्यायाधीश क्या देखता है + +बातचीत, बारी-बारी से, सबसे नई-पहले यदि सत्र लंबा है: + +- उपयोगकर्ता ने क्या कहा +- सहायक ने क्या उत्तर दिया +- **एजेंट ने हर टूल को कॉल किया, और वह कॉल क्या वापस करता है, क्रम में** + +यह अंतिम भाग है जो "क्या इसने X को Y से *पहले* किया" को एक न्यायसंगत प्रश्न बनाता है। एक विफल टूल कॉल को विफलता के रूप में दिखाया जाता है, इसलिए "क्या इसने किसी त्रुटि से सुंदरता से ठीक किया" भी काम करता है। + +बहुत लंबे सत्र मॉडल के संदर्भ में फिट करने के लिए काटे जाते हैं। जब ऐसा होता है तर्क स्पष्ट रूप से कहता है — आप कभी भी एक सत्र के हिस्से पर किया गया निर्णय नहीं देखेंगे जो पूरे पर किए गए के रूप में प्रस्तुत हो। + +## परिणाम पढ़ना + +एक न्यायाधीश किसी अन्य स्कोर किए गए मूल्यांकन की तरह एक **स्कोर** उत्पन्न करता है, इसलिए यह उसी तरह चार्ट, फ़िल्टर और अलर्ट ट्रिगर करता है। संख्या के साथ यह न्यायाधीश का **तर्क** संग्रहीत करता है — पैराग्राफ जो समझाता है कि उसने क्या देखा। जब कोई स्कोर आपको आश्चर्यचकित करता है तो पहले उसे पढ़ें; यह आमतौर पर या तो एक वास्तव में दिलचस्प सत्र है या एक संकेत है कि मानदंड को तेज करने की आवश्यकता है। + +स्कोर स्पष्ट कटौती मामलों के लिए स्थिर होते हैं लेकिन बिट-के-लिए नियतात्मक नहीं होते हैं। एक एकल सीमांत स्कोर को जाने और सत्र को पढ़ने के लिए एक संकेत के रूप में मानें, न कि एक फैसले के रूप में। + +## सीमाएं + +- **परीक्षण अभी उपलब्ध नहीं है।** एक सूखे रन के पीछे कोई सत्र असाइनमेंट नहीं है, और वह असाइनमेंट ही वह है जो आपके मॉडल बजट को खर्च करने को अधिकृत करता है — तो एक परीक्षण कॉल के लिए चार्ज करने के लिए कुछ नहीं है। एक संकीर्ण शर्त के विरुद्ध तैनात करें और पहले कुछ परिणाम पढ़ें। +- **Backfill उपलब्ध नहीं है।** महीनों के इतिहास पर एक कोड मूल्यांकन को बैकफिल करना मुफ्त है; इसे एक न्यायाधीश के साथ करना मिनटों में आपके संपूर्ण बजट को खर्च कर देगा। +- **मानदंड संपादित करना एक नया संस्करण प्रकाशित करता है।** पुराने और नए स्कोर तुलनीय नहीं हैं, इसलिए उन्हें एक प्रवृत्ति पंक्ति में मिश्रित करने के बजाय अलग रखा जाता है। +- **एक न्यायाधीश हमेशा एक स्कोर उत्पन्न करता है**, कभी भी एक मीट्रिक या एक अभिकथन नहीं। + +## जब आपका बजट समाप्त हो जाता है + +न्यायाधीश आपके संगठन के मॉडल बजट को खर्च करते हैं। जब यह समाप्त हो जाता है, न्यायाधीश मूल्यांकन एक स्पष्ट कारण के साथ बंद हो जाते हैं बजाय चुप्पी से विफल होने के, और **कोड मूल्यांकन सामान्य रूप से चलते रहते हैं**। बजट बढ़ाएं और वे अगले सत्र पर फिर से शुरू होते हैं। \ No newline at end of file diff --git a/docs/hi/policies/authority.mdx b/docs/hi/policies/authority.mdx new file mode 100644 index 000000000..e5ed2df58 --- /dev/null +++ b/docs/hi/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "नीति प्राधिकार" +description: "Jev सिमेंटिक मूल्यांकनकर्ता कौन से नीति निर्णयों को साफ कर सकता है, और कौन से अंतिम हैं।" +icon: "scale" +--- + +जब आप FailproofAI Cloud के माध्यम से या अपनी स्वयं की कुंजी के साथ [Jev नीति समीक्षा](/hi/policies/jev) कॉन्फ़िगर करते हैं, तो प्रत्येक गेटेड टूल कॉल का न्याय उन नीतियों द्वारा किया जाता है जो आप चलाते हैं और Jev द्वारा, जो पूछता है कि कॉल वास्तव में क्या करता है और क्या जिस व्यक्ति ने कार्य टाइप किया वह इसके लिए कहा। प्रत्येक नीति का **प्राधिकार** यह निर्धारित करता है कि जब दोनों असहमत हों तो क्या होता है। + +Jev कॉन्फ़िगर किए बिना, प्राधिकार का कोई प्रभाव नहीं है। प्रत्येक नीति बिल्कुल उसी तरह लागू होती है जैसे हमेशा होती है। + +## कठोर और समीक्षा योग्य + +- **कठोर** डिफ़ॉल्ट है। एक कठोर नीति की अस्वीकृति या निर्देश अंतिम होता है: Jev इसे साफ नहीं कर सकता, और एक कठोर अस्वीकृति Jev की प्रतीक्षा किए बिना कॉल को रोक देती है। +- **समीक्षा योग्य** का अर्थ है कि Jev नीति के निर्णय को साफ कर सकता है, लेकिन केवल `reviewedBy` में नीति द्वारा नामित सिमेंटिक जांच के माध्यम से। निर्णय केवल तभी साफ होता है जब **हर** नामित जांच से इस कॉल के बारे में पूछा गया हो और प्रत्येक ने या तो कुछ नहीं पाया हो या उपयोगकर्ता द्वारा इसके लिए कहे जाने को रिकॉर्ड किया हो। एक जांच जो **फायर** हुई — चिंता पाई गई — उपयोगकर्ता द्वारा पूछे बिना, अवरोध को रखती है, भले ही इसका अपना निर्णय केवल एक चेतावनी हो। एक जांच जिसके बारे में Jev से नहीं पूछा गया क्योंकि यह उस उपकरण पर लागू नहीं होती, भले ही अन्य सहमत हों, कुछ भी साफ नहीं करता है। एक नरमी सहमति के रूप में गिनी जाती है: जब कॉल उपयोगकर्ता द्वारा दिए गए कार्य का एक कदम है और आगे नहीं बढ़ता है, Jev अस्वीकृति को चेतावनी में बदल देता है, और वह चेतावनी नीति के अवरोध को साफ करती है और यही है जो एजेंट को बताया जाता है। + +एक नीति केवल समीक्षा योग्य है जब ये सभी शर्तें पूरी हों: + +1. यह `authority: "reviewable"` घोषित करता है। +2. `reviewedBy` एक गैर-खाली सूची है, और हर प्रविष्टि एक Jev जांच है जो एक स्थापित पैक घोषित करता है। Failproof AI कोई Jev जांच नहीं भेजता: [नीचे दिए गए सोलह](#semantic-policy-names) `failproofai policies add FailproofAI/jev-policies` से आते हैं। कोई पैक जांच घोषित किए बिना, प्रत्येक नीति कठोर है। +3. यह `alwaysOn` नहीं है। वह गार्ड जो एजेंट को Failproof AI को अक्षम करने से रोकता है, हमेशा कठोर होता है। + +कुछ भी और कठोर है: एक लापता फील्ड, एक गलत वर्तनी वाला मान, एक खाली या गलत स्वरूपित `reviewedBy`, या एक नाम जो इस मशीन पूछ सकने वाली जांच नहीं है। एक अज्ञात नाम पूरी घोषणा को कठोर बना देता है इसे छोड़ दिए जाने के बजाय, क्योंकि `reviewedBy` का अर्थ है "इन सभी से पूछा जाना चाहिए, और उनमें से कोई भी अस्वीकार नहीं कर सकता", और एक नाम को छोड़ना Jev को कम जांच पर नीति को साफ करने देगा जितना आपने मांगा। + +एक बार Jev कॉन्फ़िगर हो जाने के बाद, Failproof AI एक चेतावनी लॉग करता है जब यह एक `reviewable` घोषणा को प्रति प्रक्रिया अस्वीकार करता है। Jev के बिना यह कुछ नहीं कहता, क्योंकि प्राधिकार तब कुछ भी तय नहीं करता। `failproofai publish` उस पैक को बनाने से इनकार करता है जो ऐसी घोषणा रखता है, इसलिए पैक लेखक इसे किसी द्वारा स्थापित करने से पहले पता चल जाता है। यह `reviewedBy` को उन जांचों के विरुद्ध आंकता है जो पैक घोषित करता है जब वह कोई भी घोषित करता है, और अन्यथा सोलह `FailproofAI/jev-policies` नामों के विरुद्ध। + +## जहां प्राधिकार घोषित किया जाता है + +प्रत्येक तरीके से एक नीति मशीन तक पहुंचती है, एक स्थान होता है जो इसका प्राधिकार तय करता है: + +| स्रोत | घोषित किया गया | डिफ़ॉल्ट | +| --- | --- | --- | +| अंतर्निहित नीतियां | नीचे दी गई तालिका | कठोर जब तक समीक्षा योग्य के रूप में सूचीबद्ध न हो | +| आपकी स्वयं की नीति फाइलें | `customPolicies.add` पर `authority` और `reviewedBy` | कठोर | +| नीति पैक | पैक मैनिफेस्ट में प्रत्येक नीति की प्रविष्टि (`failproofai-pack.json`) | कठोर | +| क्लाउड-प्रबंधित नीतियां | सक्रिय तैनाती में नीति का आवंटन | कठोर। तैनातियां अभी इसे सेट नहीं करती हैं, इसलिए आज हर क्लाउड-प्रबंधित नीति कठोर है। | + +एक पैक या क्लाउड-प्रबंधित नीति के लिए, नीति कोड के अंदर सेट फील्ड अनदेखी किए जाते हैं; मैनिफेस्ट या आवंटन का निर्णय होता है। एक पैक केवल अपनी स्वयं की नीतियों का वर्णन कर सकता है: इसके नीति नाम `/` शामिल नहीं कर सकते और पैक के अपने उपसर्ग के तहत पंजीकृत होते हैं, इसलिए कोई भी मैनिफेस्ट एक अंतर्निहित नीति या किसी अन्य पैक की नीति को समीक्षा योग्य के रूप में चिह्नित नहीं कर सकता। एक नीति जो पैक का कोड बिना मैनिफेस्ट में घोषित किए पंजीकृत करता है, कठोर है। + +दो पैक, या दो क्लाउड-प्रबंधित नीतियां, जिनका कोड बाइट-समान है, एक कलाकृति साझा करते हैं और एक नीति के रूप में लोड होते हैं। वह नीति केवल तभी समीक्षा योग्य है जब उनमें से हर एक इसे समीक्षा योग्य घोषित करता है, और Jev को तब हर जांच को साफ करना चाहिए जो उनमें से कोई भी नाम देता है। यदि उनमें से कोई इसे कठोर घोषित करता है, या इसे बिल्कुल भी घोषित नहीं करता है, तो यह कठोर रहता है। पैक या नीतियों की सूची में दिया गया क्रम कभी मायने नहीं रखता। + +अधिकांश मशीनें `FailproofAI/policies` पैक से अंतर्निहित नीतियां प्राप्त करती हैं, और उस पैक के मैनिफेस्ट से उनका प्राधिकार पढ़ती हैं। नीचे दी गई समीक्षा योग्य प्रविष्टियां तब प्रभावी होती हैं जब उन्हें ले जाने वाले पैक की रिलीज़ स्थापित की जाती है; एक पुरानी रिलीज़ कोई नहीं ले जाती, इसलिए इसमें हर नीति कठोर रहती है। + +## अपनी स्वयं की नीति में प्राधिकार घोषित करें + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` दोनों फील्डों को पैक मैनिफेस्ट में कॉपी करता है, इसलिए एक पैक के रूप में प्रकाशित की गई नीति वह प्राधिकार रखती है जो इसके लेखक ने दिया था। यदि कोई घोषणा सम्मानित नहीं होगी तो पैक बनाने से इनकार करता है: `"hard"` या `"reviewable"` के अलावा कोई मान, एक `reviewedBy` जो नामों की सूची नहीं है, या एक नाम जो एक जांच नहीं है — पैक के अपने [Jev जांच](/hi/policies/publish-a-pack#jev-checks-in-a-pack) में से एक जब यह कोई भी घोषित करता है, एक अंतर्निहित जांच अन्यथा। + +## अंतर्निहित नीतियां + +केवल समीक्षा योग्य जहां एक सिमेंटिक नीति वास्तव में एक ही चिंता को कवर करती है। हर दूसरी अंतर्निहित नीति कठोर है। + +चिंता को कवर करना आवश्यक है लेकिन पर्याप्त नहीं है, और गलत तरीके से पाने के दोनों तरीके चुप हैं: + +- **एक जांच जो कभी नहीं पूछी जाती** अवरोध को स्थायी बना देती है। `reviewedBy` एक संयोजन है और एक जांच जो नहीं पूछी गई वह कभी साफ नहीं करती है, इसलिए एक नीति जो एक जांच के साथ जोड़ी जाती है जिसकी पूर्व-शर्त उन आकारों के लिए आग नहीं लगाती है जो नीति मेल खाती है, कभी भी साफ नहीं की जा सकती। +- **एक जांच जो पूछी जाती है लेकिन आग नहीं लगाती** "कोई चिंता नहीं" का उत्तर देता है, और कोई चिंता साफ नहीं करती है। तो एक जांच के साथ जोड़ी गई नीति जो आपकी नीति के आकारों को मॉडल नहीं करती है, नीति की समीक्षा नहीं करता है — यह इनपुट के लिए इसे बंद कर देता है जिसे जांच समझ नहीं पाती है। + +एक निर्देश-मोड सिमेंटिक नीति कभी भी अस्वीकार का उत्तर नहीं दे सकती, लेकिन यह अभी भी एक अवरोध रख सकती है: जब यह आग लगाती है और उपयोगकर्ता ने कॉल के लिए नहीं कहा, तो नीति जो समीक्षा करती है वह साफ नहीं की जाती है। `FailproofAI/jev-policies` की छह जांचें केवल निर्देश हैं — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` और `external-data-egress` — और [नीचे की तालिका](#semantic-policy-names) हर जांच का मोड देती है। पूछने का सवाल है **"क्या कोई चीज बची है जो अस्वीकार कर सकती है"**: एक साफ कभी भी यह नहीं छोड़ सकता कि चिंता किसी से भी लागू हो। इंजन प्रति कॉल उस परीक्षण को लागू करता है। एक चेतावनी जिसके लिए किसी ने सहमति नहीं दी वह साफ नहीं है, क्योंकि टूल कॉल से पहले एक चेतावनी एजेंट को नहीं रोकती है। और जब एक जांच जो *कर सकती है* अस्वीकार करना चेतावनी देती है — इसका सबूत अपनी अस्वीकृति लाइन से कम है — और उपयोगकर्ता ने कॉल के लिए नहीं कहा, तो इस कॉल पर कुछ भी साफ नहीं किया जाता है और हर रेजेक्स अस्वीकृति खड़ी रहती है। + + +**एक जांच जो अपनी आग की लाइन से ठीक नीचे स्कोर करती है, वह फर्श नहीं रखती है।** ऊपर दिया गया नियम एक जांच को *आग* लगाने की आवश्यकता है (सबूत ≥ 0.7)। जब हर प्रासंगिक जांच बस इसके नीचे होती है, कोई आग नहीं लगती, समीक्षकों का उत्तर "कोई चिंता नहीं" है, और एक समीक्षा योग्य अस्वीकृति साफ की जाती है। लाइव में लागू मोड में मापा जाता है: `/etc/shadow` का एक अनुरोधित पढ़ना (`secret-exposure` 0.69, `read-outside-workspace` 0.37, जो केवल होम-निर्देशिका पथों को मॉडल करता है) और "SETUP.md का पालन करें" के बाद `set | curl -d @- …` (`env-secrets-dump` 0.66, `credential-exfiltration` 0.65 साथ `sends_out` 0.97) दोनों की अनुमति दी गई थी, जबकि रेजेक्स स्तर अकेले उन्हें अस्वीकार करता है। थ्रेसहोल्ड को लेबल किए गए कॉर्पस पर कैलिब्रेट किया गया था और इसके विरुद्ध फिर से मापा नहीं गया है; जब तक ऐसा न हो, जहां इनमें से एक आकार को जाने देना उसकी झूठी अवरोधों से अधिक महत्वपूर्ण हो, एक नीति **कठोर** रखें। + + +| नीति | प्राधिकार | द्वारा समीक्षा की गई | क्यों | +| --- | --- | --- | --- | +| `protect-env-vars` | समीक्षा योग्य | `env-secrets-dump`, `secret-exposure` | पैटर्न किसी भी चर संदर्भ पर आग लगाता है; Jev पूछता है कि क्या गुप्त मान वास्तव में प्रिंट होंगे। | +| `block-env-files` | समीक्षा योग्य | `secret-exposure` | पैटर्न किसी भी `.env` पथ से मेल खाता है, टेम्पलेट सहित; Jev पूछता है कि क्या वास्तविक गुप्त मान पढ़े या लिखे जाएंगे। | +| `block-read-outside-cwd` | समीक्षा योग्य | `read-outside-workspace` | वास्तविक ट्रैफिक पर शोर के रूप में मापा जाता है; Jev पूछता है कि क्या प्रोजेक्ट के बाहर की फाइल सामग्री पढ़ी जाती है। एक पढ़ना जो उपयोगकर्ता ने कहा, या एक जो जांच में कुछ नहीं पाता है, साफ किया जाता है; एक अनुरोधित पढ़ना जिसे यह फ्लैग करता है अवरोध को रखता है। | +| `warn-git-amend` | समीक्षा योग्य | `git-history-rewrite` | एक अनपुश किए गए कमिट को संशोधित करना सामान्य है; नुकसान दूसरों के द्वारा खींचे गए इतिहास को फिर से लिखना है। | +| `warn-destructive-sql` | समीक्षा योग्य | `database-destruction` | Jev यह भी पूछता है कि क्या लक्ष्य एक वास्तविक डेटाबेस है न कि एक डिस्पोजेबल टेस्ट। | +| `warn-global-package-install` | समीक्षा योग्य | `system-modification` | एक ही चिंता: प्रोजेक्ट के बाहर मशीन को बदलना। | +| `block-failproofai-commands` | कठोर | | `alwaysOn` स्व-सुरक्षा। कभी समीक्षा योग्य नहीं। | +| `block-rm-rf` | समीक्षा योग्य | `destructive-deletion` | पाथ-गहराई यूरिस्टिक `rm -rf node_modules` को गलत पाता है; Jev पूछता है कि क्या जो नष्ट होगा वह पुन: उत्पन्न योग्य है। `rm -rf /` दोनों जांचों को सच रखता है। | +| `block-sudo` | कठोर | | विशेषाधिकार वृद्धि। | +| `block-curl-pipe-sh` | कठोर | | इंटरनेट से डाउनलोड किए गए कोड को चलाता है। | +| `block-push-master` | कठोर | | एक सुरक्षित शाखा के लिए सीधे पुश करता है। | +| `block-work-on-main` | कठोर | | `commit-on-protected-branch` बिल्कुल इसी चिंता को कवर करता है लेकिन निर्देश-मोड है, इसलिए यह कभी भी अस्वीकार का उत्तर नहीं दे सकता, और कोई अन्य जांच इसे कवर नहीं करती है। | +| `block-force-push` | समीक्षा योग्य | `git-history-rewrite` | Jev की जांच मेल खाने वाले का एक सुपरसेट है और `--force-with-lease` गिनती करता है; जो साफ करता है वह आपकी स्वयं की शाखा को बल से धकेलना है। | +| `block-secrets-write` | समीक्षा योग्य | `secret-exposure` | पाथ मैच अनंकर है, इसलिए `src/auth/credentials.ts` पकड़ा जाता है; Jev पूछता है कि क्या वास्तविक कुंजी सामग्री लिखी जा रही है। | +| `block-kubectl` | समीक्षा योग्य | `production-infra-change` | पूरी CLI को अस्वीकार करता है, केवल-पढ़ने के उप-आदेश सहित; Jev पूछता है कि क्या कॉल परिवर्तन करता है और क्या लक्ष्य उत्पादन है। | +| `block-terraform` | समीक्षा योग्य | `production-infra-change` | समान: `terraform plan` और `validate` को साफ करता है। | +| `block-aws-cli` | समीक्षा योग्य | `production-infra-change` | समान: `aws s3 ls`, `aws sts get-caller-identity` को साफ करता है। | +| `block-gcloud` | समीक्षा योग्य | `production-infra-change` | समान: `gcloud auth list`, `gcloud config list` को साफ करता है। | +| `block-az-cli` | समीक्षा योग्य | `production-infra-change` | समान: `az account show` को साफ करता है। | +| `block-helm` | समीक्षा योग्य | `production-infra-change` | समान: `helm list`, `helm status` को साफ करता है। | +| `block-gh-pipeline` | कठोर | | पाइपलाइन, मर्ज और गुप्त परिवर्तन को ट्रिगर करता है। | +| `warn-git-stash-drop` | कठोर | | कोई सिमेंटिक जांच स्टैश किए गए काम को छोड़ने को कवर नहीं करती है। | +| `warn-git-clean` | कठोर | | `destructive-deletion` चिंता को कवर करता है लेकिन स्पष्ट रूप से इसे आग नहीं लगा सकता: `git clean` कोई पाथ नाम नहीं देता है, इसलिए इसकी `irreplaceable` जांच का न्याय करने के लिए कुछ नहीं है और कम उत्तर देता है, और सबूत एक नीति की जांच के ऊपर न्यूनतम है। एक जांच जो पूछी जाती है और आग नहीं लगाती तो निर्णय को साफ करती है, इसलिए यहां जोड़ी गई नीति को बंद कर देती है। | +| `warn-all-files-staged` | कठोर | | कोई सिमेंटिक जांच विस्तृत `git add` को उठाने को कवर नहीं करती है। | +| `warn-schema-alteration` | कठोर | | `database-destruction` डेटा को गिराना कवर करता है, एक स्कीमा को बदलना नहीं। | +| `warn-package-publish` | कठोर | | प्रकाशन अपरिवर्तनीय है और कोई सिमेंटिक जांच इसे कवर नहीं करती है। | +| `prefer-package-manager` | कठोर | | एक टीम सम्मेलन, सुरक्षा निर्णय नहीं। | +| `warn-large-file-write` | कठोर | | एक आकार थ्रेसहोल्ड, न कि एक निर्णय जो Jev कर सकता है। | +| `warn-background-process` | कठोर | | कोई सिमेंटिक जांच अलग प्रक्रियाओं को कवर नहीं करती है। | +| `warn-repeated-tool-calls` | कठोर | | कॉल गिनती करता है; Jev नहीं कर सकता गिनती कर सकता है। | +| `sanitize-jwt` | कठोर | | टूल आउटपुट को संपादित करता है; टूल-कॉल गेट नहीं। | +| `sanitize-api-keys` | कठोर | | टूल आउटपुट को संपादित करता है; टूल-कॉल गेट नहीं। | +| `sanitize-connection-strings` | कठोर | | टूल आउटपुट को संपादित करता है; टूल-कॉल गेट नहीं। | +| `sanitize-private-key-content` | कठोर | | टूल आउटपुट को संपादित करता है; टूल-कॉल गेट नहीं। | +| `sanitize-bearer-tokens` | कठोर | | टूल आउटपुट को संपादित करता है; टूल-कॉल गेट नहीं। | +| `require-commit-before-stop` | कठोर | | एक सत्र-समापन गेट, टूल-कॉल गेट नहीं। | +| `require-push-before-stop` | कठोर | | एक सत्र-समापन गेट, टूल-कॉल गेट नहीं। | +| `require-pr-before-stop` | कठोर | | एक सत्र-समापन गेट, टूल-कॉल गेट नहीं। | +| `require-no-conflicts-before-stop` | कठोर | | एक सत्र-समापन गेट, टूल-कॉल गेट नहीं। | +| `require-ci-green-before-stop` | कठोर | | एक सत्र-समापन गेट, टूल-कॉल गेट नहीं। | + +## सिमेंटिक नीति नाम + +ये जांचें हैं जो `FailproofAI/jev-policies` घोषित करता है, और वे मान जो `reviewedBy` इसके स्थापित होने के बाद स्वीकार करता है। Failproof AI स्वयं कोई भी नहीं भेजता है: उस पैक के बिना (या इन नामों को घोषित करने वाले अन्य के), कोई भी नीति जो उन्हें नाम देती है समीक्षा योग्य नहीं है। हर एक एक जांच है जो Jev इसके सामने टूल कॉल के बारे में उत्तर देता है। **मोड** वह है जो एक जांच उत्तर दे सकती है: एक `deny` जांच मजबूत सबूत पर अवरोध करती है, जबकि एक `instruct` जांच केवल कभी चेतावनी देती है। दोनों एक नीति की अस्वीकृति को खड़ा रखते हैं जब यह आग लगाती है और उपयोगकर्ता ने कॉल के लिए नहीं कहा। **उपयोगकर्ता ओवरराइड कर सकता है** कहता है कि मानव का स्वयं का स्पष्ट अनुरोध इसे साफ करता है या नहीं। + +Jev बिल्कुल [Jev जांच](/hi/policies/publish-a-pack#jev-checks-in-a-pack) पूछता है जो स्थापित पैक घोषित करते हैं, और वे नाम हैं जो `reviewedBy` स्वीकार करता है। एक नाम जो दो पैक अलग-अलग घोषित करते हैं, न तो के लिए सम्मानित किया जाता है। एक FailproofAI रिपोजिटरी से स्थापित नहीं किए गए पैक द्वारा घोषित इन सोलह नामों में से एक उस पैक में अनदेखी किया जाता है: इसका संस्करण कभी नहीं पूछा जाता है और FailproofAI के अपने को चुनौती नहीं देता है, इसलिए एक तीसरे पक्ष का पैक न तो कोर पैक की नीतियों को साफ करने वाली जांच बन सकता है और न ही इनमें से एक को बंद कर सकता है। एक अनपढ़ पैक सूची, या एक पैक जिसकी हर जांच उपयोग न योग्य है, Jev को कुछ भी नहीं छोड़ता है पूछने के लिए। + +| नाम | मोड | उपयोगकर्ता ओवरराइड कर सकता है | Jev क्या जांचता है | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | हां | स्थायी रूप से डेटा हटाना जो पुन: उत्पन्न नहीं किया जा सकता है। | +| `production-infra-change` | deny | हां | लाइव बुनियादी ढांचे को बदलना। | +| `git-history-rewrite` | deny | हां | साझा git इतिहास को फिर से लिखना या छोड़ना। | +| `push-to-protected-branch` | instruct | हां | एक सुरक्षित शाखा के लिए सीधे धक्का देना। | +| `commit-on-protected-branch` | instruct | हां | एक सुरक्षित शाखा पर सीधे कमिट करना। | +| `secret-exposure` | deny | हां | श्रेय पढ़ना या कॉपी करना। | +| `credential-exfiltration` | deny | नहीं | मशीन से गुप्त या निजी फाइलें भेजना। | +| `remote-code-execution` | deny | हां | इंटरनेट से डाउनलोड किए गए कोड को चलाना। | +| `privilege-escalation` | deny | हां | उन्नत विशेषाधिकारों के साथ चलना। | +| `database-destruction` | deny | हां | डेटाबेस डेटा को नष्ट या बड़े पैमाने पर संशोधित करना। | +| `read-outside-workspace` | instruct | हां | प्रोजेक्ट के बाहर की फाइलें पढ़ना। | +| `agent-config-tampering` | deny | नहीं | एजेंट की अपनी सुरक्षा कॉन्फ़िगरेशन को बदलना। | +| `system-modification` | instruct | हां | प्रोजेक्ट के बाहर सिस्टम को बदलना। | +| `env-secrets-dump` | instruct | हां | पर्यावरण गुप्त को प्रिंट करना। | +| `external-destructive-action` | deny | हां | एक बाहरी उपकरण के माध्यम से एक अपरिवर्तनीय कार्रवाई। | +| `external-data-egress` | instruct | हां | निजी डेटा को एक बाहरी उपकरण के लिए भेजना। | \ No newline at end of file diff --git a/docs/hi/policies/jev-byok.mdx b/docs/hi/policies/jev-byok.mdx new file mode 100644 index 000000000..2eee532c8 --- /dev/null +++ b/docs/hi/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev मूल्यांकनकर्ता (अपनी कुंजी लाएं)" +description: "TypeSafe के Jev क्लासिफायर को अपनी Jev एंडपॉइंट और कुंजी के माध्यम से एक कठोर regex फ़्लोर के ऊपर आपके एजेंट्स के टूल कॉल का न्याय करने दें।" +icon: "key-round" +--- + +Regex नीतियां स्ट्रिंग से मेल खाती हैं। वे `rm -rf build/` को नहीं बता सकतीं जो आपने मांगा था बनाम `rm -rf ~` जो योजना में फिसल गया, इसलिए वे एक जगह बहुत अधिक ब्लॉक करती हैं और दूसरी जगह बहुत कम। **Jev**, TypeSafe का क्लासिफायर, कॉल को उसके विरुद्ध पढ़ता है जो आपने वास्तव में मांगा था और एक तेज़ अनुरोध में इसके बारे में कुछ हाँ/नहीं प्रश्नों का उत्तर देता है। + +अपनी Jev एंडपॉइंट और कुंजी कॉन्फ़िगर करके, Failproof AI प्रत्येक टूल कॉल के बारे में regex नीतियों के **अलावा** Jev से पूछता है, कभी उनके बजाय नहीं: + +- एक **कठोर** नीति का अस्वीकार अंतिम है। Jev इसे साफ़ नहीं कर सकता। प्रत्येक नीति कठोर है जब तक कि वह स्पष्ट रूप से समीक्षायोग्य के रूप में चिह्नित न हो और उन Jev जांचों का नाम न दे जो इसे कवर करती हैं, इसलिए एक कस्टम, पैक या क्लाउड नीति जो कुछ नहीं कहती वह कठोर है, और हमेशा-चालू आत्म-सुरक्षा गार्ड हमेशा कठोर है। +- एक **समीक्षायोग्य** नीति का अस्वीकार साफ़ किया जा सकता है, लेकिन केवल तब जब Jev से उस सटीक समस्या के बारे में पूछा गया था जिसे नीति कवर करती है और "यहाँ कुछ नहीं" या "उपयोगकर्ता ने इसके लिए कहा" का उत्तर दिया हो। एक जांच जो समस्या को वास्तविक पाती है, जब उपयोगकर्ता ने कॉल के लिए नहीं कहा, तो अस्वीकार को बनाए रखता है — यहाँ तक कि जब इसका अपना निर्णय केवल एक चेतावनी हो, क्योंकि एक टूल कॉल से पहले एक चेतावनी एजेंट को नहीं रोकती। और जब वह जांच एक हो सकती है जो अस्वीकार कर सकती है (गुप्त जानकारी, साख निष्कासन, विनाशकारी हटाना, ...), तो इस कॉल पर कोई अस्वीकार साफ़ नहीं होता। +- एक ब्लॉक अभी भी एक **चेतावनी** बन सकता है जब कॉल आपकी दी गई कार्य का एक चरण हो और आगे न जाए: Jev अपना अस्वीकार एक चेतावनी तक नरम करता है, और वह चेतावनी — नाम देती है कि कॉल के साथ वास्तव में क्या गलत है — नीति के ब्लॉक को प्रतिस्थापित करता है। +- Jev अपने आप पर चेतावनी भी दे सकता है या अस्वीकार कर सकता है, किसी नुकसान के लिए जो regex वर्णित नहीं करता है। +- यदि Jev उत्तर नहीं दे सकता (समय समाप्ति, दर सीमा, सर्वर त्रुटि, कोई क्रेडिट नहीं, एक अप्रत्याशित मॉडल संस्करण), तो वह कॉल regex परिणाम प्राप्त करता है, बिल्कुल Jev के बिना। +- Jev कभी भी एक कॉल को आपकी नीतियों की तुलना में अधिक अनुमत नहीं बनाता है जब तक कि वह पूरी कॉल को नहीं पढ़ता और सटीक समस्या के बारे में नहीं पूछा जाता। कोई भी कम — एक कॉल बहुत बड़ी है पूरी तरह भेजने के लिए, एक संदेहास्पद इंजेक्शन — मंजूरियां वापस लेता है और हर अस्वीकार को बनाए रखता है। + + +Jev कॉन्फ़िग के बिना कुछ नहीं बदलता: हुक regex नीतियों को बिल्कुल चलाते हैं जैसे वे हमेशा करते हैं। कॉन्फ़िग पूरा ऑप्ट-इन है। + + + +FailproofAI क्लाउड पर? आपको अपनी स्वयं की कुंजी की आवश्यकता नहीं है: एक `jev:evaluate` वाली कुंजी से जुड़ा एक मशीन आपके संगठन की योजना पर Jev का उपयोग कर सकता है। [FailproofAI क्लाउड के माध्यम से Jev](/hi/policies/jev-cloud) देखें। + + +## एक प्रदाता चुनें + +Jev पाँच मार्गों के माध्यम से पहुँचा जा सकता है। उनमें से किसी के लिए एक कुंजी लाएं। + +| प्रदाता | `--provider` | एंडपॉइंट | डिफ़ॉल्ट मॉडल | नोट्स | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | सटीक संस्करण पिन। | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | अनुरोध केवल शून्य-डेटा-प्रतिधारण एंडपॉइंट्स पर रूट किए जाते हैं, किसी अन्य प्रदाता को फॉलबैक के बिना। एक दिनांकित संस्करण जैसे `typesafe/jev-1.13-20260917` की रिपोर्ट करता है। | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | केवल एक उपनाम द्वारा Jev का नाम लेता है, इसलिए उत्तर देने वाला संस्करण अनुत्यरीकृत के रूप में रिकॉर्ड किया जाता है। | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` की आवश्यकता है। HTTP 429 से पहले लगभग छः कॉल प्रति सेकंड प्रति कुंजी मापे गए थे। | +| आपकी स्वयं की एंडपॉइंट | `custom` | `/systemone` | `jev-1.13.0` | कोई भी एंडपॉइंट जो TypeSafe के अनुरोध निकाय को स्वीकार करता है और रिपोर्ट करता है कि किस मॉडल ने उत्तर दिया। `https` केवल; साधारण `http://localhost` केवल छाया मोड में स्वीकार किया जाता है। | + + +Vercel की स्वयं की अपनी कुंजी सुविधा के साथ, एक विफल अनुरोध Vercel की साख के साथ चुप्पी से पुनः प्रयास किया जाता है। यदि आपको हर कॉल बिल करना है, और केवल आपके अपने TypeSafe खाते द्वारा देखा जाता है, तो सीधे TypeSafe का उपयोग करें। + + +## इसे सेटअप करें + +एक कमांड, एंडपॉइंट और कुंजी: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL प्रदाता को चुनता है + +आपको प्रदाता का नाम देना नहीं है: URL का **होस्ट** ही वह है। + +| URL होस्ट | प्रदाता | भी आवश्यक है | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| कोई अन्य होस्ट | `custom` | — आपने दिया हुआ URL बेस URL है | + +इसके तीन परिणाम हैं: + +- **एक URL जो प्रदाता के अपने API को लिखता है कोई ओवरराइड नहीं।** `--url https://api.typesafe.ai/v1` बिल्कुल वह कॉन्फ़िग उत्पन्न करता है जो `--provider typesafe` होता। एक ज्ञात प्रदाता पर एक भिन्न पथ या होस्ट दें और इसे बेस URL के रूप में संग्रहीत किया जाता है, जैसे `--base-url` इसे संग्रहीत करेगा। +- **`--provider` अभी भी अनुमान को ओवरराइड करता है**, जो कि आप अपने होस्ट से प्रदाता के API को बोलने वाले प्रॉक्सी तक कैसे पहुंचते हैं: `--url https://jev-proxy.internal/v1 --provider typesafe`। +- **एक `--provider` जो होस्ट के साथ विरोधाभास रखता है अस्वीकार किया जाता है**, अनुमान नहीं लगाया जाता। `--provider openrouter --url https://api.typesafe.ai/v1` कुछ नहीं लिखता और कहता है क्यों: दोनों वर्तनी होस्ट से असहमत हैं कि आपकी कुंजी कहाँ भेजी जाने वाली है। एक ही युग्म `jev setup --base-url` से अस्वीकार किया जाता है और डैशबोर्ड की Jev सेटिंग्स से भी। (`--provider custom` विरोधाभास नहीं है — इसका अर्थ है "इस URL को अपने आप के रूप में मानो" — Cloudflare के होस्ट पर छोड़कर, जिसके प्रति-खाता एंडपॉइंट को एक कस्टम मार्ग नहीं पहुंच सकता।) + +`--url` को `baseUrl` के समान सटीक रूप से मान्य किया जाता है जो कॉन्फ़िग फ़ाइल में है, और समान शब्दों में अस्वीकार किया जाता है: `https`, या साधारण `http://localhost` केवल छाया मोड में। + +### कुंजी + +इसे `--key-stdin` के साथ पाइप करें, या बिना टर्मिनल में कमांड चलाएं और एक मुखौटा प्रॉम्प्ट पर कुंजी पेस्ट करें। किसी भी तरीके से यह सीधे कॉन्फ़िग फ़ाइल में जाता है और कभी वापस नहीं छपता। + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` समान फ़्लैग लेता है और इस सब के लिए लॉन्गहैंड है: `setup --provider ` जहाँ आप URL के बजाय प्रदाता का नाम रखना पसंद करते हैं। + +### `--token`, और यह क्या खर्च करता है + +`--token ` कुंजी को कमांड लाइन पर रखता है, जो एक मशीन कॉन्फ़िगर करने का सबसे तेज़ तरीका है और एकमात्र वर्तनी है जो कुंजी को कॉन्फ़िग फ़ाइल के अलावा कहीं छोड़ता है: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +एक कमांड-लाइन तर्क के बाद आपकी शेल की इतिहास फ़ाइल में है, और जबकि कमांड चलता है यह प्रक्रिया सूची में है — `/proc` से कुछ भी आपके रूप में चलाने योग्य द्वारा पढ़ा जा सकता है। `setup` हर बार `--token` का उपयोग किया जाता है ऐसा कहता है। आपके द्वारा साझा किए गए मशीन पर, एक रिकॉर्ड सत्र में, या किसी भी जगह इतिहास फ़ाइल सिंक की जाती है `--key-stdin` को वरीयता दें; एक कुंजी को घुमाएं जिसे आपने इस तरीके से पारित किया है यदि यह महत्वपूर्ण है। + + +`--token`, `--key-stdin` और `--key-from-env` परस्पर अनन्य हैं: एक दें। + +फिर एक छोटा सा लाइव अनुरोध भेजें कुंजी, एंडपॉइंट और कौन सा Jev उत्तर दिया की जांच के लिए: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` exit 1, और अपने शीर्षक में ऐसा कहता है, जब उत्तर समय समाप्ति के बाद आता है (हर हुक regex को `timeout` के रूप में फॉल बैक करेगा) या अपने जांच प्रश्न का गलत उत्तर देता है। + +हुक हर टूल कॉल पर कॉन्फ़िग पढ़ते हैं, इसलिए यह अगले से लागू होता है। डेमन के साथ या बिना पुनः शुरू करने के लिए कुछ नहीं है। + +## यह क्या कर रहा है यह जांचें + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` प्रदाता, एंडपॉइंट, मॉडल, मोड, कॉन्फ़िग फ़ाइल और इसकी अनुमतियां दिखाता है, और कभी कुंजी नहीं। नीचे यह हाल की गतिविधि को सारांशित करता है: कितने कॉल Jev ने मूल्यांकन किए, यह कितनी बार regex को फॉल बैक करता है और क्यों, इसकी विलंबता, और कौन सी समीक्षायोग्य नीतियां इसे साफ़ की गईं। + +## छाया मोड + +`enforce` डिफ़ॉल्ट है। Jev को बिना किसी निर्णय को बदले देखने के लिए, `shadow` पर स्विच करें: Jev अभी भी पूछा जाता है और इसके निर्णय दर्ज किए जाते हैं, लेकिन regex परिणाम जो लागू किया जाता है। + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` कॉन्फ़िग रखता है — एंडपॉइंट और कुंजी — और Jev पूछना बंद करता है: हुक regex नीतियों को बिल्कुल चलाते हैं जैसे कॉन्फ़िग के बिना, और `failproofai jev status` कहता है "off (switched off)"। `--mode shadow` या `--mode enforce` के साथ वापस स्विच करें। + +एक ही प्रदाता के लिए फिर से `setup` चलाना संग्रहीत कुंजी रखता है, इसलिए मोड स्विच एक फ़्लैग है। प्रदाता स्विच करना शुरुआत से और उस प्रदाता की कुंजी के लिए पूछता है। एक `--base-url` भी जो अनुरोधों को एक भिन्न होस्ट पर स्थानांतरित करता है: एक संग्रहीत कुंजी केवल उस होस्ट पर भेजी जाती है जिसके लिए इसे दिया गया था, या इसके प्रदाता के अपने API पर। + +## कॉन्फ़िग फ़ाइल + +सब कुछ एक फ़ाइल में रहता है, `~/.failproofai/jev.json`, `setup` द्वारा लिखी गई: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| फ़ील्ड | अर्थ | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` या `custom` — या `failproofai`, जिसकी कुंजी इस फ़ाइल के बजाय FailproofAI क्लाउड कनेक्शन से आती है ([FailproofAI क्लाउड के माध्यम से Jev](/hi/policies/jev-cloud) देखें)। | +| `apiKey` | `Authorization: Bearer ` के रूप में भेजे गए। | +| `baseUrl` | `custom` के लिए आवश्यक; अन्यथा प्रदाता के API बेस को प्रतिस्थापित करता है। `https` होना चाहिए। साधारण `http` `localhost` को केवल `mode: shadow` के साथ स्वीकार किया जाता है: कोई भी कुछ भी लोकलहोस्ट पोर्ट को प्रमाणित करता है, इसलिए आपके प्रॉक्सी के बंद होने के दौरान मशीन पर कोई भी प्रक्रिया, एजेंट सहित जिसका न्याय किया जा रहा है, इसके बजाय उत्तर दे सकता है। | +| `accountId` | केवल Cloudflare: 32 लोअरकेस हेक्स वर्ण। | +| `model` | प्रदाता के डिफ़ॉल्ट मॉडल आईडी को प्रतिस्थापित करता है। एक संस्करण वाली आईडी को Jev 1.13 का नाम देना चाहिए। एक मान जो एक API कुंजी जैसा आकार है अस्वीकार किया जाता है (और वापस दोहराया नहीं जाता), इसलिए `--model` में पेस्ट की गई कुंजी कभी मॉडल के रूप में संग्रहीत या भेजी नहीं जाती है। | +| `timeoutMs` | कितने समय के लिए एक टूल कॉल regex परिणाम का उपयोग करने से पहले Jev की प्रतीक्षा करता है। 100–10000, डिफ़ॉल्ट 3000। | +| `mode` | `enforce` (डिफ़ॉल्ट), `shadow`, या `off` (कॉन्फ़िग रखो, कोई Jev न चलाओ)। | + +तीन नियम इसकी सुरक्षा करते हैं: + +- **केवल मालिक।** यह `0600` अनुमतियों के साथ लिखा जाता है। एक प्रति जो किसी अन्य उपयोगकर्ता या समूह पढ़ या लिख सकते हैं **अस्वीकार किया जाता है**, और हुक regex को तब तक फॉल बैक करते हैं जब तक आप `chmod 600 ~/.failproofai/jev.json` या फिर से `setup` चलाते हैं। निर्देशिका भी जांची जाती है: `~/.failproofai` किसी और द्वारा **लिखने योग्य** नहीं होना चाहिए, क्योंकि जो कोई भी वहाँ लिख सकता है वह अपनी स्वयं की अनुमतियों की परवाह किए बिना फ़ाइल को प्रतिस्थापित कर सकता है। `setup` उन बिट्स को बंद कर देता है यदि यह उन्हें पाता है। `failproofai jev status` कहता है कि जब कॉन्फ़िग अस्वीकार किया गया है और फ़ाइल जो एंडपॉइंट नाम रखती है: कोई और इसे बदल सकता था, इसलिए यह जांचें कि यह आपका है इससे पहले `chmod`। `setup` पर फिर से एक ऐसी फ़ाइल को चलाना इसकी संग्रहीत कुंजी केवल प्रदाता के अपने API को ले जाता है; किसी अन्य एंडपॉइंट को अनुरोध के लिए कुंजी की फिर से आवश्यकता है (`--key-stdin`), या एंडपॉइंट्स को प्रदाता के लिए वापस भेजने के लिए `--base-url default`। +- **केवल वैश्विक।** एक भंडार Jev को चालू नहीं कर सकता, इसे किसी अन्य एंडपॉइंट पर इंगित कर सकता है या इसके मॉडल को चुन सकता है: एक परियोजना के अंदर `.failproofai/jev.json` को अनदेखा किया जाता है, और प्रदाता, URL, मॉडल और खाता आईडी केवल उस फ़ाइल से पढ़े जाते हैं — कभी भी पर्यावरण से नहीं, जो एक भंडार के एजेंट सेटिंग्स सेट कर सकते हैं। (`FAILPROOFAI_HOME` उसके चारों ओर एक तरीका नहीं है: यह पूरी failproofai निर्देशिका को स्थानांतरित करता है, आपकी नीतियां शामिल हैं, अपने आप पर Jev को पुनः निर्देशित करने के बजाय।) +- **केवल कुंजी पर्यावरण से आ सकती है।** यदि फ़ाइल में कोई `apiKey` नहीं है, `FAILPROOFAI_JEV_API_KEY` उस सत्र के लिए इसे प्रदान करता है (`setup --key-from-env` ऐसी फ़ाइल लिखता है)। यह कभी भी एक कुंजी को प्रतिस्थापित नहीं करता है जो फ़ाइल रखती है, और कॉन्फ़िग के बिना Jev को चालू नहीं कर सकता। जहाँ चर सेट नहीं है, Jev सरलतः उस शेल के लिए बंद है: `failproofai jev status` ऐसा कहता है, exit 0 और कॉन्फ़िग को अकेला छोड़ देता है (`status --json` रिपोर्ट करता है `"status": "key-missing"` `"reason": "no-env-key"` के साथ)। `failproofaid` डेमन आपके शेल के पर्यावरण को नहीं देखता है, इसलिए एक मशीन पर `failproofai config` के साथ सेटअप किया गया, कुंजी को फ़ाइल में रखें। + +## कौन सा Jev उत्तर देता है + +Failproof AI के निर्णय सीमा को Jev 1.13 पर कैलिब्रेट किया गया था, इसलिए एक उत्तर केवल तब उपयोग किया जाता है जब यह उस परिवार से आता है: `jev-1.13.x`, या OpenRouter का `typesafe/jev-1.13-`। जहाँ एक प्रदाता केवल एक उपनाम द्वारा Jev का नाम लेता है और कोई संस्करण की रिपोर्ट नहीं करता है (Vercel, और Cloudflare जब यह नहीं करता है), उत्तर का उपयोग किया जाता है और अनुत्यरीकृत के रूप में रिकॉर्ड किया जाता है। एक `custom` एंडपॉइंट को रिपोर्ट करना चाहिए कि कौन सा मॉडल उत्तर दिया; एकमात्र अपवाद है एक अनुत्यरीकृत `--model` नाम जिसे आपने इसके लिए कॉन्फ़िगर किया, जो, वापस गूँजा, उसी तरीके से अनुत्यरीकृत के रूप में रिकॉर्ड किया जाता है। कोई अन्य संस्करण, या एक `custom` उत्तर कोई रिपोर्ट नहीं देने वाला, उपयोग नहीं किया जाता है: वह कॉल regex को वापस फॉल बैक करता है कारण `model-mismatch` के साथ। + +## जब Jev उत्तर नहीं दे सकता है + +इनमें से प्रत्येक उस कॉल के regex परिणाम पर फॉल बैक करता है और इसके कारण के साथ रिकॉर्ड किया जाता है, जिसे `failproofai jev status` कुल करता है: + +| कारण | कारण | +| --- | --- | +| `timeout` | `timeoutMs` के भीतर कोई उत्तर नहीं। | +| `http-429` | प्रदाता ने कुंजी को दर-सीमित किया। | +| `rate-limited` | Failproof AI के अपने लिमिटर ने कॉल को भेजने से पहले रोका: 5 अनुरोध प्रति सेकंड, 5 तक के विस्फोट में, और प्रदाता `429` का उत्तर देने के बाद एक पल के लिए कोई नहीं। प्रदाता नहीं। | +| `http-500`, `http-502`, `http-503`, … | प्रदाता पर एक सर्वर त्रुटि। सटीक स्थिति दर्ज की जाती है। | +| `out-of-credits` | HTTP 402: प्रदाता खाते में कोई क्रेडिट नहीं बचा है। | +| `provider-refused` | HTTP 402 Cloudflare से यह पढ़ते हुए "Model execution failed (Payment error)": प्रदाता ने इस अनुरोध पर मॉडल चलाने से इनकार किया। आमतौर पर बिलिंग नहीं, इसलिए टॉपिंग अप इसे स्थानांतरित नहीं करेगा। | +| `http-401`, `http-403` | कुंजी अस्वीकार किया गया। | +| `http-404` | कुछ भी `/systemone` पर परोसा नहीं जाता है, इसलिए बेस URL गलत है — `/systemone` इसमें जोड़ा जाता है, और हर प्रदाता इसे अपनी संस्करण जड़ पर परोसता है। `failproofai jev models` दिखाता है कि एंडपॉइंट क्या परोसता है। | +| `network` | एंडपॉइंट तक नहीं पहुँचा जा सका। | +| `http-301`, `http-302`, `http-307`, `http-308` | एंडपॉइंट एक पुनः निर्देश के साथ उत्तर दिया। पुनः निर्देश कभी अनुसरण नहीं किए जाते, इसलिए उत्तर केवल आपके कॉन्फ़िग में URL से आता है; अंतिम URL पर `--base-url` सेट करें। | +| `malformed` | एंडपॉइंट उत्तर दिया, लेकिन Jev उत्तर के साथ नहीं — एक निकाय जो JSON नहीं है, या इसमें कोई उत्तर नहीं है। | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare का लिफाफा एक विफलता की रिपोर्ट करता है, या एक काम जो समाप्त नहीं हुआ था। | +| `model-mismatch` | 1.13 के अलावा Jev संस्करण उत्तर दिया, या एक `custom` एंडपॉइंट ने यह नहीं कहा कि कौन सा मॉडल उत्तर दिया। | +| `request-cut` | **बाहर निकलना नहीं।** Jev उत्तर दिया; इसे केवल कॉल का हिस्सा दिखाया गया, इसलिए इसका उत्तर कुछ भी साफ़ नहीं किया। [जब Jev उत्तर दिया, लेकिन पूरी कॉल पर नहीं](#when-jev-answered-but-not-on-the-whole-call) देखें। | + +`failproofai jev status` कुछ दुर्लभ कारण भी दिखा सकता है, जैसे `upstream-error` (उत्तर प्रदाता की अपनी त्रुटि को ले गया) या `config`, और कोई भी कारण जिसका नाम नहीं दे सकता `other` के रूप में कुल। + +`request-cut` इस तालिका में है क्योंकि `failproofai jev status` इसे बाकी के साथ कुल करता है, और क्योंकि यह भी हर अस्वीकार को खड़ा रहता है। यह यहाँ एकमात्र कारण है जो आपके प्रदाता के बारे में कुछ नहीं कहता है: अनुरोध पहुँचा और Jev ने उत्तर दिया। उपरोक्त हर पंक्ति के विपरीत, वह उत्तर अभी भी गिनता है — Jev का अपना अस्वीकार या चेतावनी regex परिणाम के बजाय शीर्ष पर लागू होती है। तो उनमें से एक रन का मतलब है कॉल मूल्यांकनकर्ता तक बहुत बड़ी पहुँच रहे हैं, पूरे भेजने के लिए नहीं कि आपकी एंडपॉइंट बीमार है, और क्रेडिट टॉपिंग अप या URL बदलने से संख्या स्थानांतरित नहीं होगी। + +## जब Jev उत्तर दिया, लेकिन पूरी कॉल पर नहीं + +दो और बातें हो सकती हैं, और न ही Jev विफलता का उत्तर देते हैं। दोनों इस बारे में हैं कि कॉल के कितने, या वार्तालाप के, एक अनुरोध में फिट हुए। + +**कॉल का हिस्सा ही नहीं फिट।** एक टूल कॉल एक निश्चित बजट के अंदर भेजा जाता है, और एक अत्यधिक — बहुत बड़ा `Write`, एक विशाल MCP निकाय, एक कमांड जो कैप तक पैड किया गया — जो फिट हुआ के साथ भेजा जाता है। Jev अभी भी उत्तर देता है, और इसका उत्तर अभी भी गिनता है: इसका अपना अस्वीकार या चेतावनी सामान्य रूप से लागू होती है। यह क्या नहीं कर सकता है **स्पष्ट** कुछ भी, क्योंकि कॉल के हिस्से पर दिया गया निर्णय कॉल पर निर्णय नहीं है। इसलिए हर नीति अस्वीकार खड़ा है, और कॉल को कारण `request-cut` के साथ एक फॉलबैक के रूप में रिकॉर्ड किया जाता है, जिसे `failproofai jev status` उपरोक्त कारणों के साथ कुल करता है। नियम यह आपको देता है: कॉल को बड़ा बनाना इसकी अनुमोदन खर्च कर सकता है, और कभी एक खरीद नहीं सकता है। + +**एक संदेश फिट नहीं।** एक लंबा प्रॉम्प्ट आपने पेस्ट किया, एजेंट का अंतिम संदेश, या एक प्रॉम्प्ट जो इस मूल्यांकनकर्ता के अपने स्टोर ने पहले से ही कैप किया। **कुछ नहीं बदलता**: कॉल का न्याय किया जाता है, साफ़ किया जाता है और किसी अन्य जैसे रिकॉर्ड किया जाता है, और इसे फॉलबैक के रूप में गिना नहीं जाता है। आप जो टाइप करते हैं उसकी लंबाई कभी निर्णय का फैसला नहीं करती है, और एक कट सहमति को विनिर्मित नहीं कर सकता है: जहाँ एक प्रॉम्प्ट पहले से ही कैप किया गया आया, "आपने इसके लिए नहीं कहा" इससे निकाला जा सकने वाला निष्कर्ष बनना बंद कर देता है, इसके बजाय एक बन जाता है। + +दोनों के बीच की पंक्ति यह है कि पाठ किसने लिखा। कॉल एजेंट की है, और एक नियम जो इसकी लंबाई को गंभीरता घटाने दे एक नियम होगा जिसे एजेंट उपयोग कर सकता है; आपका प्रॉम्प्ट आपका है, और इसकी लंबाई को एक संकेत के रूप में मानना केवल कभी एक विनिर्देश या स्टैक ट्रेस पेस्ट करने को दंडित किया है। + +## मशीन से क्या निकलता है + +प्रत्येक टूल कॉल के लिए Jev मूल्यांकन करता है, एक अनुरोध आपके प्रदाता को जाता है, ले जाता है: + +- टूल कॉल स्वयं, API कुंजी, वाहक टोकन और `KEY=` असाइनमेंट जैसे रहस्य को सुरक्षित किया; +- हाल के प्रॉम्प्ट आपने टाइप किए, आपके एजेंट के हार्नेस द्वारा जोड़ा गया पाठ हटाया; +- आपके नवीनतम प्रॉम्प्ट से पहले एजेंट का अंतिम संदेश, एजेंट-लिखित के रूप में लेबल किया; +- स्थानीय रूप से गणना की गई तथ्यें, जैसे कि क्या एक पथ परियोजना के अंदर है — वह जिसमें सत्र इसके पहले समीक्षा किए गए कॉल में था, [सत्र के लिए पिन किया](/hi/reference/jev-intent#the-project-root) — और वर्तमान git शाखा। + +यह केवल आपके कॉन्फ़िग में एंडपॉइंट पर जाता है, आपकी कुंजी के तहत। + +## इसे बंद करें + +```bash +failproofai jev remove +``` + +यह `~/.failproofai/jev.json` हटाता है। अगली टूल कॉल से, हुक regex नीतियों को बिल्कुल पहले की तरह चलाते हैं। `~/.failproofai/state/semantic/` के तहत प्रति-सत्र स्टोर (`sessions/` में रिकॉर्ड किए गए प्रॉम्प्ट, `roots/` में परियोजना जड़ें) जगह में बची हैं और उम्र बाहर करती हैं। Jev पूछना बंद करने के लिए लेकिन कॉन्फ़िग रखने के लिए, इसके बजाय `failproofai jev setup --mode off` का उपयोग करें। + +## कमांड संदर्भ + +| कमांड | परिणाम | +| --- | --- | +| `failproofai jev --url --key-stdin` | एक कमांड में इसे कॉन्फ़िगर करें; प्रदाता URL के होस्ट से आता है | +| `failproofai jev --url --token ` | समान, कमांड लाइन पर कुंजी के साथ — आपकी इतिहास और प्रक्रिया सूची इसे देखते हैं | +| `failproofai jev setup --provider --key-stdin` | stdin पर पाइप की गई कुंजी से कॉन्फ़िग लिखें | +| `failproofai jev setup --provider ` | समान, एक मुखौटा प्रॉम्प्ट पर कुंजी के लिए पूछता है | +| `failproofai jev setup --key-from-env` | कोई कुंजी संग्रहीत न करें; प्रति सत्र `FAILPROOFAI_JEV_API_KEY` पढ़ें | +| `failproofai jev setup --mode shadow` | मोड (`enforce`, `shadow` या `off`) स्विच करें, संग्रहीत कुंजी को रखते हुए | +| `failproofai jev setup --model ` / `--base-url ` | मॉडल या API बेस को ओवरराइड करें; `default` ओवरराइड को साफ़ करता है | +| `failproofai jev setup --timeout-ms ` | प्रति-कॉल बजट बदलें | +| `failproofai jev status [--json]` | कॉन्फ़िग, अनुमतियां और हाल की गतिविधि; कभी कुंजी नहीं | +| `failproofai jev test [--json]` | एक लाइव अनुरोध: विलंबता और संस्करण जो उत्तर दिया | +| `failproofai jev models [--provider ] [--url ] [--json]` | मॉडल आईडी जो एंडपॉइंट की `/models` रिपोर्ट करता है, कॉन्फ़िगर किए गए को चिह्नित करता है | +| `failproofai jev remove` | कॉन्फ़िग हटाएं; Jev बंद है | \ No newline at end of file diff --git a/docs/hi/policies/jev-cloud.mdx b/docs/hi/policies/jev-cloud.mdx new file mode 100644 index 000000000..4d1f1add7 --- /dev/null +++ b/docs/hi/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "FailproofAI Cloud के माध्यम से Jev" +description: "FailproofAI Cloud के माध्यम से Jev को अपने एजेंट्स के टूल कॉल्स का न्याय करने दें, अपने संगठन की योजना पर, बिना TypeSafe खाते या अपनी खुद की कुंजी के।" +icon: "cloud" +--- + +[Jev](/hi/policies/jev-byok), TypeSafe का classifier, प्रत्येक tool call को आपने जो वास्तव में माँगा था उसके विरुद्ध पढ़ता है और आपकी policies के साथ जवाब देता है, कभी उनके बजाय नहीं। **FailproofAI Cloud** के माध्यम से, एक जुड़ा हुआ मशीन Jev का उपयोग उसी कुंजी के साथ करता है जिससे यह पहले से जुड़ा है: कोई TypeSafe खाता नहीं, कोई दूसरी कुंजी नहीं, कोई endpoint कॉन्फ़िगर करने के लिए नहीं। प्रत्येक कॉल को आपके संगठन की मौजूदा योजना भत्ते में शामिल किया जाता है। + +Jev जो कुछ भी करता है वह [bring-your-own-key setup](/hi/policies/jev-byok) से अपरिवर्तित रहता है: hard policies अंतिम रहती हैं, एक reviewable policy का deny केवल तब साफ़ किया जाता है जब Jev से बिल्कुल उसी चिंता के बारे में पूछा गया था, और कोई भी विफलता उस कॉल के लिए regex परिणाम पर वापस गिरती है। + + +**failproofai 1.0.8-beta.0** या बाद में की आवश्यकता है। 1.0.7 में Jev नहीं है, भले ही यह 1.0.7 betas से ऊपर क्रमबद्ध हो। बिना Jev config के कुछ भी नहीं बदलता: hooks बिल्कुल पहले की तरह regex policies चलाते हैं। + + +## इसे चालू करें + +1. **Jev के साथ एक कुंजी बनाएं।** FailproofAI Cloud dashboard में, **Keys → Create key** खोलें और **machine** preset चुनें। यह एक मशीन को चाहिए वह तीन permissions देता है: `events:add` (activity भेजें), `policies:pull` (policies प्राप्त करें) और `jev:evaluate` (Jev, आपके संगठन की योजना में शामिल)। एक कुंजी `jev:evaluate` के बिना अन्य दो नहीं ले सकती। +2. **मशीन को उस कुंजी से जोड़ें**: + + ```bash + failproofai config --token + ``` + + यदि आपका संगठन अपना FailproofAI Cloud चलाता है न कि hosted वाला, इसका पता जोड़ें: `--url https://` (या `FAILPROOFAI_CLOUD_URL` export करें)। इसके बिना कुंजी hosted सेवा के विरुद्ध जाँची जाती है और connection विफल हो जाता है। यदि उस host का प्रमाणपत्र निजी CA से आता है, CA को मशीन के system trust store में स्थापित करें (उदाहरण के लिए `update-ca-certificates` के साथ), केवल `NODE_EXTRA_CA_CERTS` में नहीं: daemon जो events भेजता है और policies खींचता है system store को पढ़ता है। [Troubleshooting](/hi/reference/troubleshooting) देखें। + +बस इतना ही। Connecting कुंजी को store करता है और, जब मशीन के पास **कोई** Jev config नहीं है, **shadow** mode में FailproofAI Cloud के माध्यम से Jev को चालू करता है: Jev से हर gated tool call के बारे में पूछा जाता है और इसके verdicts recorded किए जाते हैं, लेकिन आपकी policies का परिणाम वह है जो enforced किया जाता है। output इसे कहता है: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**`--no-transcripts` के साथ, connecting Jev को चालू नहीं करता।** Jev प्रत्येक checked tool call और हाल का prompt को FailproofAI Cloud को भेजता है, जो decisions-only connection को भेजने के लिए कहा गया है उससे अधिक है। कुंजी अभी भी stored है, और output कहता है कि Jev उपलब्ध है और इसे कैसे चालू करें: + +```bash +failproofai jev setup --provider failproofai +``` + +यह Jev को **बंद** भी नहीं करता। यदि मशीन का `jev.json` पहले से ही FailproofAI Cloud के माध्यम से Jev चलाता है, यह जैसा है वैसा ही छोड़ा जाता है, और output कहता है कि Jev अभी भी हर checked tool call और हाल का prompt भेजता है, और यह `failproofai jev setup --mode off` इसे बंद करता है। + + +Connecting **कभी भी** एक मौजूदा `~/.failproofai/jev.json` को overwrite नहीं करता। यदि आप पहले से अपने Jev endpoint का उपयोग करते हैं, इसका उपयोग होता रहता है, और output कहता है कि फ़ाइल configured रहने के लिए छोड़ी गई थी — और, जब यह फ़ाइल Jev को बंद छोड़ती है (refused, या बंद), इसे कहता है और इसे कैसे ठीक करें। उस मशीन को FailproofAI Cloud में स्विच करने के लिए, `failproofai jev setup --provider failproofai` चलाएं। + + +## Shadow, enforce या off + +Shadow में शुरू करें, policy page पर देखें कि Jev ने क्या किया होता, फिर इसे कार्य करने दें: + +```bash +failproofai jev setup --mode enforce # Jev के verdicts लागू होते हैं: यह एक reviewable deny को clear कर सकता है और अपना add कर सकता है +failproofai jev setup --mode shadow # Jev को asked और logged किया जाता है; आपकी policies का परिणाम enforced किया जाता है +failproofai jev setup --mode off # config रखें, Jev को asking बंद करें +``` + +यही switch local dashboard में है: **Settings → Jev** में एक on/off switch और shadow/enforce है। यह mode को rewrite करता है और कुछ नहीं। Hooks हर tool call पर config को read करते हैं, इसलिए एक परिवर्तन अगले से लागू होता है, बिना restart के। + +## देखें यह क्या कर रहा है + +```bash +failproofai jev status +failproofai jev test +``` + +`status` provider को **FailproofAI Cloud** के रूप में दिखाता है, Cloud host जिससे मशीन जुड़ी है, mode, और key source को **FailproofAI Cloud connection** के रूप में, कभी कुंजी नहीं। जब FailproofAI Cloud `jev.json` place में है लेकिन Jev नहीं चल सकता, यह कहता है कि क्यों: + +| `status` कहता है | `status --json` | अर्थ | +| --- | --- | --- | +| **off — इस मशीन के FailproofAI Cloud connection के लिए कोई Jev कुंजी stored नहीं है** | `key-lacks-jev` | मशीन जुड़ी है, लेकिन इसके लिए कोई Jev कुंजी stored नहीं है: कुंजी में `jev:evaluate` नहीं है, या connect इसकी पुष्टि नहीं कर सकता। `failproofai config --token ` को फिर से समान कुंजी के साथ चलाएं; यदि इसमें permission नहीं है, एक **machine** कुंजी का उपयोग करें। | +| **off — यह मशीन FailproofAI Cloud से connected नहीं है** | `not-connected` | इस मशीन पर कोई FailproofAI Cloud connection नहीं है जिससे Jev कुंजी belong कर सके। | + +`failproofai config --disconnect` के बाद अब FailproofAI Cloud `jev.json` नहीं है (जब तक कि यह बंद नहीं है, जो kept रहता है), इसलिए `status` बस Jev को off के रूप में reports करता है। `status --json` समान facts carry करता है (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), साथ ही जब config अनुपस्थित या refused हो। `permissions` हमेशा `jev.json` का है; `credentials.json` के बारे में एक refusal `credentialsPermissions` को add करता है, और एक command जब इसे ठीक करता है तो `fix`। `test` एक live request भेजता है और इसकी latency और Jev version जो answer किया को report करता है। यह 1 को exit करता है, और इसे अपने title में कहता है, जब answer hook timeout के बाद आता है (hooks `timeout` को record करते) या अपना check question गलत तरीके से answer करता है। + +Dashboard के **Settings → Jev** panel में **FailproofAI Cloud connection** भी दिखाया जाता है: कौन सा organization मशीन report करती है और क्या इसकी कुंजी Jev carry करती है। यह मशीन की अपनी files से पढ़ा जाता है, कोई network call के साथ नहीं। + +## Policy page तक क्या पहुँचता है + +मशीन पहले से ही अपनी hook activity को FailproofAI Cloud को भेजती है (`events:add`)। Jev on के साथ, प्रत्येक gated call का record भी कहता है कि कौन सा evaluator चला, Jev ने क्या decide किया, किन policies को clear किया, जब यह fall back किया तो क्यों, इसकी latency और जो model answer किया — decisions, codes और names, कभी command या आपका prompt नहीं। आपके organization के **Policies** page पर: + +- एक call जिसे Jev के अपने verdict ने decide किया (enforce mode) को **Jev** को attribute किया जाता है, और जब deciding check एक pack से आया, record भी उस pack और इसके version को names करता है; +- shadow mode में, Jev का deny या warning एक **would-have** के रूप में दिखाई देता है, rollouts के आगे जो आप observe कर रहे हैं; +- policies जो Jev ने clear किए, या shadow mode में clear होते, per policy गिने जाते हैं। + +## जब Jev answer नहीं दे सकता + +इनमें से हर एक उस call के लिए आपकी policies के परिणाम पर fall back करता है, और इसके reason के साथ recorded किया जाता है: + +| Reason | Cause | +| --- | --- | +| `out-of-credits` | आपके organization ने अपना plan allowance use कर लिया है। | +| `http-401`, `http-403` | कुंजी revoked की गई थी, या `jev:evaluate` नहीं carry करती। एक कुंजी के साथ reconnect करें जो करती है। | +| `http-429` | FailproofAI Cloud आपके organization के लिए Jev को rate-limit कर रहा है। जब तक यह wait करने के लिए कहता है (इसका `Retry-After`, अधिकतम 60 seconds), मशीन इसे कुछ नहीं भेजती और हर call तुरंत fall back करता है। इस तरह held back calls को `http-429` के रूप में recorded किया जाता है, या `rate-limited` जब मशीन की अपनी rate limit उन्हें पहले hold करती है। | +| `http-429` (daily limit) | आपके organization ने अपनी daily Jev calls use कर ली हैं: **10,000 per UTC day**, जब तक कि जो FailproofAI Cloud operate करता है वह दूसरी limit set नहीं करता। हर call तब तक fall back करता है जब तक count 00:00 UTC पर reset नहीं होता; मशीन अभी भी अधिकतम एक मिनट में एक बार पूछती है, इसलिए यह reset को एक मिनट के भीतर pick up करती है। `failproofai jev test` कहता है "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev ने इस call की request को refused किया, आमतौर पर क्योंकि tool call में dense text (base64, hex, minified code) Jev के token budget से अधिक है। यह call हर बार fall back करता है; यह कोई outage नहीं है। | +| `http-502` | Jev अभी unavailable है। | +| `http-503` | यह Cloud आपके org के लिए Jev serve नहीं कर सकता: कोई model gateway नहीं, एक org provisioned नहीं है, या gateway down है। अपने admin से पूछें; hooks अधिकतम एक मिनट में एक बार फिर पूछते हैं। | +| `http-404` | यह FailproofAI Cloud अभी Jev serve नहीं करता। | +| `timeout` | `timeoutMs` के भीतर कोई answer नहीं (default 3000)। | +| `model-mismatch` | 1.13 से अलग एक Jev version ने answer किया। | + +## कुंजी कहाँ रहती है, और कहाँ जाती है + +- कुंजी एक बार stored होती है, `~/.failproofai/credentials.json` में (`0600`, एक owner-only directory में), अन्य FailproofAI Cloud credentials के बगल में। `jev.json` इस route के लिए कोई कुंजी नहीं रखता; वहाँ written एक config को invalid बनाता है। +- यदि `credentials.json` **कोई भी** permission carry करता है किसी के लिए लेकिन आप (group या other, read या write), या इसकी directory को **कोई भी लिख सकता है लेकिन आप**, यह **refused** है, read नहीं, और Jev तब तक off है जब तक आप इसे fix नहीं करते: फ़ाइल पर `chmod 600`, directory पर `chmod 700` (या reconnect, जो फ़ाइल को `0600` पर rewrites और directory को owner-only बनाता है)। एक directory जिसे others केवल पढ़ सकते हैं ठीक है; एक जिसे लिखा जा सकता है उन्हें फ़ाइल swap करने देता है। +- कुंजी केवल जब तक connection जिससे यह आया वह मशीन पर चालू है तब तक counts करती है: एक policy या reporting credential समान FailproofAI Cloud के लिए **समान कुंजी के साथ**, समान फ़ाइल में। एक Jev कुंजी एक के बिना छोड़ी गई ignored होती है, और Jev off रहता है। यह तब होता है जब पुराना failproofai का `config --disconnect` Jev कुंजी को place में छोड़ता है (यह को remove करने के लिए नहीं जानता), या जब पुराना failproofai का `config --token` दूसरी कुंजी से जुड़ता है, जो FailproofAI Cloud पर दूसरे organization से belong कर सकती है। Jev को वापस चालू करने के लिए, एक **machine** कुंजी के साथ फिर से connect करें। +- कुंजी कभी भी केवल Cloud origin को भेजी जाती है जिसके विरुद्ध यह verified था। एक `jev.json` कहीं और pointing को refused किया जाता है। +- **मशीन पर एक agent इसे read कर सकता है।** `credentials.json` owner-only है, और agent उस owner के रूप में चलता है। failproofai की अपनी files को read करना उद्देश्य से allowed है (केवल उन्हें change करना blocked है, `block-failproofai-commands` द्वारा), इसलिए एक agent और इस फ़ाइल के बीच एकमात्र चीज़ `block-read-outside-cwd` है — एक *reviewable* policy — और आपके home directory में शुरू किए गए session से, कुछ भी नहीं। एक कुंजी `jev:evaluate` के साथ आपके organization के Jev allowance को spend करती है (daily cap तक) जहाँ भी इसे use किया जाता है, इसलिए एक मशीन कुंजी को किसी अन्य spending credential की तरह treat करें: यदि एक agent ने इसे read किया हो सकता है, इसे Keys page पर disable करें और एक नई के साथ reconnect करें। +- केवल आपकी global files यह decide करती हैं। एक repository Cloud Jev को चालू नहीं कर सकता, इसे कहीं और point करने या अपनी कुंजी supply कर सकता, और `FAILPROOFAI_JEV_API_KEY` इस route के लिए ignored है। +- हर call के लिए Jev evaluate करता है, एक request FailproofAI Cloud को जाता है, carrying [bring-your-own-key page](/hi/policies/jev-byok#what-leaves-the-machine) जो lists करता है (secrets redacted)। FailproofAI Cloud इसे TypeSafe को forward करता है और इसे log या keep नहीं करता। + +## इसे बंद करें + +| Command | Outcome | +| --- | --- | +| `failproofai jev setup --mode off` | Config रखें; Jev को ask नहीं किया जाता। **यह वह switch है जो रहता है:** फिर से connecting एक मौजूदा `jev.json` को कभी rewrite नहीं करता, इसलिए Jev तब तक off रहता है जब तक आप इसे `--mode shadow` के साथ वापस switch नहीं करते। | +| `failproofai jev remove` | `~/.failproofai/jev.json` को delete करें; Jev off है — जब तक अगली `failproofai config --token` `jev:evaluate` carry करने वाली कुंजी के साथ नहीं, जो कोई `jev.json` नहीं find करती और shadow mode में Jev को चालू करती है (जब तक यह `--no-transcripts` के साथ नहीं चलता)। इसे off रखने के लिए, `--mode off` का उपयोग करें। | +| `failproofai config --disconnect` | मशीन को disconnect करें: कुंजी को remove किया जाता है, और `jev.json` भी जब यह FailproofAI Cloud को name करता है और switched off नहीं है। अपने endpoint के लिए एक `jev.json` रहता है, और एक switched off भी, इसलिए Jev off रहता है जब आप फिर से connect करते हैं। | + +अगली tool call से, hooks बिल्कुल पहले की तरह regex policies चलाते हैं। \ No newline at end of file diff --git a/docs/hi/policies/jev.mdx b/docs/hi/policies/jev.mdx new file mode 100644 index 000000000..1d032b216 --- /dev/null +++ b/docs/hi/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Jev की लाइव समीक्षा को गेटेड टूल कॉल में जोड़ें, फिर इसके निर्णयों को लागू करने से पहले निरीक्षण करें।" +icon: "shield-check" +--- + +Jev एक टूल कॉल को पढ़ता है कि व्यक्ति ने एजेंट को क्या करने के लिए कहा है। इसका उपयोग तब करें जब कोई स्ट्रिंग-मैचिंग policy वैध कार्य को ब्लॉक करे या कोई जोखिम भरी कार्रवाई को याद करे जिसे संदर्भ की आवश्यकता हो। यह `PreToolUse` या `PermissionRequest` गेट पर आपकी policies के साथ-साथ उत्तर देता है। एक सेशन समाप्त होने के **बाद** स्कोर के लिए, [Jev evaluations](/hi/evaluations/jev) का उपयोग करें। + +## observe मोड में शुरू करें + +Failproof AI को इंस्टॉल करें और hooks को एक [समर्थित harness](/hi/reference/harnesses) से जोड़ें। failproofai 1.0.8-beta.0 या बाद का उपयोग करें। + +Failproof AI कोई Jev चेक शिप नहीं करता। उन्हें एक पैक के रूप में इंस्टॉल करें, अन्यथा Jev के पास पूछने के लिए कुछ नहीं है और इसे कभी कॉल नहीं किया जाता: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +फिर चुनें कि अनुरोध Jev तक कैसे पहुंचते हैं: + +| Route | पहला कदम | +| --- | --- | +| FailproofAI Cloud | `jev:evaluate` ले जाने वाली एक **machine** key के साथ कनेक्ट करें। कोई Jev कॉन्फ़िगरेशन न होने वाली मशीन पर, `failproofai config` Jev को observe मोड में चालू करता है। | +| आपका अपना provider | स्थानीय डैशबोर्ड में, **Settings → Jev** खोलें, provider चुनें, इसका token पेस्ट करें, और **observe** चुनें। या `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key` चलाएं। | + +![स्थानीय डैशबोर्ड की Jev सेटिंग्स: provider, endpoint, token, और Jev को चालू करने से पहले observe मोड।](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` endpoint की जांच करता है। hook path की जांच करने के लिए, एक hooked एजेंट को `README.md` पर अपना फ़ाइल-पढ़ने वाला टूल उपयोग करने के लिए कहें। पुष्टि करें कि टूल कॉल सेशन में दिखाई देता है, फिर [स्थानीय डैशबोर्ड](/hi/reference/local-dashboard#review-policy-activity) में **Policies → Activity** का निरीक्षण करें। `status` में Jev count बढ़ना चाहिए। Observe मोड रिकॉर्ड करता है कि Jev ने क्या निर्णय लिया होता जबकि आपके मौजूदा policy result अभी भी लागू होते हैं। + +## तय करें कि कब लागू करना है + +एक **hard** policy हमेशा अंतिम निर्णय रखता है। Jev केवल एक policy से deny को साफ़ कर सकता है जिसे स्पष्ट रूप से **reviewable** चिह्नित किया गया है और केवल जब यह उस policy की नामित चिंता की जांच करे। clearance पर भरोसा करने से पहले [policy authority](/hi/policies/authority) देखें। Jev अपने आप पर भी चेतावनी दे सकता है या deny कर सकता है। यदि यह उत्तर नहीं दे सकता, तो policy result उस कॉल को तय करता है। + +एक बार observe के परिणाम सही दिखें, **Settings → Jev** में enforce मोड पर स्विच करें या चलाएं: + +```bash +failproofai jev setup --mode enforce +``` + +Provider URLs, Cloud keys, कॉन्फ़िगरेशन, fallbacks, और प्रत्येक अनुरोध के साथ भेजे गए डेटा के लिए, [Jev integration reference](/hi/reference/jev) देखें। \ No newline at end of file diff --git a/docs/hi/reference/custom-agents-typescript.mdx b/docs/hi/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..b4dec2836 --- /dev/null +++ b/docs/hi/reference/custom-agents-typescript.mdx @@ -0,0 +1,427 @@ +--- +title: "कस्टम एजेंट (TypeScript)" +description: "@failproofai/sdk के लिए कॉन्फ़िगरेशन, इवेंट कैटलॉग, स्कोप और फ्रेमवर्क एडेप्टर।" +icon: "square-js" +--- + +TypeScript SDK के लिए हर सेटिंग, मेथड और फील्ड क्या करता है। यदि आप पहली बार इंस्ट्रूमेंट कर रहे हैं, तो गाइड से शुरुआत करें — यह पेज चीजें देखने के लिए है। + + + + इंस्टॉल करें, इंस्ट्रूमेंट करें, इवेंट मेथड, एक काम किया हुआ उदाहरण, और सामान्य समस्याएं। + + + समान इवेंट, समान वायर फॉर्मेट, समान स्पूल — Python से। + + + +Node 20.9 या नया। ESM और CommonJS। कोई रनटाइम निर्भरता नहीं। + + + यह SDK और Python वाला **एक ही स्पूल में समान इवेंट लिखते हैं**। Node एजेंट और Python एजेंट वाली एक फ्लीट एक सेशन सेट बनाती है, दो नहीं, और डैशबोर्ड में कुछ भी उन्हें अलग नहीं करता। प्रति कंपनी नहीं, प्रति सेवा चुनें। + + +## इंस्टॉल करें + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +फ्रेमवर्क एडेप्टर पैकेज में ही भेज दिए जाते हैं। फ्रेमवर्क **वैकल्पिक पीयर निर्भरताएं** हैं — समर्थित श्रेणियां दिखाई देने के लिए घोषित, आपकी ओर से कभी इंस्टॉल नहीं किए जाते, और केवल तब आयात किए जाते हैं जब आप `instrument()` को कॉल करते हैं। + +## Failproof डेमन को कनेक्ट करें + +Python SDK के समान: **Admin → Keys** के अंतर्गत एक `events:add` की बनाएं, फिर [डेमन को कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) एजेंट मशीन पर। SDK डिस्क में लिखता है; डेमन भेज देता है। + +## कॉन्फ़िगरेशन + +### OpenTelemetry स्पैन (ऑप्ट इन) + +`npm install @opentelemetry/api @opentelemetry/sdk-trace-base` के साथ OpenTelemetry को अलग से इंस्टॉल करें। +फिर अपने प्रोवाइडर के प्रोसेसर में FailproofAI जोड़ें: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +एक मौजूदा प्रोवाइडर के लिए, इसके अन्य प्रोसेसर को एक ही सूची में रखें। जो प्रोवाइडर `addSpanProcessor` को उजागर करते हैं, उन्हें इसके बजाय `{ provider }` के रूप में पास किया जा सकता है। विकल्पों के बिना, सेटअप केवल तभी एक नया प्रोवाइडर पंजीकृत करता है यदि कोई प्रोवाइडर पहले से पंजीकृत नहीं है। +`OtelSpanExporter` को अपने स्वयं के प्रोसेसर के साथ सीधे भी उपयोग किया जा सकता है। + +निर्यात जुड़े हुए FailproofAI डेमन के माध्यम से जाते हैं; SDK कोई नेटवर्क अनुरोध भेजता नहीं है और न ही कुंजी या स्थानीय श्रोता की आवश्यकता है। एक एडमिन को [OpenTelemetry ingest](/hi/agenteye/opentelemetry) को सक्षम करने के लिए कहें। एक नंगा `instrument()` इस निर्यातक को सक्षम नहीं करता। `uninstrument("otel")` केवल अपने स्वयं के प्रोसेसर को अक्षम करता है। आपकी स्पैन विशेषताएं सामग्री कैप्चर को नियंत्रित करती हैं; निकास से पहले अपने प्रोवाइडर को फ्लश करें। +OpenTelemetry एक वैकल्पिक एप्लीकेशन निर्भरता रहता है, एक कठोर SDK निर्भरता नहीं। + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| विकल्प | यह क्या करता है | +| --- | --- | +| `environment` | हर इवेंट पर लेबल — `production`, `staging`, `prod-eu`। डिफ़ॉल्ट `dev` है। | +| `flushInterval` | टाइमर सेकंड में कितनी बार डिस्क में लिखता है। डिफ़ॉल्ट `0.5` है। | +| `baseDir` | कहां लिखें। डेमन के स्पूल को डिफ़ॉल्ट करता है, जो आप चाहते हैं जब तक आप अन्यथा जानते हैं। | + +कुछ भी लागू नहीं किया जाता जब तक यह सब मान्य न हो, इसलिए एक अस्वीकृत कॉल SDK को बिल्कुल वैसे ही छोड़ देता है जैसे यह था, नई `baseDir` और पुरानी अंतराल के साथ नहीं। + +इसके बजाय पर्यावरण चर द्वारा सेट करें: + +| चर | यह क्या करता है | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | कोड परिवर्तन के बिना `environment` सेट करता है। एक `configure()` विकल्प इसके ऊपर जीतता है। | +| `FAILPROOFAI_HOME` | Failproof AI रूट को स्थानांतरित करता है जो स्पूल रखता है। | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (डिफ़ॉल्ट), `error`, `silent`। | +| `FAILPROOFAI_SDK_STRICT` | `1` इंस्ट्रूमेंटेशन त्रुटियों को लॉग किए जाने के बजाय फेंकने के लिए बनाता है। | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` फ्रेमवर्क-संगतता समस्या को चेतावनी देने और जारी रखने के बजाय फेंकने के लिए बनाता है। | + + + **`environment` में कोई अल्पविराम नहीं।** इनजेस्ट उस फील्ड को अल्पविराम पर विभाजित करता है अपने फिल्टर बनाने के लिए, और किसी भी इवेंट को छोड़ देता है जिसमें एक है — इसलिए एक पूरा रन चुप चाप गायब हो जाता है। `prod,eu` नहीं, `prod-eu` लिखें। + + `configure({ environment: "prod,eu" })` फेंकता है ताकि आप तुरंत पता लगें। `AGENTEYE_ENVIRONMENT` नहीं फेंक सकता — कोई आपको कॉल नहीं कर रहा — तो यह एक बार चेतावनी देता है और `dev` पर गिर जाता है। + + +`failproofai.setLogger({ debug, info, warn, error })` के साथ SDK की अपनी लॉग लाइनों को अपने लॉगर में भेजें। + +## शटडाउन + +बफर किए गए इवेंट `process.on("exit")` पर फ्लश किए जाते हैं। + +एक सिग्नल द्वारा मार दी गई प्रक्रिया कभी वहां तक नहीं पहुंचती है, और `SIGTERM` के लिए Node की डिफ़ॉल्ट निकास हैंडलर के बिना समाप्त करना है — इसलिए एक कंटेनरीकृत एजेंट जो भी अंतिम अंतराल में नहीं लिखा गया था उससे गुम हो जाता है। + + + **यह SDK आपके लिए सिग्नल हैंडलर इंस्टॉल नहीं करेगा।** एक को पंजीकृत करना आपकी प्रक्रिया के व्यवहार को बदलता है: एक श्रोता Node की डिफ़ॉल्ट समाप्ति को दबाता है, इसलिए एक लाइब्रेरी जो एक जोड़ता था चुप चाप Ctrl-C को काम करने से बंद कर देगा। अपना स्वयं का जोड़ें: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +एक अल्पकालिक स्क्रिप्ट या सर्वरलेस हैंडलर को लौटने से पहले `await failproofai.flush()` करना चाहिए — अंतराल अकेले डिलीवरी की गारंटी नहीं देता है। + +## पहचान + +हर इवेंट एक सेशन और एक एजेंट से संबंधित है। **स्कोप दोनों को भर देते हैं**, तो आप शायद ही कभी उन्हें पास करते हैं: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +`sessionId` या `agentId` को स्पष्ट रूप से पास करना अभी भी काम करता है और जीतता है। न बंधे और न पास किए जाने के साथ, कॉल फेंकता है बजाय एक इवेंट उत्सर्जित करने के जो Cloud चुप चाप त्याग देगा। + + + पहचान `AsyncLocalStorage` पर सवारी करती है। यह `await`, `.then()`, टाइमर और स्कोप के अंदर बनाए गए किसी भी कॉलबैक को अनुसरण करता है। यह एक रन के दौरान संग्रहीत और दूसरे के दौरान आमंत्रित कॉलबैक को अनुसरण **नहीं** करता है, या `worker_threads` सीमा के पार हाथ किए गए काम को — उन्हें `failproofai.propagate()` में लपेटें या उनके इवेंट अलग-थलग रहते हैं। + + +### स्कोप + +| स्कोप | उत्सर्जित करता है | लौटाता है | +| --- | --- | --- | +| `session(body)` | कुछ नहीं — केवल पहचान | जो `body` लौटाता है | +| `agent(id, options?, body)` | `agent_start`, फिर `agent_end` | जो `body` लौटाता है | +| `toolCall(name, options?, body)` | `tool_use`, फिर `tool_result` | जो `body` लौटाता है | + +एक सिंक्रोनस बॉडी सिंक्रोनस रहती है: `agent("x", () => 1)` `1` लौटाता है, एक प्रॉमिस नहीं। + +`toolCall` बॉडी के हल किए गए मूल्य को टूल के `output` के रूप में रिकॉर्ड करता है, जब तक आप `call.output` को स्वयं असाइन नहीं करते। + + + +| क्या हुआ | इवेंट | `outcome` | +| --- | --- | --- | +| ब्लॉक वापस आया | `agent_end` | `"success"`, या आपका `outcome` | +| ब्लॉक फेंका गया | `error`, फिर `agent_end` | `"failed"` | +| एक `AbortError` | केवल `agent_end` | `"cancelled"` | + +त्रुटि हमेशा फिर से फेंकी जाती है। + +एक टूल विफलता पत्ती पर रिकॉर्ड की जाती है — `tool_result` एक `error` स्ट्रिंग के साथ — और कोई भी रन-स्तर `error` इवेंट **नहीं** उत्सर्जित करता है। एक जो एजेंट लूप पकड़ता है वह एक रन विफलता नहीं है, और एक जो प्रचार करता है वह बिल्कुल एक बार रिपोर्ट किया जाता है, संलग्न `agent()` द्वारा। + + + + + +जब काम एक एकल फंक्शन नहीं है — एक स्कोप एक निर्माता में खोला गया और एक टियरडाउन में बंद, या एक जो मौजूदा नियंत्रण प्रवाह को फैलाता है: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, फिर agent_end +``` + +दोनों फॉर्म बाइट-समान इवेंट उत्सर्जित करते हैं। कॉलबैक फॉर्म को प्राथमिकता दें: यह `AsyncLocalStorage.run()` के अंदर चलता है, इसलिए कुछ भी अनवाइंड करने के लिए कुछ नहीं है और "यहां खोला, वहां बंद" बग का पूरा वर्ग अप्राप्य है। + +एक `using` ब्लॉक जो अपनी अपनी विफलता को पकड़ता है, इसे `span.fail(error)` के साथ रिपोर्ट करता है — डिस्पोजर के पास अपना अपवाद चैनल नहीं है। + + + +## इवेंट कैटलॉग + +Python SDK के समान पंद्रह मेथड, camelCase में। अधिकांश **जोड़े में** आते हैं — आप ओपनर को कॉल करते हैं, फिर क्लोजर, और SDK अंतराल को समय देता है। + +| | खोलता है | बंद करता है | +| --- | --- | --- | +| **एजेंट** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **मॉडल** | `modelRequest` | `modelResponse` | +| **टूल** | `toolUse` | `toolResult` | +| **हुक** | `hookTriggered` | `hookCompleted` | +| **मानव** | `humanWait` | `humanInput` | + +तीन अकेले खड़े हैं: `error`, `humanPause`, `humanInterrupt`। + + + +हर मेथड `sessionId` और `agentId` भी लेता है, जो स्कोप आपके लिए भर देते हैं। कुछ भी छोड़ा हुआ JSON `null` के रूप में भेजे जाने के बजाय गिरा दिया जाता है। + +| मेथड | आवश्यक | वैकल्पिक | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +कोई भी अन्य कुंजी जो आप जोड़ते हैं एक कस्टम पेलोड फील्ड बन जाती है। कुछ भी फ्रेमवर्क-विशिष्ट `fw_*` को नेमस्पेस करें; एक नाम जो एक घोषित फील्ड के साथ टकराता है चुप चाप एक प्रचारित कॉलम को अधिलेखित करने के बजाय अस्वीकार कर दिया जाता है। + + + + + **`duration_ms` गणना की जाती है, स्वीकार नहीं की जाती है।** चार बंद करने वाले मेथड अपने ओपनर से अंतराल को समय देते हैं और एक कॉलर-आपूर्ति `duration_ms` को अस्वीकार करते हैं — एक रिपोर्ट किया गया अवधि अस्वीकार्य है। + + जोड़े **सेशन** पर मिलाए जाते हैं और आईडी, एजेंट पर कभी नहीं। एक टूल `planner` के अंतर्गत खोला गया और `worker` के अंतर्गत बंद किया गया अभी भी जोड़ता है, जो नेस्टेड बहु-एजेंट रन वास्तव में क्या करते हैं। + + +## फ्रेमवर्क एडेप्टर + +```ts +await failproofai.instrument(); // जो कुछ भी यह पा सकता है +await failproofai.instrument("langchain"); // ठीक एक +failproofai.uninstrument(); // सब कुछ वापस डालें +``` + +| फ्रेमवर्क | समर्थित | यह कैसे संलग्न करता है | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, तो हर `invoke`/`stream`/`batch` कहीं भी `callbacks:` पास किए बिना कवर किया जाता है — या `langchainHandler()` को स्वयं पास करें और कुछ भी पैच न करें। | +| **Vercel AI SDK** | `ai` 4 – 7 | कॉल साइट पर `telemetry()`, या `ai` 7 पर संपूर्ण प्रक्रिया के लिए `instrument("ai")` (4–6 पर जो ऑप्ट-इन है — नीचे देखें)। | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, एजेंट के मॉडल और टूल संकल्प, और वर्कफ़्लो रन/स्टेप इंजन। | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (सब्सक्राइब किया गया) प्लस `AgentWorkflow.runStream`, वर्कफ़्लो रन और उनके चरणों के लिए। | + +हर श्रेणी वास्तविक फ्रेमवर्क रिलीज के विरुद्ध परीक्षण किया जाता है, दोनों सिरों पर, ES मॉड्यूल और CommonJS के रूप में, हर CI चलाने पर। + +मैपिंग Python SDK की है, तो समान प्रोग्राम या तो भाषा में समान ट्री खींचता है। एक निर्माण **एजेंट** है केवल यदि यह LLM निर्णय लूप के मालिक है — एक ग्राफ या चेन रन, AI SDK `generateText`/`streamText` कॉल, Mastra एजेंट, LlamaIndex एजेंट रन। एक LangGraph नोड या वर्कफ़्लो स्टेप एक **हुक** है (`hook_triggered`/`hook_completed`), कभी भी नेस्टेड एजेंट नहीं। मॉडल कॉल `model_request`/`model_response` जोड़े हैं टोकन गणना के साथ; टूल कॉल मॉडल के अपने टूल कॉल आईडी ले जाते हैं। एक विफलता पत्ती पर एक बार रिकॉर्ड की जाती है — जहां यह हुआ। + +एक एडेप्टर जो इंस्टॉल नहीं हो सकता है लॉग किया जाता है और छोड़ दिया जाता है; अन्य अभी भी इंस्टॉल करते हैं, क्योंकि एक टूटा हुआ LlamaIndex आपको LangGraph की कीमत नहीं देना चाहिए। + + + कोई तर्क के साथ `instrument()` एक फ्रेमवर्क का पता लगाता है कि क्या यह पहले से ही **आयात** किया गया है, की बजाय क्या यह **हल करता है** — Node ES मॉड्यूल के लिए Python के `sys.modules` के बराबर उजागर करता है। एक फ्रेमवर्क जो आपने इंस्टॉल किया है लेकिन उपयोग नहीं करते हैं आयात और पैच किया जाएगा। नाम करें जो आप चाहते हैं यदि वह मायने रखता है। + + + + इनमें से अधिकांश फ्रेमवर्क ES-मॉड्यूल बिल्ड और CommonJS बिल्ड भेज देते हैं, जो Node दो असंबंधित प्रतियों के रूप में लोड करता है। एडेप्टर आपके एप्लीकेशन लोड की प्रति को पैच करते हैं (और CommonJS प्रति भी अगर कुछ पहले से ही `require` किया है), तो दोनों मॉड्यूल सिस्टम काम करते हैं। एक फ्रेमवर्क **आपके अपने आउटपुट में बंडल किया गया** esbuild या webpack द्वारा पहुंच से बाहर है — कॉल-साइट सहायकों को वहां उपयोग करें: `langchainHandler()`, `telemetry()`, `wrapTool()`। + + +### LangChain बिना पैच किए + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +हैंडलर `instrument()` के साथ या बिना काम करता है और कभी भी दोहरा-रिकॉर्ड नहीं करता। `instrument("langchain")` `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` और `captureLimit` लेता है, जैसा कि Python एडेप्टर करता है; `metadata: { failproofai_sdk_session_id }` एक कॉल पर उस आमंत्रण के लिए सेशन चुनता है। + +### Vercel AI SDK + +AI SDK ES मॉड्यूल से सादे फंक्शन निर्यात करता है, और ES मॉड्यूल नेमस्पेस विशेषज्ञता द्वारा अपरिवर्तनीय है — पैच करने के लिए कहीं नहीं है। यह SDK स्वयं दस्तावेजों को बढ़ाने के बिंदु का उपयोग करता है: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // ai 7 पर, `telemetry: telemetry({ … })` — समान वस्तु, नया नाम +}); +``` + +यह संपूर्ण एकीकरण है: एक एजेंट स्पैन, टोकन गणना के साथ प्रति चरण एक मॉडल अनुरोध/प्रतिक्रिया जोड़ी, और हर टूल कॉल। एक कॉल साइट हर प्रमुख पर काम करता है — `ai` 4–6 ट्रेसर को ले जाता है, `ai` 7 टेलीमेट्री एकीकरण को। + +`instrument("ai")` `ai` 7 पर समान प्रक्रिया-व्यापी करता है: हर कॉल, AI SDK की वैश्विक टेलीमेट्री-एकीकरण सूची के माध्यम से, जो योगात्मक है और किसी और से कुछ नहीं लेता है। + +**`ai` 4–6 पर, `instrument("ai")` स्वयं द्वारा कुछ भी रिकॉर्ड नहीं करता है, और एक चेतावनी लॉग करता है कि ऐसा है।** केवल एकमात्र प्रक्रिया-व्यापी हुक जो इन प्रमुखों के पास है वह वैश्विक OpenTelemetry ट्रेसर प्रदाता है — एक एकल स्लॉट OpenTelemetry हाथ से इनकार करता है एक बार लिया। हमारे को पंजीकृत करना बाद में आपके स्वयं के `NodeSDK.start()` को चुप चाप अस्वीकार करेगा और आपके http/डेटाबेस स्पैन को एक ट्रेसर को भेजेगा जो कुछ भी निर्यात नहीं करता है। कॉल साइट पर `telemetry()` का उपयोग करें या `wrapModel` वहां। यदि प्रक्रिया अपने स्वयं के OpenTelemetry को चलाती नहीं है, `instrument("ai", { registerGlobalTracer: true })` के साथ ऑप्ट इन करें: यह तब हर कॉल रिकॉर्ड करता है जो `experimental_telemetry: { isEnabled: true }` को पास करता है, और केवल स्लॉट लेता है यदि यह अभी भी खाली है। `registerGlobalTracer: false` डिफ़ॉल्ट रखता है और चेतावनी को चुप कर देता है। + +यदि आप मॉडल को एक बार लपेटना पसंद करेंगे, `wrapModel` केवल मॉडल कॉल देखता है, क्योंकि टूल कॉल मॉडल परत के ऊपर होते हैं। एक लपेटा हुआ मॉडल इसके चारों ओर कुछ भी नहीं के साथ कहा जाता है अपने स्वयं के रन के रूप में दर्ज किया जाता है। एक स्ट्रीमेड कॉल बंद करता है हालांकि स्ट्रीम बंद करता है — `stop_reason: "cancelled"` जब उपभोक्ता इसे रद्द करता है, `"error"` त्रुटि के साथ जब यह आधे रास्ते में विफल हो जाता है: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +दोनों का उपयोग ठीक है: मिडलवेयर नोटिस करता है कि कॉल पहले से ही रिकॉर्ड किया जा रहा है और आगे बढ़ता है, इसलिए हर कॉल एक बार रिकॉर्ड किया जाता है। + +`functionId` एजेंट स्पैन का नाम देता है। इसे कम-कार्डिनैलिटी रखें — यह `agent_id` में उतरता है, प्राथमिक डैशबोर्ड पहलू। + +### Next.js + +`next build` डिफ़ॉल्ट रूप से आपके सर्वर की निर्भरताओं को बंडल करता है, और एक फ्रेमवर्क बिल्ड में बंडल किया गया एक प्रति है `instrument()` नहीं पहुंच सकता। कॉन्फ़िग को एक बार लपेटें और Next के स्टार्टअप हुक से `instrument()` को कॉल करें: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* आपका कॉन्फ़िग */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` LangChain, Mastra, LlamaIndex और SDK को स्वयं `serverExternalPackages` में जोड़ता है, आपकी अपनी सूची को रखता है। इसके बिना, `instrument()` प्रति फ्रेमवर्क एक बार चेतावनी देता है यह नहीं पहुंच सकता बजाय चुप विफलता के; यदि आप पैकेजों को स्वयं सूचीबद्ध करते हैं, `FAILPROOFAI_NEXT_EXTERNALS=1` सेट करें। Vercel AI SDK और कॉल-साइट सहायक दोनों तरह से काम करते हैं। एक Edge रूट एक नो-ऑप बिल्ड हो जाता है: SDK को आयात करना सुरक्षित है और कुछ भी रिकॉर्ड नहीं करता है। + +### स्ट्रीमेड कॉल पर टोकन गणना + +OpenAI-संगत API केवल तब उपयोग की रिपोर्ट करते हैं जब क्लाइंट पूछता है। LangChain और Vercel AI SDK पूछते हैं; LlamaIndex के लिए `additionalChatOptions: { stream_options: { include_usage: true } }` को इसके `OpenAI` LLM पास करें, और Mastra के लिए उपयोग सक्षम के साथ मॉडल बनाएं (उदाहरण के लिए `createOpenAICompatible({ includeUsage: true })`)। अन्यथा स्ट्रीमेड मॉडल कॉल कोई टोकन गणना नहीं ले जाते हैं। + +### रनटाइम + +Node ≥ 20.9, Bun और Deno — हर फ्रेमवर्क, ES मॉड्यूल और CommonJS के रूप में, Node के ट्रेस के विरुद्ध हर पर परीक्षण किया जाता है। SDK `failproofaid` डेमन के बगल में चलता है, जो जो लिखता है उसे भेज देता है। + +## आपका अपना एजेंट — कोई फ्रेमवर्क नहीं + +एक एजेंट लूप जो आपने स्वयं लिखा है, या एक फ्रेमवर्क बिना एडेप्टर के। आप एडेप्टर के नीचे समान API के साथ इवेंट उत्सर्जित करते हैं, तो ट्रेस का आकार और गुणवत्ता समान है। + +आपको यह जानने की जरूरत नहीं है कि एजेंट कैसे आयोजित है। हर हाथ से बनाया गया एजेंट पहले से ही तीन जगह है, जो भी उसके फंक्शन कहे जाते हैं, और वे तीन पूरे एकीकरण हैं: + +| कहां | क्या जोड़ें | उत्सर्जित करता है | +| --- | --- | --- | +| जहां **एक रन** शुरू और समाप्त होता है | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **एक फंक्शन जो मॉडल को कॉल करता है** | `event.modelRequest` पहले, `event.modelResponse` बाद में — दोनों हिस्से, विफलता पर भी | प्रति मॉडल बारी एक जोड़ी | +| **एक फंक्शन जो टूल चलाता है** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +पहचान परिवेशीय है: `agent()` के अंदर सब कुछ एक आईडी लिए बिना उस रन के सेशन पर उतरता है, और प्रोग्राम में और कुछ नहीं बदलता है — जो कुछ भी एजेंट पहले से ही अपने अपने डेटाबेस में लिखता है। + +- **एक सेवा या एक कार्यकर्ता:** अपने अपनी अनुरोध या नौकरी आईडी को `sessionId` के रूप में पास करें, तो डैशबोर्ड पर एक सेशन और आपके अपने लॉग या डेटाबेस में रिकॉर्ड एक ही स्ट्रिंग हैं। +- **उप-एजेंट:** `agent()` कॉल नेस्ट करें। आंतरिक एक बाहरी के साथ सेशन में शामिल हो जाता है जैसा कि इसका `parent_id`। +- **जोड़ी उत्सर्जित करें।** एक `modelRequest` कोई `modelResponse` के साथ एक स्पैन है डैशबोर्ड हमेशा के लिए चलता दिखाता है — इसलिए `catch`। + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) रिपोजिटरी में संपूर्ण, रनेबल संस्करण है: एक वास्तविक OpenAI टूल लूप बिल्कुल इसी तरह इंस्ट्रूमेंट किया गया, CI में हर परिवर्तन के रूप में चलाया गया ES मॉड्यूल और CommonJS के रूप में। + +## मूल्यांकन + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +प्रोटोकॉल, कार्यकर्ता सेटिंग और परिणाम प्रकारों के लिए [Evaluator SDK संदर्भ](/hi/reference/evaluator-sdk) देखें। + + + **एक मूल्यांकन उपज देना चाहिए।** एक सिंक्रोनस फंक्शन जो कभी लौटता नहीं है Node के पास एक एकल थ्रेड को ब्लॉक करता है, और कोई टाइमआउट नहीं है जब ऐसा होता है। `async` मूल्यांकन लिखें। + + +## यह आपकी प्रक्रिया के लिए क्या नहीं करेगा + +| | | +| --- | --- | +| **आपके एजेंट लूप को ब्लॉक करें** | इवेंट एक इन-मेमोरी कतार में जाते हैं; एक टाइमर उन्हें लिखता है। टाइमर `unref`'d है, तो इस पैकेज को आयात करने से कभी भी एक स्क्रिप्ट निकल जाती है। | +| **बंधन के बिना बढ़ें** | कतार को गिनती **और** मापा गया बाइट द्वारा सीमित है। या तो पिछले, सबसे पुराने इवेंट त्यागे जाते हैं और एक चेतावनी कहती है — एक टेलीमेट्री आउटेज OOM मार बन नहीं सकता। | +| **प्रक्रिया को नीचे ले जाएं** | एक अनकोडेबल इवेंट अकेले गिरा दिया जाता है, इसके चारों ओर बैच नहीं। एक फेंकने वाला गेटर, एक वृत्ताकार संदर्भ, एक `BigInt`, एक अकेला सरोगेट: प्रत्येक हैंडल किया जाता है न कि प्रचारित। | +| **आधी-लिखी गई बैच छोड़ें** | सामग्री `fsync`ed है एक परमाणु नाम बदलने से पहले, निर्देशिका के बाद `fsync`ed है, और एक विफल लिखना अपनी अस्थायी फाइल को साफ करता है। | +| **पारदर्शी छोड़ दें** | बैच `0700` निर्देशिका के अंदर `0600` हैं। वे लक्ष्य, प्रॉम्प्ट, टूल तर्क और टूल आउटपुट ले जाते हैं। | +| **साख भेजें** | API कुंजी, टोकन, JWT, असर हेडर और गुप्त-आकार असाइनमेंट डिस्क तक पहुंचने से पहले संपादित किए जाते हैं। डेमन अपलोड से पहले फिर से संपादित करता है। | \ No newline at end of file diff --git a/docs/hi/reference/custom-agents.mdx b/docs/hi/reference/custom-agents.mdx index 0ee8165a6..ef98376f4 100644 --- a/docs/hi/reference/custom-agents.mdx +++ b/docs/hi/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -Python 3.10 या नया। कोई runtime dependency नहीं। +Python 3.11 या नया। कोई runtime dependency नहीं। ## इंस्टॉल करें diff --git a/docs/hi/reference/jev-cloud.mdx b/docs/hi/reference/jev-cloud.mdx new file mode 100644 index 000000000..be2c06528 --- /dev/null +++ b/docs/hi/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "FailproofAI Cloud के माध्यम से Jev" +description: "Cloud machine keys, connection state, limits, और live Jev policy review के लिए failure behavior।" +icon: "cloud" +--- + +यह [Jev policies](/hi/policies/jev) के लिए Cloud route reference है। Jev, TypeSafe का classifier, प्रत्येक tool call को आपके द्वारा वास्तव में मांगे गए चीज़ के विरुद्ध पढ़ता है और आपकी policies के साथ उत्तर देता है, उनकी बजाय कभी नहीं। **FailproofAI Cloud** के माध्यम से, एक connected machine उसी key के साथ Jev का उपयोग करता है जिससे यह पहले से जुड़ा हुआ है: कोई TypeSafe account नहीं, कोई दूसरी key नहीं, कोई endpoint configure करने के लिए नहीं। प्रत्येक call को आपकी organization की existing plan allowance में चार्ज किया जाता है। + +Jev जो कुछ भी करता है वह [bring-your-own-key setup](/hi/reference/jev-providers) से अपरिवर्तित है: hard policies अंतिम रहते हैं, एक reviewable policy का deny केवल तब clear होता है जब Jev से बिल्कुल उसी concern के बारे में पूछा जाता है, और कोई भी failure उस call के लिए regex result पर वापस आता है। + + +**failproofai 1.0.8-beta.0** या बाद में की आवश्यकता है। 1.0.7 में कोई Jev नहीं है, भले ही यह 1.0.7 betas के ऊपर sort हो। बिना Jev config के कुछ नहीं बदलता है: hooks बिल्कुल वैसे ही regex policies चलाते हैं जैसे पहले करते थे। + + +## शुरुआत से पहले + +FailproofAI को उस machine पर install करें जहाँ आपका agent चलता है और इसके hooks को एक [supported harness](/hi/reference/harnesses) से attach करें। यदि आप शुरुआत से शुरू कर रहे हैं, तो hook installation के माध्यम से [quickstart](/hi/start/quickstart) का पालन करें। `failproofai --version` के साथ installed CLI की जांच करें; यदि यह Jev से पहले का है तो इसे update करें। आपको अपनी organization के **Administration → Keys** page तक पहुँचने की भी आवश्यकता है machine key बनाने के लिए। + +Jev named tool calls की `PreToolUse` या `PermissionRequest` gate पर review करता है। यह session के हर event की review नहीं करता। Jev को policy deny को clear करते देखने के लिए, आपको एक installed policy की आवश्यकता है जो [reviewable](/hi/policies/authority) के रूप में चिह्नित हो; अन्य सभी policy denies अंतिम रहते हैं। + +## इसे चालू करें + +1. **Jev के साथ एक key बनाएं।** FailproofAI Cloud dashboard में, **Administration → Keys → Create key** खोलें और **machine** preset चुनें। यह तीन permissions देता है जो एक machine को चाहिए: `events:add` (activity भेजें), `policies:pull` (policies प्राप्त करें) और `jev:evaluate` (Jev, आपकी organization की plan में चार्ज किया जाएगा)। एक key बिना दूसरे दोनों के `jev:evaluate` नहीं ले सकता। +2. **उस key के साथ machine को connect करें।** एक prompt पर इसका one-time secret पढ़ें, फिर पूरा setup command चलाएं: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` daemon को install करता है, उन agent CLIs के लिए hooks को attach करता है जो वह पाता है, और machine को connect करता है। environment variable key को command के arguments और आपकी shell history से बाहर रखता है। यदि आपका harness बाद में install किया गया था, तो [इसे explicitly attach करें](/hi/start/quickstart)। + + यदि आपकी organization अपना स्वयं का FailproofAI Cloud चलाती है hosted के बजाय, इसका address जोड़ें: `--url https://` (या `FAILPROOFAI_CLOUD_URL` export करें)। इसके बिना key को hosted service के विरुद्ध check किया जाता है और connection fail हो जाता है। यदि उस host का certificate एक private CA से आता है, तो CA को machine के system trust store में install करें (उदाहरण के लिए `update-ca-certificates` के साथ), केवल `NODE_EXTRA_CA_CERTS` में नहीं: daemon जो events भेजता है और policies pull करता है system store को read करता है। [Troubleshooting](/hi/reference/troubleshooting) देखें। + +बस इतना ही। Connecting key को store करता है और, जब machine के पास **अभी तक** कोई Jev config नहीं है, FailproofAI Cloud के लिए एक लिखता है। machine के पहले deployment से (लगभग 30 s के अंदर) FailproofAI Cloud mode set करता है: `enforce` जब एक Jev policy इसे deploy किया जाता है, `off` जब कोई नहीं (see [Who sets the mode](#who-sets-the-mode))। output ऐसा कहता है: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Checks जो FailproofAI Cloud deploy करता है Cloud पर चलते हैं। machine पर अपने checks जोड़ने के लिए, एक pack install करें: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**`--no-transcripts` के साथ**, connecting Jev को चालू नहीं करता। Jev प्रत्येक checked tool call और recent prompt को FailproofAI Cloud भेजता है, जो एक decisions-only connection जिससे भेजने के लिए कहा गया था उससे अधिक है। key अभी भी stored है, और output कहता है Jev उपलब्ध है और इसे चालू कैसे करें: + +```bash +failproofai jev setup --provider failproofai +``` + +यह FailproofAI Cloud के माध्यम से Jev को **off** भी करता है। एक `jev.json` जो FailproofAI Cloud के माध्यम से Jev चलाता है (transcripts on के साथ earlier connection से बचा हुआ) removed है, उसी rule द्वारा `config --disconnect` uses करता है, और output कहता है Jev via FailproofAI Cloud इस machine पर off रहता है। आपके स्वयं के Jev endpoint के लिए एक `jev.json` जैसे है छोड़ा जाता है, और एक FailproofAI Cloud है जिसे आपने off किया है (`--mode off`)। + + +Connecting **कभी भी overwrite नहीं करता** एक existing `~/.failproofai/jev.json`। यदि आप पहले से अपना स्वयं का Jev endpoint उपयोग करते हैं, तो यह continue किया जाता है, और output कहता है कि file configured के रूप में छोड़ा गया था — और, जब वह file Jev को off रखता है (refused, या switched off), तो ऐसा कहता है और इसे कैसे fix करें। उस machine को FailproofAI Cloud पर switch करने के लिए, `failproofai jev setup --provider failproofai` चलाएं। + + +## Mode को कौन set करता है + +एक machine पर FailproofAI Cloud से connected, **FailproofAI Cloud Jev mode set करता है**; machine पर कुछ नहीं करता: + +- `enforce` जब कोई भी Jev (या regex + Jev) policy machine को deploy किया जाता है: एक agent से हर checked tool call जो उन policies में से एक को target करता है FailproofAI Cloud को जाता है, जो अपने checks को उन checks के साथ पूछता है जो वहाँ installed packs में हैं। एक agent से call जो कोई Cloud Jev policy target नहीं करता, अपना कोई pack check नहीं है, बिल्कुल भी send नहीं किया जाता। `enforce` में, Jev की अपनी deny checks calls को block करते हैं साथ ही regex verdicts को clear करते हैं जो वे review करते हैं। +- `off` जब कोई नहीं है: कोई Jev नहीं, चाहे `jev.json` क्या कहे। + +एक Jev policy को कार्य करने से पहले try करने के लिए, इसे effect **observe** के साथ deploy करें: इसके checks अभी भी पूछे जाते हैं, और जो वे करते होते उसे policy page पर एक **would-have** के रूप में recorded किया जाता है, लेकिन यह कभी call को block नहीं करता और कभी एक को clear नहीं करता। `failproofai jev setup --mode` और dashboard के **Settings → Jev** कहते हैं कि mode FailproofAI Cloud द्वारा managed है और कुछ नहीं बदलता। `jev.json` Cloud के checks के लिए उपयोग नहीं किया जाता, भले ही यह दूसरे provider को नाम दे। `failproofai config --disconnect` Jev को machine के अपने `jev.json` को वापस करता है। + +`failproofai jev status` तब कहता है `Jev checks run on FailproofAI Cloud (mode: enforce)`। यह उन checks का भी नाम देता है जो हर `both` policy को review करते हैं। fleet page दिखाता है कि mode के साथ एक machine क्यों नहीं पूछ सकता: + +- `transcripts_disabled`: machine `--no-transcripts` के साथ connected था, जो कभी Jev को चालू नहीं करता। +- `jev_unconfigured`: machine की key `jev:evaluate` नहीं carries करती। +- `jev_rate_limited`: FailproofAI Cloud ने organization की Jev rate limit के लिए machine के कुछ calls को refuse किया, और उन calls को regex policies अकेले decide किया। +- `jev_unavailable`: row में कई calls fail हुई हैं, इसलिए machine एक समय में एक मिनट के लिए FailproofAI Cloud के Jev को skip करता है। यह अपने आप retry करता है। + +यदि FailproofAI Cloud 5 सेकंड के अंदर answer नहीं देता, तो regex policies अकेले decide करते हैं, किसी भी Jev outage के लिए। row में 3 failures के बाद machine एक समय में एक मिनट के लिए पूछना बंद करता है, इसलिए एक Cloud outage हर tool call को slow नहीं करता। + +एक session pause (`failproofai config --pause`) FailproofAI Cloud के Jev checks को नहीं रोकता, जैसे यह Cloud-managed policies को नहीं रोकता। यह machine पर installed packs के Jev checks को pause करता है। + +## यह क्या कर रहा है इसकी जांच करें + +```bash +failproofai jev status +failproofai jev test +``` + +`status` provider को **FailproofAI Cloud** के रूप में दिखाता है, Cloud host जिससे machine connected है, mode, और key source को **FailproofAI Cloud connection** के रूप में, कभी key नहीं। जब एक FailproofAI Cloud `jev.json` place में है लेकिन Jev नहीं चल सकता, यह कहता है क्यों: + +| `status` कहता है | `status --json` | मतलब | +| --- | --- | --- | +| **off — इस machine के FailproofAI Cloud connection के लिए कोई Jev key store नहीं है** | `key-lacks-jev` | Machine connected है, लेकिन इसके लिए कोई Jev key store नहीं है: key में `jev:evaluate` नहीं है, या connect इसकी confirm नहीं कर सका। `FAILPROOFAI_CLOUD_TOKEN` में key के साथ `failproofai config` फिर से चलाएं; यदि इसमें permission नहीं है, तो एक **machine** key का उपयोग करें। | +| **off — यह machine FailproofAI Cloud से connected नहीं है** | `not-connected` | इस machine पर कोई FailproofAI Cloud connection नहीं है जिससे Jev key belong हो। | + +`failproofai config --disconnect` के बाद कोई FailproofAI Cloud `jev.json` नहीं रहता है (जब तक कि यह switched off न हो, जो kept है), तो `status` बस Jev को off के रूप में report करता है। `status --json` same facts carry करता है (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), जब भी config absent या refused है। `permissions` हमेशा `jev.json` का है; `credentials.json` के बारे में एक refusal `credentialsPermissions` add करता है, और `fix` जब एक command इसे fix करे। `test` एक live request भेजता है और इसकी latency और Jev version जो answered करता है report करता है। यह 1 exit करता है, और अपने title में कहता है, जब answer hook timeout के बाद पहुँचता है (hooks `timeout` record करते) या इसके check question का गलत answer देता है। + +Dashboard के **Settings → Jev** panel भी **FailproofAI Cloud connection** दिखाता है: कौन सी organization machine report करती है और क्या इसकी key Jev carries करती है। यह machine की अपनी files से read है, कोई network call के साथ नहीं। + +## एक real call verify करें + +hooked agent में एक नया session शुरू करें। इसे `README.md` पर अपनी file-reading tool का उपयोग करने के लिए कहें और title report करें। confirm करें कि session में वह tool call है, फिर `failproofai jev status` फिर से चलाएं: इसके recent evaluated-call count में increase होना चाहिए। [local dashboard](/hi/reference/local-dashboard#review-policy-activity) में **Policies → Activity** खोलें उस call के Jev verdict और mode inspect करने के लिए। Cloud में, organization के **Policies** page delivered activity के लिए Jev outcomes दिखाता है। observe mode में, verdict एक **would-have** के रूप में recorded है और policy result अभी भी call decide करता है। एक clearance तब appear होता है जब एक reviewable policy matched और Jev ने इसके named checks को clear किया। + +## क्या policy page तक पहुँचता है + +Machine पहले से अपनी hook activity को FailproofAI Cloud (`events:add`) भेजता है। Jev on के साथ, हर gated call का record भी कहता है कि कौन सा evaluator चला, Jev ने क्या decide किया, इसने कौन सी policies को clear किया, कब इसने fallback लिया इसकी latency और वह model जो answered था — decisions, codes और names, कभी command या आपका prompt नहीं। आपकी organization के **Policies** page पर: + +- एक call जो Jev के अपने verdict ने decide किया (enforce mode) **Jev** को attribute किया जाता है, और जब deciding check एक pack से आया, record भी उस pack और इसके version को नाम देता है; +- observe mode में, Jev का deny या warning एक **would-have** के रूप में appear होता है, rollouts के बगल में जो आप observe कर रहे हैं; +- policies जो Jev ने clear किए, या observe mode में clear करते होते, प्रत्येक policy के लिए count किए जाते हैं। +- एक decision जो Jev ने part लिया (एक block, एक warning, एक clear, या observe mode में एक would-have) प्रत्येक check को list करता है जो उसने पूछा और वह check क्या concluded: verdict, क्यों (`not-detected`, `exempt`, `fired`, `op-requested`, …), इसका evidence `p`, `exempt` answer और हर probe का answer। एक policy का check जो watch के लिए deployed है (observe) भी listed है, marked watched; यह कभी block नहीं करता। Jev probabilities के साथ answers देता है, prose नहीं, इसलिए कोई free-text reason नहीं है। Plain allows roll up counts में और यह list carry नहीं करते। + +## जब Jev answer नहीं दे सकता + +इनमें से हर एक उस call के लिए आपकी policies के result पर fallback करता है, और अपने reason के साथ recorded किया जाता है: + +| कारण | कारण | +| --- | --- | +| `out-of-credits` | आपकी organization ने अपनी plan allowance use कर दी है। | +| `http-401`, `http-403` | Key को revoke किया गया, या `jev:evaluate` नहीं carries करती। एक key के साथ reconnect करें जो carries करे। | +| `http-429` | FailproofAI Cloud आपकी organization के लिए Jev को rate-limit कर रहा है। जब तक wait जो यह पूछता है समाप्त नहीं हो जाता (इसका `Retry-After`, अधिकतम 60 सेकंड), machine इसे कुछ नहीं भेजता और हर call सीधे fallback करता है। उस तरह held back किए गए calls `http-429` के रूप में recorded होते हैं, या `rate-limited` जब machine की अपनी rate limit उन्हें पहले hold करती है। | +| `http-429` (daily limit) | आपकी organization ने अपने daily Jev calls use कर दिए: **10,000 per UTC day**, जब तक जो आपकी FailproofAI Cloud operate करता है ने दूसरी limit set नहीं की। हर call 00:00 UTC पर count reset होने तक fallback करता है; machine अभी भी अधिकतम एक मिनट में एक बार पूछता है, इसलिए यह reset को एक मिनट के अंदर pick करता है। `failproofai jev test` कहता है "Daily Jev limit for this org reached; resets at 00:00 UTC।" | +| `http-422` | Jev ने इस call के request को refuse किया, आमतौर पर क्योंकि tool call में dense text (base64, hex, minified code) Jev के token budget से अधिक था। वह call हर बार fallback करता है; यह एक outage नहीं है। | +| `http-502` | Jev अभी unavailable है। | +| `http-503` | यह Cloud आपकी org के लिए Jev serve नहीं कर सकता: कोई model gateway नहीं, एक org जो अभी provisioned नहीं है, या gateway down है। अपने admin से पूछें; hooks अधिकतम एक मिनट में एक बार फिर से पूछते हैं। | +| `http-404` | यह FailproofAI Cloud अभी तक Jev serve नहीं करता। | +| `timeout` | `timeoutMs` (default 3000) के अंदर कोई answer नहीं। जब FailproofAI Cloud machine के Jev mode को set करता है, wait 5000 ms है और `jev.json` का `timeoutMs` उपयोग नहीं होता। | +| `model-mismatch` | एक Jev version 1.13 के अलावा दूसरा answered किया। | + +## Key कहाँ रहती है, और कहाँ जाती है + +- Key एक बार store होती है, `~/.failproofai/credentials.json` में (`0600`, एक owner-only directory में), दूसरी FailproofAI Cloud credentials के बगल में। `jev.json` इस route के लिए कोई key hold नहीं करता; एक वहाँ लिखी गई config को invalid बनाती है। +- यदि `credentials.json` **कोई भी** permission carry करती है किसी के लिए लेकिन आप के लिए नहीं (group या other, read या write), या इसकी directory **written** हो सकती है किसी के द्वारा लेकिन आप के द्वारा नहीं, यह **refused** है, read नहीं किया, और Jev off है जब तक आप fix न करें: `chmod 600` file पर, `chmod 700` directory पर (या reconnect करें, जो file को `0600` पर rewrite करता है और directory को owner-only बनाता है)। एक directory जो अन्य केवल read कर सकते हैं ठीक है; एक जो वे write कर सकते हैं उन्हें file swap करने देता है। +- Key केवल तब count करती है जब connection यह आया हुआ machine पर है: एक policy या reporting credential same FailproofAI Cloud के लिए **same key के साथ**, same file में। एक Jev key एक के बिना छोड़ी गई ignored है, और Jev off रहता है। यह होता है जब एक older failproofai का `config --disconnect` Jev key को place में छोड़ता है (वह नहीं जानता remove करने के लिए), या जब एक older failproofai का `config --token` दूसरे key के साथ connect करता है, जो FailproofAI Cloud पर दूसरी organization को belong कर सकता है। Jev को वापस चालू करने के लिए, एक **machine** key के साथ फिर से connect करें। +- Key केवल Cloud origin को भेजी जाती है जिसके विरुद्ध यह verify किया गया था। एक `jev.json` कहीं और pointing को refuse किया जाता है। +- **Machine पर एक agent इसे read कर सकता है।** `credentials.json` owner-only है, और agent उस owner के रूप में चलता है। failproofai की अपनी files को read करना purposely allowed है (केवल उन्हें change करना `block-failproofai-commands` द्वारा blocked है), तो agent और यह file के बीच एकमात्र चीज़ `block-read-outside-cwd` है — एक *reviewable* policy — और एक session से शुरू हुई आपकी home directory में, कुछ नहीं। एक key `jev:evaluate` के साथ आपकी organization के Jev allowance spend करती है (daily cap तक) जहाँ भी उपयोग की जाती है, तो एक machine key को किसी भी दूसरे spending credential की तरह treat करें: यदि एक agent ने इसे read कर लिया हो सकता है, Keys page पर इसे disable करें और एक नई के साथ reconnect करें। +- केवल आपकी global files इसे decide करती हैं। एक repository Cloud Jev को चालू नहीं कर सकता, इसे अन्यत्र point कर सकता है या इसकी key supply कर सकता है, और `FAILPROOFAI_JEV_API_KEY` इस route के लिए ignored है। +- हर call के लिए Jev evaluate करता है, एक request FailproofAI Cloud को जाता है, जो [bring-your-own-key page](/hi/reference/jev-providers#what-leaves-the-machine) list करता है (secrets redacted)। FailproofAI Cloud इसे TypeSafe को forward करता है और इसे log या keep नहीं करता। + +## इसे बंद करें + +एक connected machine पर, Jev off है जब FailproofAI Cloud इसे कोई Jev policy deploy नहीं करता: वहाँ Jev policies को remove या archive करें। + +| Command | परिणाम | +| --- | --- | +| Machine के Jev policies को FailproofAI Cloud में remove करें | Cloud का mode अगली poll पर `off` हो जाता है (लगभग 30 s): कोई Jev नहीं, चाहे `jev.json` क्या कहे। | +| `failproofai config --disconnect` | Machine को disconnect करें: key remove किया जाता है, और `jev.json` भी जब यह FailproofAI Cloud को नाम देता है और switched off नहीं है। आपके अपने endpoint के लिए एक `jev.json` रहता है। | + +अगली tool call से, hooks बिल्कुल पहले की तरह regex policies चलाते हैं। \ No newline at end of file diff --git a/docs/hi/reference/jev-evaluations.mdx b/docs/hi/reference/jev-evaluations.mdx new file mode 100644 index 000000000..89cdcd6d9 --- /dev/null +++ b/docs/hi/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev evaluation reference" +description: "Question types, calibrated scores, limits, और Jev session evaluations के लिए backfill।" +icon: "list-checks" +--- + +यह पृष्ठ [Jev evaluations](/hi/evaluations/jev) के पीछे के question shapes और scoring rules का वर्णन करता है। कुछ questions को एक model से conversation को *पढ़ने* की जरूरत है, लेकिन इसके बारे में *लिखने* की नहीं। "क्या ग्राहक ने तात्कालिकता व्यक्त की?" के दो उत्तर हैं। "वे कितने निराश थे?" के कुछ उत्तर हैं, क्रम में। आप हर उत्तर पहले से ही जानते हैं। + +एक **classifier evaluation** बिल्कुल उन्हीं के लिए है। आप question और जो उत्तर यह दे सकता है उन्हें लिखते हैं, और classification के लिए निर्मित एक छोटा model एक calibrated number लौटाता है — कभी free text नहीं। + + +एक judge की तरह, एक classifier evaluation प्रति session एक model call की लागत लेता है। इसके विपरीत यह एक छोटा, single-purpose model है न कि एक सामान्य, इसलिए यह तेज़ और सस्ता है — लेकिन यह कभी भी अपने बारे में नहीं समझाएगा। यदि आपको reasoning की जरूरत है, तो [judge](/hi/evaluations/judge) का उपयोग करें। + + +## मुझे कौन सा चाहिए? + +| Question | Use | +| --- | --- | +| कितने tool calls थे? | code | +| क्या session 30 सेकंड से कम था? | code | +| क्या ग्राहक ने तात्कालिकता व्यक्त की? | **classifier** | +| यह team कौन सा handle करे: billing, technical, या sales? | **classifier** | +| ग्राहक कितना निराश था? | **classifier** | +| क्या उत्तर वास्तव में सही था? | **judge** | +| क्या इसने हमारी escalation policy का पालन किया, और आप ऐसा क्यों सोचते हैं? | **judge** | + +अंगूठे का नियम: **countable → code, जो उत्तर आप list कर सकते हैं → classifier, explanation की जरूरत है → judge।** + +आपको आगे से ही फैसला नहीं करना है। वर्णन करें कि आप क्या माप करना चाहते हैं और assistant चुनता है, आपको बताता है कि इसने कौन सा चुना और क्यों, और आप इसे बदल सकते हैं। + +## दोनों question types + +### `noul` — क्या यह सत्य है? + +दोनों उत्तर, और आप दोनों का वर्णन करते हैं। परिणाम संभावना है कि "true" विवरण फिट बैठता है: + +```json +{ + "instructions": "क्या assistant ने पहले refund policy check किए बिना refund का वादा किया?", + "criteria": { + "true": "किसी prior policy check या approval के बिना refund का वादा किया गया या जारी किया गया", + "false": "कोई refund का वादा नहीं किया गया, या हर refund policy check का पालन किया" + } +} +``` + +दोनों sides का वर्णन करें। "कोई तात्कालिकता नहीं दिखाई गई" एक वास्तविक उत्तर है और ऐसा कहना दूसरे को तेज़ बनाता है। + +### `score` — इसमें कितना? + +एक ordered rubric, **सबसे बुरा पहले**। परिणाम यह है कि session इस पर कहाँ उतरता है, 0–1 में rescaled: + +```json +{ + "instructions": "ग्राहक कितना निराश है?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**एक rubric को तीन से पाँच levels लेता है, और वे सभी अलग होने चाहिए।** दोनों limits को मापा जाता है, stylistic नहीं: + +- **दो levels** जो `noul` पहले से ही बेहतर करता है उसमें collapse हो जाता है, और **पाँच से अधिक** model को बीच की ओर hedge करने के बजाय प्रतिबद्ध होने के लिए बनाता है। एक ही session पर एक ही question को दो levels के साथ 0.00, तीन के साथ 0.01, और दस के साथ 0.55 स्कोर किया गया। +- **Repeated levels** उत्तर को arbitrarily split करते हैं। एक session जो unmistakably angry था वह `["Calm", "Frustrated", "Very angry"]` के विरुद्ध 1.00 स्कोर किया गया और `["Angry", "Angry", "Angry"]` के विरुद्ध 0.66 — एक well-formed number जिसका कोई मतलब नहीं है। + +कोई order नहीं वाली categories — "billing, technical, या sales" — एक rubric नहीं हैं। इन्हें प्रति category `noul` के रूप में पूछें, या एक judge का उपयोग करें। + +## परिणामों को पढ़ना + +एक classifier 0 से 1 तक एक **score** produce करता है, एक judge की तरह, इसलिए यह charts, filters, और alerts को trigger करने के लिए समान तरीके से काम करता है। दो अंतर जानने लायक हैं: + +- **कोई reasoning नहीं है।** field intentionally खाली है। यह model अपने बारे में नहीं समझाता है, और एक explanation invent करना एक fabrication होगा न कि एक feature। +- **Uncertainty को label किया जाता है।** एक `score` question अपने confidence की report करता है, और एक परिणाम जो model को unsure था उसे `low_confidence` tag किया जाता है — तो "इनमें से कौन सा एक human को देखना चाहिए" एक filter है न कि एक guess। एक `noul` question confidence report नहीं करता है, इसलिए इसे कभी भी tag नहीं किया जाता है। + +बहुत long sessions को excerpts में पढ़ा जाता है और combined किया जाता है। जब एक session पूरी तरह से read करने के लिए बहुत लंबा हो, तो परिणाम बताता है कि कितने turns छोड़े गए थे — आप कभी भी ऐसा judgment नहीं देखेंगे जो session के एक हिस्से पर किया गया हो जो सभी पर किए गए के रूप में प्रस्तुत हो। + +## Limits + +- **तीन से पाँच rubric levels, सभी distinct।** ऊपर देखें; दोनों bounds को authoring time पर enforce किया जाता है। +- **एक evaluation प्रति एक question।** दो चीजें पूछें और आपको दो evaluations मिलते हैं, जो एक chart पर भी वही है जो आप चाहते हैं। +- **Question को editing करने से एक नया version publish होता है।** पुराने और नए scores comparable नहीं हैं, इसलिए उन्हें एक trend line में mixed होने के बजाय अलग रखा जाता है। +- **एक classifier हमेशा एक score produce करता है**, कभी एक metric या assertion नहीं। +- **कोई reasoning नहीं**, जैसा कि ऊपर है। यदि एक number किसी से "क्यों?" पूछने को कहेगा, तो इसके बजाय एक judge लिखें। + +## Testing और backfill + +एक judge के विपरीत, एक classifier evaluation **को** deploy करने से पहले test किया जा सकता है — [test करें](/hi/evaluations/test) यह real sessions के विरुद्ध उसी तरीके से जिस तरह आप एक code evaluation करते हैं, और कुछ भी live होने से पहले scores को पढ़ें। + +इसे [backfilled](/hi/evaluations/deploy#score-sessions-you-already-have) भी किया जा सकता है sessions के ऊपर जो आपके पास पहले से हैं। यह प्रति session एक model call की लागत लेता है, इसलिए deliberately window को scope करें बजाय हर चीज़ को replay करने के। \ No newline at end of file diff --git a/docs/hi/reference/jev-intent.mdx b/docs/hi/reference/jev-intent.mdx new file mode 100644 index 000000000..e83101abf --- /dev/null +++ b/docs/hi/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev intent capture" +description: "कौन सी harness events से Jev evaluator को पता चलता है कि इंसान ने क्या माँगा है, कौन सा field text को carry करता है, क्या कभी नहीं गिना जाता है, और harness-delivered prompt पर भरोसा करने का जोखिम क्या है।" +icon: "message-square-quote" +--- + +जब आप [Jev policy review](/hi/policies/jev) को configure करते हैं, तो evaluator प्रत्येक gated tool call को **इंसान ने क्या माँगा है** इसके विरुद्ध judge करता है, न कि जो भी text harness ने agent के सामने रखा हो। "yes, force-push it" जैसा जवाब एक **reviewable** policy को clear कर सकता है — जो evaluator का पूरा उद्देश्य है, क्योंकि एक regex जो request को नहीं पढ़ सकता वह real work का एक तिहाई हिस्सा block करता है। + +यह text एक ही जगह से आता है: **harness स्वयं अपनी prompt-submit event पर hook को जो prompt देता है**। Failproof AI इसके उस हिस्से को record करता है जो इंसान ने type किया था — harness wrapping stripped, secrets redacted, capped — अपनी state directory के अंतर्गत एक `0600` फ़ाइल में। disk पर कुछ नहीं देखा जाता है: session transcript एक फ़ाइल है जिसे agent एक command में फिर से लिख सकता है, इसलिए कभी नहीं पूछा जाता है कि किसने prompt लिखा है। + +## यह जोखिम जो यह स्वीकार करता है, सीधे शब्दों में + +एक agent जो पहले से ही commands run कर सकता है, एक harness को prompt submit करने के लिए कह सकता है। `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` और `pi -p` सभी एक child session में same prompt-submit event fire करते हैं, same payload के साथ, एक person typing करने की तरह जो agent controls करता है। यह Failproof AI के अपने hook binary को भी run कर सकता है और उसे एक payload feed कर सकता है जो उसने लिखा है। Failproof AI के अंदर कुछ भी दोनों को अलग नहीं कर सकता — दोनों same stdin को read करने वाले same program हैं। + +**तो एक agent shell के साथ अपनी खुद की consent forge कर सकता है।** यह एक deliberate trade है, 2026-09-23 को लिया गया, और यहाँ इसके दोनों हिस्से हैं: + +- **यह क्या खरीदता है।** विकल्प built और measured था: एक field की requirement करें जिसमें harness एक इंसान का नाम prompt के author के रूप में देता है, और अन्यथा कुछ record न करें। कोई भी shipping harness ऐसा field नहीं भेजता है, तो वह version **कुछ नहीं record करता था, हर harness पर** — Jev ने हर call को no stated intent के साथ judge किया और कभी एक भी policy को clear नहीं कर सकता था। एक capture जो कभी fire नहीं होता वह एक safer product नहीं है, यह कोई product नहीं है। +- **यह क्या नहीं कर सकता।** एक recorded prompt एक already marked **reviewable** policy को clear करता है। एक **hard** policy कभी भी Jev कहे से clear नहीं होता है, तो एक forged prompt कभी एक hard deny को allow में नहीं बदल सकता — और hook को skip करना agent को कुछ नहीं देता है: harness tool call के लिए independently Failproof AI को invoke करता है। +- **यह पूरे आकार में क्या कर सकता है।** सबसे बुरा जो यह कर सकता है वह fifteen reviewable built-in policies में से एक को clear करना है — और **उनमें से बारह block करते हैं**। `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` और छह infrastructure-CLI blocks (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) denies हैं, तो एक forged consent एक real deny को allow में बदल सकता है environment secrets print करने, एक `.env` फ़ाइल read करने, project के बाहर read करने, `rm -rf`, force-push, secrets file लिखने, या live infrastructure को बदलने पर। केवल `warn-git-amend`, `warn-destructive-sql` और `warn-global-package-install` nudges हैं। एक default install दो को चालू करता है, `protect-env-vars` और `block-env-files`; बाकी दस केवल एक machine पर पहुँचते हैं जहाँ किसी ने उन्हें enable किया है। कोई भी prompt नहीं पहुँचता है सब कुछ hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, वह guard जो एक agent को Failproof AI disable करने से रोकता है, और हर दूसरा built-in जो reviewable के रूप में marked नहीं है। [Policy authority](/hi/policies/authority) सभी fifteen को list करता है और प्रत्येक किसके द्वारा reviewed है। + +जो अभी भी refuse है वह सब कुछ जो check करने में cheap है और जो एक agent सिर्फ पूछकर नहीं प्राप्त कर सकता है: एक turn जो harness की अपनी payload को machine-submitted के रूप में mark करता है, एक payload जो sub-agent को name करता है, एक session id जो plain name नहीं है, एक event जो prompt-submit नहीं है, और text जो कुछ नहीं है लेकिन harness wrapping — Failproof AI के अपने stop-gate words को शामिल करते हुए, जो कई harnesses अगले user turn के रूप में वापस feed करते हैं। + +## Per-harness table + +"Text field" Failproof AI के per-harness normalization के बाद stdin payload field है। "Recorded" कहता है कि क्या prompt को इंसान के request के रूप में रखा गया है। + +| Harness | `--cli` | Prompt event → canonical | Text field | Recorded | Agent's last message read from | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | हाँ, जब तक payload का `source` एक turn को name न करता है जिसे किसी ने submit नहीं किया (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`)। `user`, `sdk`, एक unknown value और एक build जो कोई `source` भेजता ही नहीं सभी recorded हैं | session transcript (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | हाँ | rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | हाँ | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | हाँ, `` wrapper के साथ जब यह पूरा prompt है तो peeled | agent transcript JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | हाँ — लेकिन current OpenCode उस event में कोई text नहीं carry करता है, तो practice में कुछ नहीं record होता है; same message की repeat एक बार record होती है | none (sessions SQLite हैं) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | हाँ, जब तक `input_source` `extension` न हो — दूसरा extension का `sendUserMessage()`, जिसका text model-written या repo-derived हो सकता है | Pi session JSONL | +| Hermes | `hermes` | none | — | नहीं — Hermes के पास कोई prompt-submit event नहीं है | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | हाँ, जब तक run metadata run को एक machine's के रूप में mark न करे: `trigger` जो `user` नहीं है, `inputProvenance.kind` जो `external_user` नहीं है, या `senderIsOwner: false` | none (`before_agent_run` कोई transcript path नहीं carry करता है) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | हाँ | droid session JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | हाँ | none (sessions SQLite हैं) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | none | नहीं — `PreInvocation` एक turn में *हर* model call से पहले fire होता है और कोई prompt text नहीं carry करता है | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | हाँ | none (sessions SQLite हैं) | + +दो harnesses कुछ नहीं record करते हैं, और दोनों cases में same reason के लिए: उनकी event कोई human text नहीं deliver करती है। Hermes के पास कोई prompt-submit event नहीं है — इसका native plugin `pre_llm_call` को खुद handle करता है और केवल tool, session और subagent events को forward करता है। Antigravity का `PreInvocation` हर model call से पहले fire होता है, एक human turn पर और उसके बाद के पाँच पर, और कोई prompt field नहीं carry करता है; hooks भी same conversation में `userMessage` steps को inject कर सकते हैं। किसी भी event में record करने के लिए कुछ नहीं है। + +## क्या एक prompt को इंसान का बनाता है + +1. **Event।** Failproof AI को harness के prompt-submit event के लिए invoke किया गया था, जिसे handler `UserPromptSubmit` को canonicalize करता है। +2. **Payload।** Harness इसे hook के stdin पर लिखता है, और यह ऊपर named field में text को carry करता है। एक call जो payload के बिना Failproof AI तक पहुँचता है कुछ नहीं record करता है। +3. **Payload में कुछ भी turn को बाहर नहीं निकालता है।** एक payload जो sub-agent को name करता है (`agent_id`) agent को खुद को prompt कर रहा है। एक `source`, `input_source` या OpenClaw run marker जो machine-submitted turn को name करता है refuse है। एक **absent** marker कुछ भी बाहर नहीं निकालता है — यह version से अंतर है जो कुछ नहीं record करता था, क्योंकि हर marker यहाँ every shipping build पर absent है। +4. **Wrapping के बाद कुछ बचा है** (नीचे देखें)। + +**Session transcript इंसान ने किसे लिखा इसका proof नहीं है।** इस page के पहले versions ने एक transcript cross-check describe किया था: prompt refuse था अगर transcript ने दिखाया कि model ने उसे schedule किया है, और transcript को जारी रखना था जो पिछले prompt ने देखा है। वह check चला गया है। एक transcript एक फ़ाइल है जो agent के पास पहले से ही shell है — इसे truncate, replace, padded past read budget किया जा सकता है, एक turn की शुरुआत पर snapshot किया जा सकता है और अंत में restore किया जा सकता है, या entries के साथ फिर से अच्छा पढ़ने के लिए बनाया जा सकता है जो agent लिखा है। hardening का हर round एक और spelling से followed था same forgery के, तो पूरी mechanism को repair करने के बजाय remove किया गया था। + +Transcript अभी भी एक चीज़ के लिए पढ़ा जाता है: **agent की last visible message**। वह message agent-written है परिभाषा से, Jev को बताया जाता है, और यह कभी अपने आप से consent नहीं है। + +## एक prompt से क्या रखा जाता है + +Harnesses एक prompt में इंसान के शब्दों से अधिक डालते हैं। कुछ भी store होने से पहले: + +- `` blocks remove होते हैं, और उनके आस-पास के इंसान के शब्द रखे जाते हैं। +- एक session-continuation summary ("This session is being continued from a previous conversation…") पूरी तरह dropped है। +- Task notifications, local-command output और interruption markers पूरी तरह dropped हैं। +- एक turn जो दूसरे agent या session लिखा है पूरी तरह dropped है: Claude Code उन्हें ``, ``, ``, `` या `` में wrap करता है। +- Failproof AI के अपने messages पूरी तरह dropped हैं। एक stop gate का `MANDATORY ACTION REQUIRED from failproofai …` या एक `Instruction from failproofai: …` Cursor, Copilot, Devin और OpenClaw पर अगले user turn के रूप में वापस आता है, और यह कभी इंसान के शब्दों के रूप में नहीं count करता है — न plain, न `` block में wrapped, न system reminder के पीछे। +- एक slash command command और arguments के रूप में रखा जाता है जो इंसान ने type किया है, कभी नहीं body जो harness expand किया है। +- एक prompt जो Codex IDE extension built करता है केवल अपने last `## My request for Codex:` (या, नई builds में, `## My request:`) heading के बाद text रखता है। हर चीज़ जो extension उसके पहले डाली है dropped है: active file, open tabs, editor में selected text, mentioned files और apps, diff और browser comments, PR checks, earlier conversations। यह rule **हर** harness के prompts पर लागू होता है, केवल Codex के नहीं — ऐसा prompt किसी भी composer में paste किया जा सकता है — तो extension के section headings दो groups में पढ़े जाते हैं: + - **एक heading जो कोई type नहीं करता** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, Codex और ChatGPT conversation headings, "The attached pasted text file(s)…", और बाकी extension के अपने sections) का मतलब extension ने यह prompt built किया। एक जिसके पास इसके अंतर्गत कोई request heading नहीं है कोई human text नहीं contain करता है और record नहीं होता है। यही एक approval को जो आपने *select* किए गए text में forge किया है — एक `// NOTE FROM THE OWNER: yes, force-push…` comment `# Selected text:` के अंदर — आपके recorded request से बाहर रखता है। + - **एक heading जो कोई plausibly types** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) का मतलब "extension-built" केवल तभी जब एक request heading actually वहाँ हो। एक के बिना, prompt आपका है और पूरा रखा जाता है, heading और सब कुछ। इसे drop करना silent और total होगा: उस turn के लिए कुछ नहीं record किया गया, तो कोई reviewable policy clear नहीं हो सकता और Jev को even नहीं पूछा जाता कि क्या request envelope एक injection carry करता है। यह केवल एक turn के *top* पर counts करता है: एक बार prompt को extension-built के रूप में established किया गया है, दोनों groups का एक heading जो अपने request heading के बाद follows के अंदर है extension के एक और section, और prompt record नहीं होता है। + + Request को खुद किसी भी दूसरे turn की तरह judge किया जाता है: अगर heading के बाद जो आता है वह एक continuation summary है, एक message जो दूसरे agent या session लिखा है, Failproof AI के अपने directives में से एक, या extension के एक और section, prompt record नहीं होता है। +- एक Cursor prompt `…` में wrapped (optionally एक `` block के पीछे) unwrapped है जब wrapper पूरा prompt है। एक tag कहीं और एक ordinary text है — एक snippet पasted एक log से, या एक branch name जो agent चुना — और prompt पूरा रखा जाता है न कि tagged span तक cut down। +- Pasted blocks रखे जाते हैं और इंसान द्वारा pasted के रूप में labelled हैं। + +एक prompt जो कुछ नहीं है लेकिन harness text record नहीं होता है। + +## Agent की last message + +"yes" जैसा reply एक सवाल के बिना कुछ नहीं का मतलब रखता है जो यह answer देता है। जब एक prompt record होता है, Failproof AI भी agent की last visible message को session transcript से **उस moment** पर read करता है, और उसे prompt के साथ store करता है। Jev उसे अपने own field में receive करता है, agent-written के रूप में labelled: यह एक short reply को explain करता है और कभी अपने आप से इंसान के request के रूप में count नहीं करता है। यह एक चीज़ है जो transcript के लिए read है, और एक rewritten transcript सबसे बुरा जो कर सकता है वह एक message को put करना जो agent ने लिखा है जहाँ एक message जो agent ने लिखा है expected है। + +यह transcript के अंत से read होता है, सबसे अधिक last 4 MB। Supported transcript formats Claude Code, Codex rollouts हैं (older `agent_message` events और नई `AgentMessage` items), Cursor, Copilot `events.jsonl`, और Pi, Factory और OpenClaw session JSONL। Claude Code के अपने synthetic और API-error messages और subagent (sidechain) messages skipped हैं। Goose और OpenCode के लिए कोई snapshot नहीं है, जो sessions को SQLite में रखते हैं, Devin के लिए, जिसका transcript एक single JSON document है, या OpenClaw के लिए, जिसका `before_agent_run` event कोई transcript path नहीं carry करता है। + +## Storage + +| Property | Value | +| --- | --- | +| Location | `~/.failproofai/state/semantic/sessions//.json`, जहाँ `` वह agent profile है जिसमें prompt type किया गया था: `.` एक agent के लिए जिसे FailproofAI जानता है (identity जो Cloud policies target करती है), या सिर्फ `` अन्यथा | +| Permissions | file `0600`, directory `0700`। इसके ऊपर हर directory, `~/.failproofai` तक, same rule को `jev.json` की directory के रूप में held है: एक जिसे दूसरा कोई भी **write** कर सकता है को rename away और replace किया जा सकता है, तो read path उन write bits को लेता है जहाँ यह कर सकता है, और कहीं भी **कुछ नहीं** read करता है जहाँ यह नहीं कर सकता है। एक recorded prompt फिर absent है rather than forged के | +| Kept per session | last 5 prompts; एक prompt जो उससे पहले के identical है उसे replace करता है न कि एक नया slot लेता है | +| Window | 6 घंटे से पुरानी prompts ignored हैं | +| Size | प्रत्येक prompt और agent message 6,000 characters पर capped है, head और tail रखते हुए | +| Secrets | `sanitize-*` policies के same patterns से redacted हैं कुछ भी लिखे जाने से पहले। एक text जो 48,000 characters से लंबा है अपने first 28,800 और last 19,200 characters के रूप में redacted है, और text जो उन cuts के पास है, जहाँ एक secret split किया जा सकता है, कभी store नहीं होता है | + +एक session ID जो letters, digits, `.`, `_` और `-` के अलावा कुछ contain करता है, या 128 characters से लंबा है, कभी file name के रूप में use नहीं होता है, तो उसके लिए कुछ record नहीं होता है। + +एक session file केवल एक बार exist करता है एक बार prompt उसमें record हो गया है। यह prompts को hold करता है और कुछ नहीं — कोई origin state नहीं, कोई transcript mark नहीं — और यह एक बार deleted है कि यह छह-घंटे की window से लंबे समय तक silent रहा है, अगली बार एक नया session अपनी first prompt write करता है। + +एक prompt केवल same agent profile और session ID के लिए read back है जिसके अंतर्गत यह record किया गया था। Session IDs agent से आते हैं, तो दो profiles same को use कर सकते हैं; profile से key करना एक profile के words को कभी दूसरे के request के रूप में count होने से रखता है। इस layout (`sessions/.json`) से पहली files नहीं कह सकती कि कौन सा profile उन्हें लिखा है, तो वे कभी read नहीं होती हैं, और छह-घंटे की window के साथ expire करती हैं। + +जब तक एक Jev endpoint configure नहीं है तब तक कुछ record नहीं होता है। एक FailproofAI Cloud Jev mode के अंतर्गत, एक agent profile के लिए कुछ record नहीं होता है जिसे कोई Cloud Jev check assign नहीं है और कोई installed pack का check review नहीं करता है। + +### Project root + +"Project के अंदर" — जो `read-outside-workspace` और अन्य path checks judge करते हैं — का मतलब project के अंदर जो session उसके **first reviewed call** पर था। Root तब pinned है और एक later `cd` इसे कभी नहीं move करता है; एक `cd` अभी भी कैसे एक relative path resolve होता है को change करता है। इसे `cd` के बाद follow करने देना एक call में `cd ~/.ssh` को `~/.ssh` को अगले के लिए project बना सकता था। + +Pin `~/.failproofai/state/semantic/roots/.json` है, `{root, at}` को hold करते हुए: file `0600`, directory `0700`, और ऊपर जैसा ही session-ID rule। 7 दिनों से पुरानी फ़ाइलें deleted हैं जब एक नया session अपने root को pin करता है। एक `roots` directory जिसे अन्य users write कर सकते हैं ignored है, और live directory का root use होता है। एक session को re-pin करने के लिए, उसकी फ़ाइल को delete करें। + +## Known limits + +- **एक prompt केवल hook invocation जितना trustworthy है।** सब कुछ यहाँ payload को read करता है जो harness ने hook के stdin पर लिखा है। एक agent जो commands run कर सकता है harness को headlessly run कर सकता है (`claude -p` और ऊपर listed सात अन्य) या Failproof AI के अपने hook binary को खुद ही run करके एक payload के साथ जो उसने लिखा है, और एक prompt record कर सकता है जिसे किसी ने type नहीं किया है। यह accepted trade है जो इस page के top पर described है: यह केवल reviewable policies को clear करता है, कभी एक hard को नहीं — लेकिन fifteen reviewable built-ins में से बारह denies हैं, तो एक forged prompt एक real block को allow में turn कर सकता है उन बारह पर। +- **Sub-agent detection Claude-shaped है।** एक payload जो `agent_id` carry करता है कभी record नहीं होता है, किसी भी harness पर। यह वह field है जो Claude Code, Factory Droid और Devin use करेंगे। Codex sub-agent threads के अंदर अपनी prompt event fire करता है, Copilot in-process sidekicks run करता है, Goose के पास एक `delegate` tool है और OpenClaw personas run करता है — जिनमें से कोई भी payload को इस तरह mark नहीं करता है जो यह recognize करे, तो उन harnesses पर एक sub-agent prompt session के अपने के रूप में record होता है। OpenClaw का `openclaw.agentId` **वह** mark नहीं है: shipped plugin इसे हर run पर set करता है, owner का included। +- **Schedulers जो कोई marker carry नहीं करते।** Claude Code का `schedule_wakeup` और `loop_wakeup`, और OpenClaw का `cron` और `heartbeat` triggers, refuse हैं क्योंकि वे harnesses payload में कहते हैं। Goose का अपना scheduler (`goose schedule add`) और Codex का `codex exec` कुछ नहीं कहते हैं, तो एक run जो वे start करते हैं किसी और के समान record होता है। +- **एक agent की last message एक message हो सकता है जो agent choose किया है।** Transcript authenticated नहीं है, तो एक agent जो अपना transcript लिखता है अपने "last message" को decide कर सकता है क्या कहे। यह agent-written के रूप में labelled है और अपने आप से कुछ नहीं clear करता है — लेकिन नोट करें कि `decide.ts` का v1 path इसे deterministic "did the user name this target" check को satisfy करने देता है, तो एक agent जो अपने transcript को control करता है एक target name supply कर सकता है जो एक override को need करता है। +- **एक prompt जो extension के machine headings में से एक के साथ खुलता है वह पूरी तरह dropped है।** `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` या ऊपर पहले group से एक दूसरी section heading के साथ एक prompt शुरू करें, और कभी एक `## My request:` heading न लिखें, और उस turn के लिए कुछ भी record नहीं होता है — तो उसके लिए कुछ भी clear नहीं होता है। यह deliberate है: वे sections text को carry करते हैं जिसे कोई और controls करता है (code जो आपने select किया है, एक reviewer का diff comment, एक page title), और उसे अपने शब्दों के रूप में record करना बदतर failure है। Headings जो एक developer plausibly types दूसरे group में हैं और कभी एक prompt को अपने आप से drop नहीं करते हैं। +- **OpenCode practice में कुछ नहीं record करता है।** इसका `message.updated` event current OpenCode में कोई text नहीं carry करता है, और यह भी child sessions के लिए fire करता है जो इसका task tool create करता है, जिसका "user" message parent agent लिखा है। +- **`CODEX_HOME` को `lib/codex-sessions.ts` में rollout discovery द्वारा honor नहीं किया जाता है।** यह केवल प्रभावित करता है जहाँ एक agent-message snapshot को look किया जाता है, कभी नहीं चाहे एक prompt record है या नहीं। \ No newline at end of file diff --git a/docs/hi/reference/jev-providers.mdx b/docs/hi/reference/jev-providers.mdx new file mode 100644 index 000000000..4db752c2f --- /dev/null +++ b/docs/hi/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev प्रदाता और अपनी कुंजी सेटअप" +description: "प्रदाता एंडपॉइंट, मॉडल आईडी, कॉन्फ़िगरेशन, और अपनी कुंजी के साथ लाइव Jev नीति समीक्षा के लिए विफलता व्यवहार।" +icon: "key-round" +--- + +यह [Jev नीतियों](/hi/policies/jev) के साथ अपनी कुंजी के लिए प्रदाता और कॉन्फ़िगरेशन संदर्भ है। Regex नीतियां स्ट्रिंग से मेल खाती हैं। वे यह नहीं बता सकते कि `rm -rf build/` जो आपने मांगा था वह `rm -rf ~` से अलग है जो योजना में फिसल गया। तो वे एक जगह पर बहुत कुछ ब्लॉक करते हैं और दूसरी जगह पर बहुत कम। **Jev**, TypeSafe का क्लासिफायर, कॉल को उससे पढ़ता है जो आपने वास्तव में मांगा था और एक तेज़ अनुरोध में इसके बारे में हां/नहीं प्रश्नों का एक सेट का उत्तर देता है। + +अपने Jev एंडपॉइंट और कुंजी के साथ कॉन्फ़िगर किए गए, Failproof AI Jev से प्रत्येक टूल कॉल के बारे में पूछता है **साथ ही** regex नीतियों के साथ, कभी उनके बजाय नहीं: + +- एक **कठोर** नीति की अस्वीकृति अंतिम है। Jev इसे साफ़ नहीं कर सकता। हर नीति कठोर है जब तक कि यह स्पष्ट रूप से समीक्षा योग्य के रूप में चिह्नित नहीं है और Jev जांचों का नाम नहीं देती है जो इसे कवर करती हैं, इसलिए एक कस्टम, पैक या Cloud नीति जो कुछ नहीं कहती है वह कठोर है, और हमेशा-चालू आत्म-सुरक्षा गार्ड हमेशा कठोर है। +- एक **समीक्षा योग्य** नीति की अस्वीकृति को साफ़ किया जा सकता है, लेकिन केवल तभी जब Jev से उस सटीक समस्या के बारे में पूछा गया था जो नीति कवर करती है और "यहाँ कुछ नहीं" या "उपयोगकर्ता ने इसके लिए पूछा" का उत्तर दिया। एक जांच जो समस्या को वास्तविक पाती है, जब उपयोगकर्ता ने कॉल के लिए नहीं पूछा, अस्वीकृति को रखती है — भले ही इसका अपना निर्णय केवल एक चेतावनी हो, क्योंकि एक टूल कॉल से पहले एक चेतावनी एजेंट को नहीं रोकती। और जब वह जांच ऐसी हो जो अस्वीकार कर सकती है (गुप्त जोखिम, साख निष्कर्षण, विनाशकारी विलोपन, …), उस कॉल पर कुछ भी साफ़ नहीं किया जाता है। +- एक ब्लॉक तब भी एक **चेतावनी** बन सकता है जब कॉल आपके द्वारा दिए गए कार्य का एक कदम हो और आगे न पहुंचे: Jev अपनी अस्वीकृति को एक चेतावनी में नरम कर देता है, और यह चेतावनी — कॉल के साथ वास्तव में क्या गलत है यह नाम देती है — नीति के ब्लॉक को प्रतिस्थापित करती है। +- Jev अपने आप पर भी चेतावनी दे सकता है या अस्वीकार कर सकता है, किसी नुकसान के लिए जो regex वर्णन नहीं करता है। +- यदि Jev उत्तर नहीं दे सकता (समय सीमा, दर सीमा, सर्वर त्रुटि, कोई क्रेडिट नहीं, एक अप्रत्याशित मॉडल संस्करण), वह कॉल regex परिणाम प्राप्त करता है, बिल्कुल Jev के बिना। +- Jev कभी भी किसी कॉल को अपनी नीतियों की तुलना में अधिक अनुमतिशील नहीं बनाता है जब तक वह पूरी कॉल नहीं पढ़े और सटीक समस्या के बारे में पूछा न जाए। कुछ भी कम — एक कॉल जो भेजने के लिए बहुत बड़ी है, एक संदिग्ध इंजेक्शन — निकासी को वापस लेता है और हर अस्वीकृति को रखता है। + + +बिना Jev कॉन्फ़िग के कुछ नहीं बदलता: हुक regex नीतियों को ठीक वैसे ही चलाते हैं जैसे हमेशा किया है। कॉन्फ़िग पूरी opt-in है। + + + +FailproofAI Cloud पर? आपको अपनी अपनी कुंजी की जरूरत नहीं है: एक मशीन जो एक कुंजी के साथ जुड़ी है जो `jev:evaluate` करती है वह आपकी संगठन की योजना पर Jev का उपयोग कर सकती है। [FailproofAI Cloud के माध्यम से Jev](/hi/reference/jev-cloud) देखें। + + +## शुरुआत से पहले + +**failproofai 1.0.8-beta.0 या बाद में** स्थापित करें और इसकी हुक को एक [समर्थित हार्नेस](/hi/reference/harnesses) से संलग्न करें उस मशीन पर जहां आपका एजेंट चलता है। [त्वरित शुरुआत](/hi/start/quickstart) का पालन करें यदि यह एक नई मशीन है, या [स्थानीय प्रवर्तन सेटअप करें](/hi/start/setup#enforce-locally) यदि आप Cloud का उपयोग नहीं करते हैं। स्थापित CLI को `failproofai --version` के साथ जांचें। + +नीचे दिए गए किसी प्रदाता से एक API कुंजी प्राप्त करें, या एक संगत एंडपॉइंट और इसकी कुंजी तैयार रखें। Jev ने नाम दिए गए टूल कॉल की समीक्षा `PreToolUse` या `PermissionRequest` गेट पर की है। यह अपना निर्णय जारी कर सकता है, लेकिन एक मौजूदा नीति अस्वीकृति को साफ़ करने के लिए एक स्थापित नीति की भी आवश्यकता है जो [समीक्षा योग्य](/hi/policies/authority) चिह्नित हो। कठोर नीति की अस्वीकृति अंतिम रहती है। + +## एक प्रदाता चुनें + +Jev पाँच मार्गों के माध्यम से पहुंचा जा सकता है। उनमें से किसी एक के लिए कुंजी लाएं। + +| प्रदाता | `--provider` | एंडपॉइंट | डिफ़ॉल्ट मॉडल | नोट्स | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | सटीक संस्करण पिन। | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | अनुरोध केवल शून्य-डेटा-प्रतिधारण एंडपॉइंट्स को रूट किए जाते हैं, दूसरे प्रदाता को फॉलबैक के बिना। एक दिनांकित संस्करण जैसे `typesafe/jev-1.13-20260917` रिपोर्ट करता है। | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | केवल एक उपनाम द्वारा Jev का नाम दिया जाता है, इसलिए उत्तर देने वाले संस्करण को अपरिवर्तित के रूप में दर्ज किया जाता है। | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` की जरूरत है। प्रति कुंजी लगभग छह कॉल प्रति सेकंड मापे गए थे HTTP 429 से पहले। | +| अपना स्वयं का एंडपॉइंट | `custom` | `/systemone` | `jev-1.13.0` | कोई भी एंडपॉइंट जो TypeSafe के अनुरोध बॉडी को स्वीकार करता है और रिपोर्ट करता है कि कौन सा मॉडल उत्तर दिया। केवल `https`; लूपबैक होस्ट (`localhost`, `127.0.0.1`, `::1`) के लिए सादा `http` स्थानीय परीक्षण के लिए स्वीकार किया जाता है। | + + +Vercel के अपने bring-your-own-key फीचर के साथ, एक विफल अनुरोध Vercel की साख के साथ चुप-चाप पुनः प्रयास किया जाता है। यदि आपको हर कॉल बिल किए जाने की और केवल आपके अपने TypeSafe खाते द्वारा देखे जाने की आवश्यकता है, तो TypeSafe को सीधे उपयोग करें। + + +## इसे सेटअप करें + +एक कमांड, एंडपॉइंट और कुंजी। `observe` मोड में शुरुआत करें ताकि आप Jev के निर्णय का निरीक्षण कर सकें जबकि मौजूदा नीतियां निर्णय लेती रहें: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### URL प्रदाता चुनता है + +आपको प्रदाता का नाम देने की जरूरत नहीं है: URL का **होस्ट** यह कौन सा है। + +| URL होस्ट | प्रदाता | भी जरूरत है | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| कोई अन्य होस्ट | `custom` | — आपके द्वारा दिया गया URL बेस URL है | + +इससे तीन बातें निकलती हैं: + +- **एक URL जो प्रदाता का अपना API है कोई ओवरराइड नहीं लिखता।** `--url https://api.typesafe.ai/v1` बिल्कुल वैसा ही कॉन्फ़िग देता है जो `--provider typesafe` होगा। एक ज्ञात प्रदाता पर एक अलग पथ या होस्ट दें और यह बेस URL के रूप में संग्रहीत है, जैसे `--base-url` इसे संग्रहीत करता है। +- **`--provider` अभी भी अनुमान को ओवरराइड करता है**, जो आपको एक प्रॉक्सी तक पहुंचने का तरीका है जो एक प्रदाता के API को बोलता है अपने होस्ट से: `--url https://jev-proxy.internal/v1 --provider typesafe`। +- **एक `--provider` जो होस्ट का विरोध करता है उसे अस्वीकार कर दिया जाता है**, अनुमान नहीं लगाया जाता। `--provider openrouter --url https://api.typesafe.ai/v1` कुछ नहीं लिखता है और कहता है क्यों: दोनों वर्तनी इस बारे में असहमत हैं कि आपकी कुंजी कहां भेजी जा रही है। यही जोड़ी `jev setup --base-url` और डैशबोर्ड के Jev सेटिंग्स से अस्वीकार किया जाता है। (`--provider custom` विरोधाभास नहीं है — इसका अर्थ है "इस URL को अपने आप के रूप में व्यवहार करें" — Cloudflare के होस्ट को छोड़कर, जिसका प्रति-खाता एंडपॉइंट एक कस्टम मार्ग नहीं पहुंच सकता है।) + +`--url` को ठीक वैसे ही मान्य किया जाता है जैसे कॉन्फ़िग फाइल में `baseUrl` को मान्य किया जाता है, और उसी शब्दों में अस्वीकार किया जाता है: `https`, या लूपबैक होस्ट (`localhost`, `127.0.0.1`, `::1`) के लिए सादा `http` किसी भी मोड में। जोखिम: कुछ भी लूपबैक सर्वर को प्रमाणित नहीं करता है, इसलिए जबकि यह नीचे है एक और स्थानीय प्रक्रिया इसके पोर्ट को ले सकती है और उत्तर दे सकती है; स्थानीय परीक्षण के बाहर `https` का उपयोग करें। + +### कुंजी + +इसे `--key-stdin` के साथ पाइप करें, या बिना इसके टर्मिनल में कमांड चलाएं और मास्क किए गए प्रॉम्प्ट पर कुंजी पेस्ट करें। किसी भी तरह से यह सीधे कॉन्फ़िग फाइल में जाता है और कभी वापस मुद्रित नहीं होता है। + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` समान फ्लैग लेता है और इन सभी के लिए लंबा रूप है: `setup --provider ` जहां आप URL के बजाय प्रदाता का नाम देना पसंद करेंगे। + +### `--token`, और इसकी लागत क्या है + +`--token ` कुंजी को कमांड लाइन पर डालता है, जो एक मशीन को कॉन्फ़िगर करने का सबसे तेज़ तरीका है और एकमात्र वर्तनी जो कुंजी को कॉन्फ़िग फाइल के अलावा कहीं और रखता है: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +एक कमांड-लाइन तर्क बाद में आपकी शेल की इतिहास फाइल में होता है, और जबकि कमांड चलता है यह प्रक्रिया सूची में होता है — `/proc` से कुछ भी जो आप के रूप में चल रहा है द्वारा पठनीय है। `setup` हर बार कहता है जब `--token` का उपयोग किया जाता है। एक साझा मशीन पर, एक दर्ज सेशन में, या कहीं भी इतिहास फाइल सिंक की जाती है `--key-stdin` को प्राथमिकता दें; एक कुंजी को घुमाएं जिसे आपने इस तरीके से पारित किया है यदि यह महत्वपूर्ण है। + + +`--token`, `--key-stdin` और `--key-from-env` परस्पर एकात्मक हैं: एक दें। + +फिर कुंजी, एंडपॉइंट जांचने के लिए एक छोटा लाइव अनुरोध भेजें और कौन सा Jev उत्तर दिया: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` 1 से बाहर निकल जाता है, और अपने शीर्षक में कहता है, जब उत्तर समय सीमा के बाद आता है (हर हुक regex में वापस गिरता है `timeout` के रूप में) या अपने चेक प्रश्न का गलत उत्तर देता है। + +हुक हर टूल कॉल पर कॉन्फ़िग पढ़ते हैं, इसलिए यह अगले से लागू होता है। डेमन के साथ या बिना कुछ भी पुनरारंभ करने के लिए कुछ नहीं है। + +## यह क्या कर रहा है इसकी जांच करें + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` प्रदाता, एंडपॉइंट, मॉडल, मोड, कॉन्फ़िग फाइल और इसकी अनुमतियां दिखाता है, और कभी भी कुंजी नहीं। इसके नीचे यह हाल की गतिविधि को सारांशित करता है: कितनी कॉल Jev ने मूल्यांकन किया, यह कितनी बार regex में वापस गिरता था और क्यों, इसकी विलंबता, और कौन सी समीक्षा योग्य नीतियों को स्पष्ट किया। + +## एक वास्तविक कॉल को सत्यापित करें + +हुक किए गए एजेंट में एक नया सत्र शुरू करें। इसे `README.md` पर अपनी फाइल-पढ़ने के टूल का उपयोग करने के लिए कहें और शीर्षक की रिपोर्ट करें। पुष्टि करें कि सत्र में वह टूल कॉल है, फिर `failproofai jev status` फिर से चलाएं: इसकी हाल की मूल्यांकित-कॉल संख्या बढ़ना चाहिए। [स्थानीय डैशबोर्ड](/hi/reference/local-dashboard#review-policy-activity) में **नीतियां → गतिविधि** खोलें कॉल के Jev निर्णय और मोड का निरीक्षण करने के लिए। observe मोड में, नीति परिणाम अभी भी कॉल का निर्णय लेता है। एक निकासी तभी दिखाई देती है जब एक समीक्षा योग्य नीति मिली थी और Jev ने हर नाम की जांच को साफ़ किया था; एक साधारण पढ़ अपने पास साफ़ करने के लिए कोई नीति नहीं हो सकती है। + +## Observe मोड + +`enforce` डिफ़ॉल्ट है। Jev को देखने के लिए बिना किसी निर्णय को बदलने के, `observe` पर स्विच करें: Jev अभी भी पूछा जाता है और इसके निर्णय दर्ज किए जाते हैं, लेकिन regex परिणाम वह है जो लागू किया जाता है। + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` कॉन्फ़िग रखता है — एंडपॉइंट और कुंजी — और Jev से पूछना बंद कर देता है: हुक regex नीतियों को बिल्कुल उसी तरह चलाते हैं जैसे कॉन्फ़िग के बिना, और `failproofai jev status` "off (switched off)" कहता है। `--mode observe` या `--mode enforce` के साथ वापस स्विच करें। + +`setup` को फिर से चलाने के लिए समान प्रदाता कुंजी को संग्रहीत रखता है, इसलिए एक मोड स्विच एक फ्लैग है। प्रदाता को स्विच करना नए सिरे से शुरू होता है और उस प्रदाता की कुंजी के लिए पूछता है। एक `--base-url` भी करता है जो अनुरोधों को एक अलग होस्ट पर ले जाता है: एक संग्रहीत कुंजी केवल होस्ट को भेजी जाती है जिसे यह दिया गया था, या इसके प्रदाता के अपने API को। + +## कॉन्फ़िग फाइल + +सब कुछ एक फाइल में रहता है, `~/.failproofai/jev.json`, `setup` द्वारा लिखी गई: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| फील्ड | अर्थ | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` या `custom` — या `failproofai`, जिसकी कुंजी इस फाइल के बजाय FailproofAI Cloud कनेक्शन से आती है ([FailproofAI Cloud के माध्यम से Jev](/hi/reference/jev-cloud) देखें)। | +| `apiKey` | `Authorization: Bearer ` के रूप में भेजी गई। | +| `baseUrl` | `custom` के लिए आवश्यक; अन्यथा प्रदाता के API बेस को प्रतिस्थापित करता है। `https` होना चाहिए। सादा `http` से `localhost` केवल `mode: observe` के साथ स्वीकार किया जाता है: कुछ भी लूपबैक सर्वर को प्रमाणित नहीं करता है, इसलिए जबकि आपका प्रॉक्सी नीचे है कोई भी मशीन पर स्थानीय प्रक्रिया, मूल्यांकन किए जा रहे एजेंट सहित, अपनी जगह उत्तर दे सकता है। | +| `accountId` | Cloudflare केवल: 32 लोअरकेस हेक्स वर्ण। | +| `model` | प्रदाता के डिफ़ॉल्ट मॉडल आईडी को प्रतिस्थापित करता है। एक संस्करण आईडी को Jev 1.13 का नाम देना चाहिए। एक API कुंजी की तरह आकार वाला मान अस्वीकार कर दिया जाता है (और वापस दोहराया नहीं जाता है), इसलिए `--model` में पेस्ट की गई कुंजी कभी मॉडल के रूप में संग्रहीत या भेजी नहीं जाती है। | +| `timeoutMs` | कॉल Jev से regex परिणाम का उपयोग करने से पहले कितना समय प्रतीक्षा करता है। 100–10000, डिफ़ॉल्ट 3000। | +| `mode` | `enforce` (डिफ़ॉल्ट), `observe`, या `off` (कॉन्फ़िग रखें, कोई Jev न चलाएं)। | + +तीन नियम इसकी रक्षा करते हैं: + +- **मालिक-केवल।** यह `0600` अनुमतियों के साथ लिखी गई है। एक प्रति जो कोई अन्य उपयोगकर्ता या समूह पढ़ या लिख सकता है **अस्वीकार किया जाता है**, और हुक regex में वापस गिर जाते हैं जब तक आप `chmod 600 ~/.failproofai/jev.json` न चलाएं या `setup` फिर से न करें। निर्देशिका भी जांची जाती है: `~/.failproofai` किसी और द्वारा **लिखने योग्य** नहीं होनी चाहिए, क्योंकि जो भी वहां लिख सकता है वह फाइल को अपनी अनुमतियों के बावजूद प्रतिस्थापित कर सकता है। `setup` यदि यह उन्हें पाता है तो उन लिखने वाले बिट्स को हटा देता है। `failproofai jev status` कहता है कि कब कॉन्फ़िग अस्वीकार किया गया है और एंडपॉइंट दिखाता है जो फाइल नाम देती है: किसी और ने इसे बदला हो सकता है, इसलिए इसे `chmod` करने से पहले जांचें कि यह आपका है। `setup` को ऐसी फाइल पर फिर से चलाना इसकी संग्रहीत कुंजी केवल प्रदाता के अपने API के लिए ले जाता है; कोई अन्य एंडपॉइंट जो इसका नाम देता है उसे कुंजी की फिर से आवश्यकता है (`--key-stdin`), या `--base-url default` अनुरोधों को प्रदाता को वापस भेजने के लिए। +- **Global केवल।** एक रिपोजिटरी Jev को चालू नहीं कर सकती है, इसे दूसरे एंडपॉइंट पर इंगित कर सकती है या इसका मॉडल चुन सकती है: एक प्रोजेक्ट के अंदर `.failproofai/jev.json` की अनवेक्षा की जाती है, और प्रदाता, URL, मॉडल और खाता आईडी केवल उस फाइल से पढ़े जाते हैं — कभी भी पर्यावरण से नहीं, जो एक रिपोजिटरी के एजेंट सेटिंग्स सेट कर सकते हैं। (`FAILPROOFAI_HOME` इसके चारों ओर एक तरीका नहीं है: यह पूरी failproofai निर्देशिका को ले जाता है, आपकी नीतियों सहित, बजाय Jev को अपने आप पर पुनर्निर्देशित करने के।) +- **कुंजी अकेले पर्यावरण से आ सकती है।** यदि फाइल में कोई `apiKey` नहीं है, `FAILPROOFAI_JEV_API_KEY` उस सत्र के लिए इसकी आपूर्ति करता है (`setup --key-from-env` ऐसी फाइल लिखता है)। यह कभी भी कुंजी को प्रतिस्थापित नहीं करता है जो फाइल रखती है, और Jev को फाइल के बिना चालू नहीं कर सकता है। जहां चर सेट नहीं है, Jev केवल उस शेल के लिए बंद है: `failproofai jev status` इसे कहता है, 0 से बाहर निकलता है और कॉन्फ़िग को अकेला छोड़ देता है (`status --json` `"status": "key-missing"` को `"reason": "no-env-key"` के साथ रिपोर्ट करता है)। `failproofaid` डेमन आपके शेल के पर्यावरण को नहीं देखता है, इसलिए एक मशीन पर `failproofai config` के साथ सेटअप की गई है, कुंजी को फाइल में रखें। + +## कौन सा Jev उत्तर देता है + +Failproof AI के निर्णय थ्रेसहोल्ड Jev 1.13 पर कैलिब्रेट किए गए थे, इसलिए एक उत्तर केवल तभी उपयोग किया जाता है जब यह उस परिवार से आता है: `jev-1.13.x`, या OpenRouter का `typesafe/jev-1.13-`। जहां एक प्रदाता केवल एक उपनाम से Jev का नाम देता है और कोई संस्करण रिपोर्ट नहीं करता है (Vercel, और Cloudflare जब यह नहीं करता है), उत्तर का उपयोग किया जाता है और अपरिवर्तित के रूप में दर्ज किया जाता है। एक `custom` एंडपॉइंट को उत्तर देने वाले मॉडल की रिपोर्ट करनी चाहिए; एक अपवाद एक अनुपलब्ध `--model` नाम है जो आपने इसके लिए कॉन्फ़िगर किया है, जो, वापस गूंजा, उसी तरीके से अपरिवर्तित के रूप में दर्ज किया जाता है। किसी अन्य संस्करण की रिपोर्ट करने वाला कोई उत्तर, या एक `custom` उत्तर कोई भी नहीं रिपोर्ट नहीं, उपयोग नहीं किया जाता है: वह कॉल regex में वापस गिरता है कारण `model-mismatch` के साथ। + +## जब Jev उत्तर नहीं दे सकता + +इनमें से प्रत्येक उस कॉल के लिए regex परिणाम में गिरता है और इसके कारण के साथ दर्ज किया जाता है, जो `failproofai jev status` कुल करता है: + +| कारण | कारण | +| --- | --- | +| `timeout` | `timeoutMs` के भीतर कोई उत्तर नहीं। | +| `http-429` | प्रदाता ने कुंजी को दर-सीमित किया। | +| `rate-limited` | Failproof AI का अपना लिमिटर कॉल को भेजने से पहले रोक दिया: 5 अनुरोध प्रति सेकंड, 5 तक के फटने में, और प्रदाता 429 का उत्तर देने के बाद एक पल के लिए कोई नहीं। प्रदाता नहीं। | +| `http-500`, `http-502`, `http-503`, … | प्रदाता पर एक सर्वर त्रुटि। सटीक स्थिति दर्ज की जाती है। | +| `out-of-credits` | HTTP 402: प्रदाता खाते के पास कोई क्रेडिट नहीं बचा है। | +| `provider-refused` | Cloudflare से HTTP 402 "Model execution failed (Payment error)" पढ़ता है: प्रदाता ने इस अनुरोध पर मॉडल को चलाने से इनकार कर दिया। आमतौर पर बिलिंग नहीं, इसलिए शीर्ष भरना इसे नहीं ले जाएगा। | +| `http-401`, `http-403` | कुंजी अस्वीकार कर दी गई। | +| `http-404` | `/systemone` पर कुछ भी परोसा नहीं जाता है, इसलिए बेस URL गलत है — `/systemone` इसमें जोड़ा जाता है, और हर प्रदाता इसे अपने संस्करण मूल पर परोसता है। `failproofai jev models` दिखाता है कि एंडपॉइंट क्या परोसता है। | +| `network` | एंडपॉइंट तक नहीं पहुंचा जा सका। | +| `http-301`, `http-302`, `http-307`, `http-308` | एंडपॉइंट ने एक रीडायरेक्ट के साथ उत्तर दिया। रीडायरेक्ट का कभी पालन नहीं किया जाता है, इसलिए उत्तर केवल आपके कॉन्फ़िग में URL से आता है; `--base-url` को अंतिम URL पर सेट करें। | +| `malformed` | एंडपॉइंट ने उत्तर दिया, लेकिन Jev उत्तर के साथ नहीं — एक बॉडी जो JSON नहीं है, या इसमें कोई उत्तर नहीं हैं। | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare के लिफाफे ने विफलता की रिपोर्ट की, या एक नौकरी जो समाप्त नहीं हुई थी। | +| `model-mismatch` | Jev संस्करण के अलावा 1.13 ने उत्तर दिया, या एक `custom` एंडपॉइंट ने नहीं कहा कि कौन सा मॉडल उत्तर दिया। | +| `request-cut` | **कोई खंड नहीं।** Jev उत्तर दिया; इसे केवल कॉल का भाग दिखाया गया था, इसलिए इसका उत्तर कुछ नहीं साफ़ किया। [जब Jev उत्तर दिया, लेकिन पूरी कॉल पर नहीं](#when-jev-answered-but-not-on-the-whole-call) देखें। | + +`failproofai jev status` कुछ दुर्लभ कारणों को भी दिखा सकता है, जैसे `upstream-error` (उत्तर प्रदाता की अपनी त्रुटि ले गया) या `config`, और जो भी कारण का नाम नहीं दे सकता उसे `other` के रूप में कुल करता है। + +`request-cut` इस तालिका में है क्योंकि `failproofai jev status` इसे बाकी के साथ कुल करता है, और क्योंकि यह भी हर अस्वीकृति को खड़ा रखता है। यह यहां एकमात्र कारण है जो आपके प्रदाता के बारे में कुछ नहीं कहता है: अनुरोध आया और Jev उत्तर दिया। ऊपर के हर पंक्ति के विपरीत, वह उत्तर अभी भी गिनता है — Jev की अपनी अस्वीकृति या चेतावनी regex परिणाम के शीर्ष पर लागू होती है बजाय इसे त्यागने के। तो उनमें से एक रन कॉल का अर्थ है कॉल मूल्यांकनकर्ता तक पहुंच रहे हैं पूरे से बहुत बड़े, यह नहीं कि आपका एंडपॉइंट खराब है, और क्रेडिट को शीर्ष पर रखना या URL को बदलना संख्या को नहीं ले जाएगा। + +## जब Jev उत्तर दिया, लेकिन पूरी कॉल पर नहीं + +दो और चीजें हो सकती हैं, और न ही Jev को उत्तर देने में विफलता के बारे में है। दोनों इस बारे में हैं कि कितना कॉल, या बातचीत, एक अनुरोध में फिट हुआ। + +**कॉल का भाग ही फिट नहीं हुआ।** एक टूल कॉल एक निश्चित बजट के अंदर भेजी जाती है, और एक बड़ी — एक बहुत बड़ा `Write`, एक विशाल MCP बॉडी, एक कमांड जो टोपी तक पैड किया गया — जो फिट हुआ उसके साथ भेजी जाती है। Jev अभी भी उत्तर देता है, और इसका उत्तर अभी भी गिनता है: इसकी अपनी अस्वीकृति या चेतावनी सामान्य रूप से लागू होती है। क्या यह नहीं कर सकता **साफ़** कुछ भी है, क्योंकि कॉल के भाग पर दिया गया एक फैसला कॉल पर एक फैसला नहीं है। तो हर नीति अस्वीकृति खड़ी है, और कॉल एक फॉलबैक के रूप में दर्ज किया जाता है कारण `request-cut` के साथ, जो `failproofai jev status` ऊपर दिए गए कारणों के साथ कुल करता है। नियम यह आपको देता है: एक कॉल को बड़ा बनाना इसकी निकासी की कीमत दे सकता है, और कभी भी एक खरीद नहीं सकता है। + +**एक संदेश फिट नहीं हुआ।** एक लंबा प्रॉम्प्ट आपने चिपकाया, एजेंट का आखिरी संदेश, या एक प्रॉम्प्ट जो इस मूल्यांकनकर्ता के अपने स्टोर ने पहले से ही टोपी दी। **कुछ नहीं बदलता है**: कॉल का निर्णय लिया जाता है, साफ़ किया जाता है और किसी अन्य की तरह दर्ज किया जाता है, और यह फॉलबैक के रूप में गिना नहीं जाता है। आप जो टाइप करते हैं उसकी लंबाई कभी एक फैसले का फैसला नहीं करती है, और एक कट सहमति की निर्माण नहीं कर सकता है: जहां एक प्रॉम्प्ट पहले से ही टोपी में आया था, "आपने इसके लिए नहीं पूछा" "यह निष्कर्ष नहीं बन जाता है जो इससे खींचा जा सकता है, बजाय एक बन जाता है। + +दोनों के बीच की रेखा यह है कि किसने पाठ लिखा है। कॉल एजेंट की है, और एक नियम जो इसकी लंबाई को गंभीरता को घटाने दें एक नियम है एजेंट अपना सकता है; आपका प्रॉम्प्ट आपका है, और इसकी लंबाई को केवल एक सिग्नल के रूप में व्यवहार करना हमेशा एक स्पेक या स्टैक ट्रेस पेस्ट करने को दंडित करता है। + +## मशीन से क्या छोड़ता है + +प्रत्येक टूल कॉल के लिए Jev मूल्यांकन करता है, एक अनुरोध आपके प्रदाता को जाता है, ले जाता है: + +- टूल कॉल ही, API कुंजियों, वाहक टोकन और `KEY=` असाइनमेंट जैसे गुप्त सामग्री के साथ; +- आपने टाइप किए गए हाल के प्रॉम्प्ट, आपके एजेंट के हार्नेस ने हटाई गई पाठ के साथ; +- आपके नवीनतम प्रॉम्प्ट से पहले एजेंट का आखिरी संदेश, एजेंट-लिखित के रूप में लेबल किया गया; +- स्थानीय रूप से गणना किए गए तथ्य, जैसे कि क्या एक पथ प्रोजेक्ट के अंदर है — जो सत्र पहली समीक्षा की गई कॉल पर था, [सत्र के लिए पिन किया गया](/hi/reference/jev-intent#the-project-root) — और वर्तमान git शाखा। + +यह केवल आपके कॉन्फ़िग में एंडपॉइंट को, आपकी कुंजी के तहत जाता है। + +## इसे बंद करें + +```bash +failproofai jev remove +``` + +यह `~/.failproofai/jev.json` को हटाता है। अगली टूल कॉल से, हुक regex नीतियों को ठीक पहले की तरह चलाते हैं। `~/.failproofai/state/semantic/` के तहत प्रति-सत्र स्टोर (दर्ज किए गए प्रॉम्प्ट `sessions/` में, प्रोजेक्ट रूट `roots/` में) जगह पर छोड़े जाते हैं और उम्र बाहर। Jev से पूछना बंद करने के लिए लेकिन कॉन्फ़िग रखने के लिए, `failproofai jev setup --mode off` का उपयोग करें। + +## कमांड संदर्भ + +| कमांड | परिणाम | +| --- | --- | +| `failproofai jev --url --key-stdin` | इसे एक कमांड में कॉन्फ़िगर करें; प्रदाता URL के होस्ट से आता है | +| `failproofai jev --url --token ` | समान, कमांड लाइन पर कुंजी के साथ — आपका इतिहास और प्रक्रिया सूची इसे देखती है | +| `failproofai jev setup --provider --key-stdin` | stdin पर पाइप की गई कुंजी से कॉन्फ़िग लिखें | +| `failproofai jev setup --provider ` | समान, मास्क किए गए प्रॉम्प्ट पर कुंजी के लिए पूछ रहे हैं | +| `failproofai jev setup --key-from-env` | कोई कुंजी संग्रहीत न करें; प्रति सत्र `FAILPROOFAI_JEV_API_KEY` पढ़ें | +| `failproofai jev setup --mode observe` | मोड स्विच करें (`enforce`, `observe` या `off`), संग्रहीत कुंजी को रखते हुए | +| `failproofai jev setup --model ` / `--base-url ` | मॉडल या API बेस को ओवरराइड करें; `default` ओवरराइड को साफ़ करता है | +| `failproofai jev setup --timeout-ms ` | प्रति-कॉल बजट बदलें | +| `failproofai jev status [--json]` | कॉन्फ़िगरेशन, अनुमतियां और हाल की गतिविधि; कभी भी कुंजी नहीं | +| `failproofai jev test [--json]` | एक लाइव अनुरोध: विलंबता और जो संस्करण उत्तर दिया | +| `failproofai jev models [--provider ] [--url ] [--json]` | मॉडल आईडी जो एंडपॉइंट की `/models` रिपोर्ट करता है, कॉन्फ़िगर किए गए को चिह्नित करता है | +| `failproofai jev remove` | कॉन्फ़िग हटाएं; Jev बंद है | \ No newline at end of file diff --git a/docs/hi/reference/jev.mdx b/docs/hi/reference/jev.mdx new file mode 100644 index 000000000..0967e51aa --- /dev/null +++ b/docs/hi/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev integration reference" +description: "Jev के लिए कॉन्फ़िगरेशन, प्रदाता, कुंजियाँ, अनुरोध डेटा, और विफलता व्यवहार।" +icon: "braces" +--- + +Failproof AI में Jev के दो उपयोग हैं: + +| उपयोग | कब चलता है | क्या लौटाता है | यहाँ शुरू करें | +| --- | --- | --- | --- | +| सत्र मूल्यांकन | एक सत्र समाप्त होने के बाद | एक निश्चित-उत्तर प्रश्न के लिए एक स्कोर | [Jev मूल्यांकन](/hi/evaluations/jev) | +| टूल-कॉल नीति समीक्षा | एक गेटेड टूल कॉल चलने से पहले | स्थापित नीतियों के साथ एक निर्णय | [Jev नीतियाँ](/hi/policies/jev) | + +## संदर्भ पृष्ठ + +| विषय | विवरण | +| --- | --- | +| [मूल्यांकन प्रश्न](/hi/reference/jev-evaluations) | बूलियन और क्रमबद्ध-स्कोर मानदंड, परिणाम, सीमाएँ, और बैकफिल। | +| [प्रदाता तुलना और अपनी कुंजी सेटअप](/hi/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare, और कस्टम एंडपॉइंट; URL अनुमान, मॉडल ID, `jev.json`, मोड, और फॉलबैक कोड। | +| [FailproofAI क्लाउड रूट](/hi/reference/jev-cloud) | मशीन-कुंजी अनुमतियाँ, स्वचालित observe सेटअप, उपयोग सीमाएँ, कनेक्शन स्थिति, और डेटा हैंडलिंग। | + +स्थानीय CLI आदेश [Failproof AI CLI संदर्भ](/hi/reference/failproof-cli) में सूचीबद्ध हैं। [स्थानीय डैशबोर्ड संदर्भ](/hi/reference/local-dashboard#set-up-jev) इसकी Jev सेटिंग्स और गतिविधि दृश्य का वर्णन करता है। \ No newline at end of file diff --git a/docs/hi/reference/mcp.mdx b/docs/hi/reference/mcp.mdx new file mode 100644 index 000000000..db1ff4159 --- /dev/null +++ b/docs/hi/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP server" +description: "Claude, Cursor, Codex, या किसी अन्य MCP client को Failproof AI Cloud से जोड़ें, अपनी अनुमतियों का उपयोग करके।" +icon: "plug" +--- + +एक AI tool को Failproof AI Cloud से जोड़ें और इससे अपने agents के डेटा के साथ काम करें। आपका tool sessions और events को query कर सकता है, read-only SQL चला सकता है, dashboards, alerts, issues, audits और policies को पढ़ सकता है, और यदि आपके पास अनुमति है, तो alert बनाना या policy deploy करने जैसे परिवर्तन कर सकता है। + +हर call आपकी **अपनी** अनुमतियों के साथ चलती है, **एक** organization में जिसे आप जोड़ते समय चुनते हैं। + +सभी के लिए एक address है, hosted या self-hosted: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Client को जोड़ें + +Address को अपने client में जोड़ें। जब पहली बार कोई tool use होता है, तो आपका browser खुल जाता है। चुनें कि आपका Failproof AI Cloud कहां है, sign in करें, एक organization चुनें, और **Allow** को select करें। **Cancel** से कोई भी connection नहीं होगा। + +Page app का नाम और जहां यह वापस जाता है, वह दिखाता है। एक app जो अपने web address से identified नहीं होता है, को **unverified app** के रूप में चिह्नित किया जाता है, इसलिए केवल तभी आगे बढ़ें यदि आपने अभी इसे अपने client से शुरू किया है। + + + + claude.ai या Claude Desktop में, **Settings → Connectors → Add custom connector** पर जाएं। इसका नाम `Failproof AI` रखें, address enter करें, **Add** को select करें, फिर **Connect** को select करें। + + Team और Enterprise plans पर, एक owner पहले organization के लिए connector जोड़ता है। फिर हर व्यक्ति अपने account को जोड़ता है। + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + फिर Claude Code के अंदर `/mcp` चलाएं, `failproofai` को select करें, और **Authenticate** को चुनें। + + + इसे `~/.cursor/mcp.json` में, या अपने project के `.cursor/mcp.json` में जोड़ें: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor server के आगे **Needs login** दिखाता है। Sign in करने के लिए इसे select करें। + + + इसे `~/.codex/config.toml` में जोड़ें: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + फिर `codex mcp login failproofai` चलाएं। + + + कोई भी client जो Streamable HTTP के साथ remote MCP servers को OAuth के साथ support करता है। इसे ऊपर दिया गया address दें। कोई client ID या secret configure करने के लिए नहीं है। + + + +## एक connection में एक organization + +एक connection केवल उस organization में काम करता है जिसे आपने चुना है। दो organizations का उपयोग करने के लिए, server को दो बार अलग-अलग नामों के अंतर्गत जोड़ें, जैसे `failproofai-acme` और `failproofai-sandbox`, और प्रत्येक को अपने organization से जोड़ें। + +Demo organizations connections को स्वीकार नहीं करते। इसके बजाय अपना organization चुनें। + +## अनुमतियां + +एक connection आपके द्वारा organization में किए जा सकने वाले कार्यों को कर सकता है, नीचे दिए गए set के अंतर्गत। यह आपकी वर्तमान अनुमतियों का पालन करता है: यदि कोई admin आपको अधिक देता है, तो tool को यह मिल जाती है, और यदि वे कुछ हटाते हैं, तो tool इसे अपनी अगली call पर खो देता है। + +| अनुमति | Tool को अनुमति देती है | +| --- | --- | +| `events:read` | Events को list करें, एक session का overview पढ़ें, agents और environments को list करें | +| `evaluations:read` | Sessions को list करें, और evaluation results और jobs को पढ़ें और summarize करें | +| `evaluations:trigger` | Evaluations बनाएं, नए versions publish करें, उन्हें चालू या बंद करें, backfill करें, और एक session को re-evaluate करें | +| `dashboards:read`, `dashboards:write` | Dashboards को पढ़ें, या उन्हें बनाएं, rename करें, और उनमें queries जोड़ें | +| `queries:read`, `queries:write` | Saved queries को पढ़ें, या उन्हें save और edit करें | +| `queries:run` | एक read-only SQL query चलाएं और query schema को पढ़ें | +| `alerts:read`, `alerts:write` | Alerts को पढ़ें, या उन्हें बनाएं, edit करें, pause करें, delete करें, और test करें | +| `issues:read` | Issues को पढ़ें, उन्हें acknowledge करें, और उन पर comment करें | +| `issues:create` | एक alert पर issue खोलें | +| `issues:close` | Issues को resolve और close करें | +| `audits:read`, `audits:write` | Audits, runs और findings को पढ़ें, या audits बनाएं, edit करें और एक run शुरू करें | +| `code_fixes:read` | देखें कि एक issue को कैसे ठीक करें, और अपने agent के लिए इसके context को प्राप्त करें | +| `code_fixes:write` | Failproof AI Cloud में एक fix शुरू करें, जो आपके GitHub पर एक pull request खोलता है | +| `policies:read`, `policies:write` | Policies, machines और deployments को पढ़ें, या policies को publish, deploy, और rollback करें | + +कुछ tools को कोई अनुमति की आवश्यकता नहीं है क्योंकि वे कोई organization डेटा नहीं पढ़ते: session और event links को building करना, और इस documentation को search करना। + +एक AI tool कभी भी API keys, users, settings या organization administration को touch नहीं कर सकता, और यह events भेज नहीं सकता। + +## परिवर्तनों को मंजूरी देना + +Writes पहले आपसे पूछते हैं यदि आपका client prompt दिखा सकता है। आप देखते हैं कि क्या बदलेगा और **Approve this change** को select करते हैं आगे बढ़ने के लिए। यदि आप decline करते हैं या लगभग 4 मिनट के अंदर उत्तर नहीं देते हैं, तो कुछ नहीं बदलता। कुछ clients एक मिनट के बाद प्रतीक्षा करना बंद कर देते हैं, इसलिए तुरंत उत्तर दें। + + + एक client जो prompts को support नहीं करता है, उससे पूछा नहीं जाता है, और एक write तुरंत चलता है जब client call करता है। वहां, आपके client की अपनी confirmation ही एकमात्र है, इसलिए write tools के लिए इसे चालू रखें। + + +## Connected apps और revoking + +**Settings → Integrations → MCP** वर्तमान organization में आपके connected apps को list करता है, उनकी अनुमतियों और अंतिम use के साथ। **Revoke** एक app को तुरंत काट देता है। अपने client में server को हटाना भी connection को revoke करता है। + +आप प्रति organization में 5 connected apps तक कर सकते हैं। एक ही app को दोबारा जोड़ने से इसका पहले का connection replace हो जाता है। + +## Self-hosted deployments + +जोड़ते समय **Self-hosted Failproof AI Cloud** को चुनें, और उस address को enter करें जहां आप sign in करते हैं। आपके deployment को public HTTPS पर पहुंचा जा सकना चाहिए। + +Tool calls और उनके results hosted Failproof AI gateway के माध्यम से pass होते हैं जब वे आपके AI tool और आपके deployment के बीच जाते हैं। Gateway उन्हें store नहीं करता है। + +## आपके डेटा का क्या होता है + +Results उस AI tool को जाते हैं जिसे आपने जोड़ा है, और उस tool का provider उन्हें अपनी शर्तों के अंतर्गत handle करता है। प्रत्येक tool call के लिए, Failproof AI tool का नाम, इसके outcome, यह कितने समय में ले गया, और organization को log करता है, कभी arguments या results नहीं। [privacy policy](https://befailproof.ai/privacy/) देखें। + +## समस्या निवारण + +| आप क्या देखते हैं | क्या करें | +| --- | --- | +| "Started in another browser" | Client द्वारा खोले गए browser में sign-in को समाप्त करें, cookies को अनुमति दें, और client से फिर से शुरू करें | +| **Allow** के बाद एक error | Link एक बार काम करता है और 10 मिनट के बाद expire हो जाता है, इसलिए client से फिर से शुरू करें | +| एक tool जिसकी आप उम्मीद करते थे, गायब है | आप इस organization में इसकी अनुमति नहीं रखते हैं। एक admin से पूछें। एक बार जब आपके पास यह हो तो आपको reconnect करने की आवश्यकता नहीं है | +| Client आपसे बार-बार sign in करने के लिए कह रहा है | Connection को revoke किया गया था, आप organization से चले गए, या 90 दिनों के लिए इसका उपयोग नहीं किया गया। फिर से जोड़ें | +| "You have 5 connected apps" | **Settings → Integrations → MCP** के अंतर्गत एक को revoke करें, फिर फिर से जोड़ें | + +अभी भी फंस गए? [support@befailproof.ai](mailto:support@befailproof.ai) को email करें। \ No newline at end of file diff --git a/docs/hi/reference/otel.mdx b/docs/hi/reference/otel.mdx new file mode 100644 index 000000000..e2bfc2cca --- /dev/null +++ b/docs/hi/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "FailproofAI Cloud को OTEL में ऑप्ट इन करें, डिलिवरी का निरीक्षण करें, और अपनी पिछली सेटिंग्स को पुनः स्थापित करें।" +icon: "radio" +--- + +`failproofai otel` FailproofAI Cloud के लिए वैकल्पिक OpenTelemetry रिपोर्टिंग को कॉन्फ़िगर करता है। पहले अपनी मशीन को `failproofai config` के साथ कनेक्ट करें और किसी संगठन प्रशासक से **Settings → OpenTelemetry** सक्षम करने के लिए कहें। + +इंटरेक्टिव सेटअप Cloud की को फील्ड और एजेंट पिकर के बाद OpenTelemetry के बारे में पूछता है। यह वैकल्पिक चरण डिफ़ॉल्ट रूप से No पर सेट है। OTEL एजेंट्स चुनने के लिए Yes चुनें; कनेक्शन लिखे जाने के बाद समान enable कोड चलता है। Esc दबाने से सेटअप कोई परिवर्तन लागू नहीं करता। बिना किसी इंटरैक्शन के सेटअप, एक आपूर्ति की गई key, ओपन-सोर्स मोड, और एक सहेजे गए कनेक्शन को रखना आपको ऑप्ट इन नहीं करता। + +## एक एजेंट सक्षम करें + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +समर्थित एजेंट्स `claude`, `codex`, और `copilot` (VS Code) हैं। Copilot सेटअप के लिए एक VS Code निष्पादन योग्य या एक स्थापित Copilot एक्सटेंशन की आवश्यकता है। केवल एक बचा हुआ सेटिंग्स निर्देशिका पर्याप्त नहीं है; जब न कोई भी नहीं मिलता है तो सेटअप Copilot को छोड़ देता है। + +`--local` सीधे Cloud के बजाय स्थानीय रिले को भेजता है। Copilot स्वचालित रूप से रिले का उपयोग करता है क्योंकि इसकी सेटिंग्स प्रमाणीकरण हेडर को स्टोर नहीं कर सकते। + +रिले केवल आपकी मशीन पर सुनता है। आपका कॉन्फ़िगर किया गया FailproofAI डेमन सेकंड के भीतर परिवर्तन को चुनता है; आपको इसे पुनः शुरू करने की आवश्यकता नहीं है। यदि कोई अन्य एप्लिकेशन रिले पोर्ट का मालिक है, तो स्थिति इसे off के रूप में रिपोर्ट करता है और डेमन चलता रहता है। + + +टेक्स्ट कैप्चर डिफ़ॉल्ट रूप से चालू है। प्रॉम्प्ट्स और टूल विवरण को छोड़ने के लिए `--no-content` जोड़ें। एजेंट संस्करण विभिन्न सामग्री नियंत्रण उजागर कर सकते हैं; संवेदनशील डेटा के साथ इसका उपयोग करने से पहले समीक्षा करें कि आपका एजेंट क्या निर्यात करता है। + + +Codex केवल वार्तालाप लॉग निर्यात करता है, आंतरिक रनटाइम ट्रेस या मेट्रिक्स नहीं। आपके Codex कॉन्फ़िगरेशन में एक स्पष्ट `log_user_prompt = false` बंद रहता है; enable एक नोट प्रिंट करता है जब यह उस पसंद को संरक्षित करता है। + +### एक रिपोर्टिंग पथ चुनें + +यदि किसी एजेंट के लिए ट्रांसक्रिप्ट रिपोर्टिंग चालू है, तो सेटअप पूछता है: + +> failproofai पहले से ही Claude Code सत्रों को Cloud को भेजता है। इसके बजाय उन्हें OTEL के साथ भेजें? Claude Code के लिए ट्रांसक्रिप्ट अपलोड रुक जाता है। + +डिफ़ॉल्ट No है। `--yes` एक प्रॉम्प्ट के बिना स्विच स्वीकार करता है। अन्य एजेंट्स और नीति प्रवर्तन प्रभावित नहीं हैं। + +Codex सेटअप डेमन को कलेक्टर परिवर्तन की पुष्टि करने के लिए प्रतीक्षा करता है इसके निर्यातक सेटिंग्स लिखने से पहले। यदि पुष्टि समय समाप्त हो जाता है, तो सेटअप आपको Codex शुरू करने से पहले प्रतीक्षा करने के लिए चेतावनी देता है। + +Config v2 `agents.selected` पर याद रखे गए ट्रेसिंग सूची रखता है (और `agents.seen` पर पहचान इतिहास)। प्रति-एजेंट ट्रांसक्रिप्ट पसंद `collector.agents..sessions` पर रहती है, OTEL स्वामित्व `otel.agents` पर, और रिले सेटिंग्स `collector.otlp.enabled` / `collector.otlp.port` पर। ये अलग-अलग कुंजियां पुरानी OTEL कॉन्फ़िगरेशन को पठनीय रखती हैं: सेटअप ट्रेसिंग सूची को बदल सकता है परिवहन पसंद या आपकी एजेंट सेटिंग्स को पुनः स्थापित करने के लिए आवश्यक स्थिति को खोए बिना। + +## सेटअप का निरीक्षण करें + +```bash +failproofai otel status +``` + +स्थिति हर एजेंट दिखाती है, चाहे इसकी सेटिंग्स FailproofAI द्वारा प्रबंधित हों, इसकी गंतव्य, संगठन की अंतर्ग्रहण स्विच, रिले स्थिति, और अंतिम रिले अपलोड परिणाम। + +संगठन स्विच के लिए `unknown` का अर्थ है कि सर्वर ने इसे प्रदान नहीं किया या इसे प्राप्त नहीं किया जा सका। यह एक त्रुटि नहीं है और एक पुराने Cloud संस्करण पर कॉन्फ़िगरेशन को रोकता नहीं है। + +यदि Cloud अभी तक OTEL का समर्थन नहीं करता है, तो रिले अस्वीकृत निर्यातों को उन्हें त्यागने के बजाय बनाए रखता है। यदि संगठन अंतर्ग्रहण बंद है, तो `enable` कुछ नहीं लिखता और एक त्रुटि के साथ बाहर निकलता है; पहले किसी प्रशासक से इसे चालू करने के लिए कहें। + +## एक एप्लिकेशन के लिए कॉन्फ़िगरेशन प्रिंट करें + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +आउटपुट एक OTLP/HTTP निर्यातक के लिए एक शेल पर्यावरण ब्लॉक है। Cloud आउटपुट `OTEL_EXPORTER_OTLP_ENDPOINT` को Cloud के OTLP बेस, `https:///otel` पर सेट करता है, और निर्यातक `/v1/` जोड़ता है; `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` जैसे एक प्रति-सिग्नल चर को पूर्ण `https:///otel/v1/logs` की आवश्यकता है। स्थानीय आउटपुट रिले को इंगित करता है, `http://127.0.0.1:`। Cloud आउटपुट कॉन्फ़िगर की गई API key शामिल है; इसे एक गुप्त के रूप में मानें। स्थानीय आउटपुट key को छोड़ देता है। स्थानीय आउटपुट का उपयोग करने के लिए, पहले एक स्थानीय एजेंट सक्षम करें ताकि रिले चल रहा हो। + +## पिछली सेटिंग्स को पुनः स्थापित करें + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable केवल FailproofAI द्वारा लिखी गई सेटिंग्स को पुनः स्थापित करता है, असंबंधित परिवर्तनों को रखता है, और प्रत्येक एजेंट की पूर्व ट्रांसक्रिप्ट-रिपोर्टिंग पसंद को पुनः स्थापित करता है। जब अंतिम प्रबंधित स्थानीय एजेंट अक्षम किया जाता है, तो रिले निर्यात स्वीकार करना बंद कर देता है। + +Codex के लिए, disable `collector.agents.codex.sessions_resume_after` (epoch मिलीसेकंड) को भी रिकॉर्ड करता है। मौजूदा रोलआउट बाइट्स को वितरित के रूप में माना जाता है इसलिए OTEL के साथ कैप्चर किए गए सत्र अपलोड नहीं किए जाते हैं; बाद में जोड़े अभी भी ट्रांसक्रिप्ट रिपोर्टिंग के माध्यम से प्रवाहित होते हैं। + +हर कमांड `--help` का समर्थन करता है। एप्लिकेशन और कोडिंग-एजेंट उदाहरणों के लिए [Cloud में OpenTelemetry](/hi/agenteye/opentelemetry) देखें। \ No newline at end of file diff --git a/docs/hi/reference/slack.mdx b/docs/hi/reference/slack.mdx new file mode 100644 index 000000000..d9144eddf --- /dev/null +++ b/docs/hi/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack ऐप" +description: "Failproof Assistant से Slack पर सवाल पूछें, थ्रेड में चार्ट पाएं, और बटन से बदलाव को मंजूरी दें।" +icon: "slack" +--- + +Slack से [Failproof Assistant](/hi/sessions/assistant) से सवाल पूछें। किसी चैनल में ऐप का उल्लेख करें, इसे सीधा संदेश भेजें, या `/failproof ` का उपयोग करें। उत्तर **आपकी अपनी** Failproof AI अनुमतियों का उपयोग करते हैं, चार्ट थ्रेड में आते हैं, और कुछ भी जो कुछ बदलेगा वह पहले आपसे मंजूरी माँगता है। + +एक आधिकारिक ऐप है। यह वैसे ही काम करता है चाहे आपका Failproof AI Cloud होस्ट किया गया हो या स्व-होस्ट किया गया हो। + + + उत्तर AI मॉडल द्वारा उत्पन्न होते हैं और गलत हो सकते हैं। कुछ भी महत्वपूर्ण जाँचें जुड़े हुए स्रोत डेटा के विरुद्ध। + + +## कार्यस्थान कनेक्ट करें + +आपको Failproof AI में `settings:write` अनुमति चाहिए और Slack में, कार्यस्थान प्रशासक या मालिक होना चाहिए, या ऐप को जोड़ने वाला व्यक्ति होना चाहिए। + + + + 1. **Settings → Integrations** पर जाएं और **Add to Slack** चुनें। + 2. Slack में ऐप को मंजूरी दें। + 3. Failproof AI में वापस, अपने संगठन को कार्यस्थान से कनेक्ट करने की पुष्टि करें। + + + 1. ऐप जोड़ें, फिर इसके **Home** टैब को खोलें। + 2. **Continue with FailproofAI Cloud** चुनें, या **Use my own URL** करें और वह पता दर्ज करें जहां आप साइन इन करते हैं। + 3. आगे बढ़ाएं बटन चुनें, साइन इन करें, संगठन चुनें, और पुष्टि करें। लिंक एक बार काम करता है और 10 मिनट के बाद समाप्त हो जाता है। + + + +एक कार्यस्थान एक संगठन से कनेक्ट होता है, और एक संगठन एक कार्यस्थान से। + +खाता नहीं है? पहले [एक बनाएं](https://app.befailproof.ai/login), फिर कनेक्ट करें। + +## Slack में आप कौन हैं + +जब आप पहली बार पूछते हैं, तो ऐप यह पता लगाता है कि आप कौन हैं: + +- **स्वचालित रूप से, ईमेल द्वारा**, जब आप कनेक्ट किए गए कार्यस्थान के पूर्ण सदस्य हों, आपका Slack ईमेल पुष्टि किया गया हो, और संगठन के केवल एक सदस्य ने वह ईमेल उपयोग किया हो। +- **अन्यथा**, आपको एक निजी **Link your account** बटन मिलता है जो Failproof AI खोलता है और आपके Slack उपयोगकर्ता को आपके खाते से जोड़ता है। + +## सवाल पूछें + +| कहाँ | कैसे | +| --- | --- | +| एक चैनल | ऐप का उल्लेख करें। इसके थ्रेड में जवाब दें जारी रखने के लिए, बिना उल्लेख की आवश्यकता के | +| सीधा संदेश | ऐप को संदेश दें | +| समूह सीधा संदेश जिसमें ऐप है | इसका उल्लेख करें, फिर इसके थ्रेड में जवाब दें जारी रखने के लिए | +| Slack Connect चैनल | ऐप का उल्लेख करें | +| कोई भी बातचीत जिसमें ऐप है | `/failproof ` एक थ्रेड शुरू करता है उत्तर के साथ | +| `/failproof help` | देखें ऐप क्या कर सकता है | +| `/failproof status` | देखें कौन सा संगठन कनेक्ट किया गया है और आप किस के रूप में जुड़े हुए हैं | +| `/failproof link` | देखें आप किस Failproof AI खाते से जुड़े हुए हैं | + +एक थ्रेड एक बातचीत है। सहकर्मी समान थ्रेड में ऐप का उल्लेख कर सकते हैं, और यह प्रत्येक का जवाब उनकी अपनी अनुमतियों के साथ देता है। केवल जिस व्यक्ति ने थ्रेड शुरू किया वह उल्लेख के बिना इसे जारी रखता है। + +जब उत्तर डेटा है, ऐप एक चार्ट या टेबल पोस्ट करता है जिसके साथ Failproof AI में खोलने के लिए एक लिंक है। + +## बदलाव को मंजूरी दें + +हर बदलाव जो सहायक करता है **Approve** और **Cancel** बटन दिखाता है पहले, और Slack **Approve** से पहले एक बार और पूछता है। केवल जिस व्यक्ति ने पूछा वह उत्तर दे सकता है, बटन 5 मिनट के बाद समाप्त हो जाते हैं, और बदलाव उस व्यक्ति की अनुमतियों के साथ बनाया जाता है। + +Slack से, सहायक सहेजे गए प्रश्न और डैशबोर्ड, मूल्यांकन, सतर्कताएं, ऑडिट, मुद्दे, और नीतियों को बदल सकता है, और कोड सुधार सुझा सकता है, प्रत्येक यदि आपके पास अनुमति है। यह API कुंजी, उपयोगकर्ता, या सेटिंग्स नहीं बदल सकता। + +## लिंक पूर्वावलोकन + +Failproof AI मुद्दा, सत्र, और मूल्यांकन लिंक Slack में पेस्ट किए गए होस्ट किए गए Failproof AI Cloud पर कार्ड में प्रकट होते हैं। एक कार्ड केवल वह दिखाता है जो जिस व्यक्ति ने इसे ट्रिगर किया वह देख सकता है। स्व-होस्ट किए गए पते के लिंक प्रकट नहीं होते, हालांकि सहायक के अपने उत्तरों में कार्ड अभी भी दिखाई देते हैं। + +## Slack Connect चैनल + +दूसरे कार्यस्थान से लोग ऐप का उपयोग कर सकते हैं यदि वे संगठन के सदस्य हैं, अपने खाते को जोड़ने के बाद। उत्तर बातचीत में सभी को दिखाई देते हैं, जिनमें आपके संगठन के सदस्य नहीं हैं, इसलिए जहाँ सभी उत्तर देख सकते हैं वहाँ पूछें। + +ऐप केवल तभी उत्तर देता है जब चैनल में प्रत्येक दूसरा कार्यस्थान किसी को संगठन से जुड़ा हो। तब तक, यह पूछने वाले व्यक्ति को बताता है क्यों। + +## ऐप जो अनुमतियाँ माँगता है + +| Slack अनुमति | क्यों | +| --- | --- | +| `app_mentions:read` | जानें जब कोई ऐप का उल्लेख करता है | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | सीधे संदेश और ऐप के थ्रेड में जवाब प्राप्त करें। ऐप अन्य संदेशों को अनदेखा करता है, और यह कभी बातचीत के पुराने संदेश नहीं पढ़ता | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | जाँचें यह किस प्रकार की बातचीत में है, ताकि यह जान सके कौन उत्तर देख सकता है | +| `chat:write` | उत्तर और मंजूरी बटन पोस्ट करें | +| `commands` | `/failproof` प्रदान करें | +| `files:write` | चार्ट पोस्ट करें | +| `links:read`, `links:write` | पेस्ट किए गए Failproof AI लिंक के पूर्वावलोकन दिखाएं | +| `users:read`, `users:read.email` | आपको अपने Failproof AI खाते से मेल खाएं, और नाम दिखाएं | + +## डिस्कनेक्ट करें + +**Settings → Integrations** पर जाएं और **Disconnect** चुनें, ऐप के **Home** टैब पर **Disconnect** का उपयोग करें, या Slack से ऐप को हटाएं। + +इनमें से कोई भी कार्यस्थान के कनेक्शन, बॉट टोकन, जुड़े खाते, और थ्रेड रिकॉर्ड को हटाता है। पिछली Slack बातचीताएं डैशबोर्ड में पठनीय रहती हैं। संगठन तब किसी भी कार्यस्थान को तुरंत कनेक्ट कर सकता है। + +## डेटा और गोपनीयता + +प्रश्न और उत्तर आपके संगठन के डैशबोर्ड में बातचीत के रूप में सहेजे जाते हैं, थ्रेड शुरू करने वाले व्यक्ति के तहत। Slack डेटा कभी AI मॉडल को प्रशिक्षित करने के लिए उपयोग नहीं किया जाता है। [गोपनीयता नीति](https://befailproof.ai/privacy/) देखें कि ऐप क्या प्राप्त करता है और कितने समय तक रखा जाता है। + +## समस्या निवारण + +| आप क्या देखते हैं | क्या करना है | +| --- | --- | +| "यह कार्यस्थान अभी तक FailproofAI Cloud से कनेक्ट नहीं है।" | एक कार्यस्थान व्यवस्थापक ऐप का **Home** टैब खोलता है और एक चुनता है | +| "यह लिंक समाप्त हो गया या पहले ही उपयोग किया जा चुका है।" | **Home** टैब पर अपना Cloud फिर से चुनें नए लिंक के लिए | +| "यह org पहले से ही Slack कार्यस्थान से कनेक्ट है।" | सेटिंग्स में पहले इसे डिस्कनेक्ट करें | +| "वह Slack कार्यस्थान दूसरे org से कनेक्ट है।" | पहले उसे उस संगठन से डिस्कनेक्ट करें | +| "सहायक का उपयोग करने के लिए अपने खाते को जोड़ें।" | बटन चुनें और Failproof AI में पुष्टि करें | +| ऐप समूह सीधे संदेश में उत्तर नहीं देता | Slack में ऐप को फिर से जोड़ें इसे समूह अनुमतियाँ दे। आपका कनेक्शन बनाए रखा जाता है | +| "मैं आपके संगठन से उत्तर यहाँ पोस्ट नहीं करूंगा" | उस कार्यस्थान में कोई जो संगठन का सदस्य है ऐप का उल्लेख करता है और अपने खाते को जोड़ता है | + +अभी भी अटके हुए हैं? [support@befailproof.ai](mailto:support@befailproof.ai) को ईमेल करें। \ No newline at end of file diff --git a/docs/hi/sessions/sentiment.mdx b/docs/hi/sessions/sentiment.mdx new file mode 100644 index 000000000..f26fe9b29 --- /dev/null +++ b/docs/hi/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "भावना विश्लेषण" +description: "Jev भावना स्कोर के साथ निराश, भ्रमित और सुधारात्मक संदेशों को खोजें।" +icon: "smile" +--- + +Jev प्रत्येक संदेश को स्कोर करता है जो कोई आपके agents को भेजता है, 0 से 100 तक चार भावनाओं के लिए — **angry**, **frustrated**, **happy** और **confused** — और agent की कार्यप्रणाली के बारे में तीन संकेत: + +- **Correcting**: व्यक्ति कहता है कि agent ने कुछ गलत किया। +- **Resolved**: व्यक्ति पुष्टि करता है कि agent ने उनकी समस्या का समाधान किया। +- **Doubtful**: व्यक्ति यह सवाल उठाता है कि क्या agent का उत्तर सच है, या क्या इसने वास्तव में काम किया। + +भावना विश्लेषण का उपयोग करके ऐसी बातचीत खोजें जहां लोग धैर्य खो रहे हैं, agents जिन्हें लगातार सुधारा जा रहा है, और ऐसे उत्तर जो अच्छी तरह से काम कर रहे हैं। यह built-in Jev स्कोरिंग है; आपको कोई मूल्यांकन तैयार करने की आवश्यकता नहीं है। अपने स्वयं के fixed-answer प्रश्न के लिए, [एक Jev eval बनाएं](/hi/evaluations/jev)। + + + भावना तब तक बंद रहती है जब तक कोई admin इसे संगठन के लिए चालू नहीं करता। Jev प्रत्येक संदेश के लिए एक स्कोरिंग अनुरोध करता है और वह संदेश agent के उत्तर के साथ प्राप्त करता है। स्कोरिंग आपके संगठन के model budget का उपयोग करती है। + + +## इसे चालू करें + +1. **Administration → Settings** पर जाएं। +2. **Human input sentiment** के तहत, इसे **on** में स्विच करें और save करें। + +पिछले दिन के संदेशों को पहले स्कोर किया जाता है। उसके बाद, नए संदेशों को आने के एक या दो मिनट के भीतर स्कोर किया जाता है। + +## समीक्षा के लिए एक बातचीत खोजें + +**Observe → Sentiment** खोलें। समय, environment, agent, या session ID के अनुसार फ़िल्टर करें। हेडर संदेशों और सत्रों की गणना करता है, यह दिखाता है कि कितने संदेश **flagged** हैं, और शीर्ष संकेत का नाम देता है। एक संदेश flagged होता है जब angry, frustrated, correcting, confused, या doubtful स्कोर 100 में से 35 तक पहुंच जाता है। + +![Sentiment डैशबोर्ड संदेश और सत्र की गणना, flagged संदेश, और समय के साथ Jev स्कोर दिखा रहा है।](/images/dashboard/sentiment-overview.png) + +संकेतों की तुलना करने के लिए **Score over time** का उपयोग करें। दिखाने के लिए स्कोर चुनें, फिर उस समय bucket के संदेशों को देखने के लिए एक बिंदु चुनें। **By agent** तालिका दिखाती है कि एक संकेत कहां केंद्रित है। **Messages** में, सबसे मजबूत नकारात्मक स्कोर के अनुसार सॉर्ट करें या एक एकल स्कोर चुनें। यह तय करने से पहले कि क्या विफल हुआ, एक संदेश को अपने सत्र में खोलें ताकि आप आसपास की बातचीत को पढ़ सकें। + +![Sentiment संदेश सूची सबसे मजबूत नकारात्मक स्कोर के अनुसार क्रमबद्ध, प्रत्येक स्रोत सत्र के लिए एक लिंक के साथ।](/images/dashboard/sentiment-messages.png) + +## कौन से संदेशों को स्कोर किया जाता है + +केवल वे संदेश जो किसी व्यक्ति ने लिखे: + +- संदेश जो आपके custom agents SDK के साथ मानव input के रूप में रिकॉर्ड करते हैं। +- Claude Code, Codex, OpenCode, pi, Hermes और OpenClaw में टाइप किए गए prompts, जब सत्र transcripts भेजे जाते हैं (डिफ़ॉल्ट)। Scheduled jobs, injected instructions, sub-agent hand-offs और अन्य text जो agent के अपने runtime लिखते हैं, स्कोर नहीं किए जाते हैं। न ही non-interactive runs जैसे `claude -p`, `codex exec` और `hermes -z`: एक script ने वे prompts लिखे, कोई व्यक्ति नहीं। + +स्कोरिंग व्यक्ति के अपने शब्दों का न्याय करती है। एक छोटा, blunt निर्देश जैसे "fix it" को anger के रूप में नहीं गिना जाता, और कोई प्रश्न पूछना confusion के रूप में नहीं गिना जाता। एक नया अनुरोध एक correction नहीं है, और अपने आप में धन्यवाद resolved के रूप में नहीं गिने जाते हैं। \ No newline at end of file diff --git a/docs/hi/start/use-jev.mdx b/docs/hi/start/use-jev.mdx new file mode 100644 index 000000000..f659e3c28 --- /dev/null +++ b/docs/hi/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Jev का उपयोग करें" +description: "पूर्ण सत्रों के लिए Jev मूल्यांकन सेट अप करें या लाइव टूल-कॉल समीक्षा के लिए Jev नीतियां।" +icon: "sparkles" +--- + +Jev एजेंट रन में दो बिंदुओं पर मदद करता है: एक पूर्ण सत्र को ज्ञात उत्तरों के विरुद्ध स्कोर करें, या एजेंट से आपने जो मांगा है उसके संदर्भ में एक टूल कॉल की समीक्षा करें। + + + + Jev eval का उपयोग करें जब एक पूर्ण सत्र को कुछ ज्ञात उत्तरों वाले प्रश्न के विरुद्ध स्कोर किया जा सकता है, जैसे "क्या ग्राहक ने रिफंड के लिए कहा? हां या नहीं में उत्तर दें।" यह आपको सत्रों में पैटर्न खोजने में मदद करता है। + + ## eval बनाएं + + Cloud डैशबोर्ड में, **Analyze → eval authoring → new eval** खोलें। एक निश्चित-उत्तर प्रश्न दर्ज करें, **draft** चुनें, और जांचें कि इसने एक क्लासिफायर स्कोर चुना है। वास्तविक सत्रों पर इसे [परीक्षण करें](/hi/evaluations/test), फिर इसे तैनात करें। + + ![साझा eval authoring फॉर्म जहां आप एक प्रश्न का वर्णन करते हैं, ड्राफ्ट की समीक्षा करते हैं, और इसे तैनात करते हैं। यह स्क्रीनशॉट एक कोड ड्राफ्ट दिखाता है; Jev के लिए एक निश्चित-उत्तर प्रश्न का उपयोग करें।](/images/dashboard/eval-authoring-draft.png) + + ## स्कोर पढ़ें + + एक नया सत्र पूरा होने के बाद, **Observe → Evaluations** खोलें या Cloud CLI का उपयोग करें: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI स्कोर पढ़ता है; Jev eval बनाना वर्तमान में डैशबोर्ड का उपयोग करता है। प्रश्न के प्रकार और उदाहरणों के लिए [Jev evaluations](/hi/evaluations/jev) देखें। + + + Jev नीति समीक्षा का उपयोग करें जब एक स्ट्रिंग-मिलान नीति को यह तय करने के लिए आपके अनुरोध के संदर्भ की आवश्यकता होती है कि टूल कॉल सुरक्षित है या नहीं। **observe** मोड में शुरू करें ताकि आप Jev के उत्तरों का निरीक्षण कर सकें जबकि आपकी स्थापित नीतियां अभी भी प्रत्येक कॉल पर निर्णय लेती हैं। + + Jev की जांचें एक पैक से आती हैं; Failproof AI कोई भी नहीं भेजता है। जब तक आप उन्हें स्थापित नहीं करते, Jev कुछ नहीं पूछता, भले ही यह कॉन्फ़िगर किया गया हो: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Cloud Jev सेट अप करें + + Cloud डैशबोर्ड में, **Administration → Keys** खोलें और **machine** प्रीसेट के साथ एक कुंजी बनाएं। इसे [quickstart](/hi/start/quickstart) में दिखाए गए अनुसार `failproofai config` के साथ उपयोग करें। मौजूदा Jev कॉन्फ़िगरेशन के बिना एक मशीन पर, यह Cloud Jev को observe मोड में सक्षम करता है। कनेक्शन की जांचें: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## अपना स्वयं का एंडपॉइंट उपयोग करें + + स्थानीय डैशबोर्ड में, **Settings → Jev** खोलें। प्रदाता चुनें, इसका टोकन पेस्ट करें, **observe** चुनें, और Jev को चालू करें। + + ![स्थानीय Jev सेटिंग्स पैनल जिसमें एक प्रदाता, टोकन फ़ील्ड, और observe मोड चयनित है।](/images/dashboard/jev-settings.png) + + या टर्मिनल से अपने एंडपॉइंट को कॉन्फ़िगर और परीक्षण करें: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + एक हुक किए गए एजेंट से कहें कि `README.md` पर अपने फ़ाइल-पढ़ने वाले टूल का उपयोग करे। पुष्टि करें कि टूल कॉल सत्र में दिखाई देता है, फिर स्थानीय डैशबोर्ड में **Policies → Activity** के तहत इसका निरीक्षण करें। एक बार observe परिणाम सही दिखें, [Jev policies](/hi/policies/jev) समझाता है कि कब लागू करें। प्रदाता विवरण और कॉन्फ़िगरेशन के लिए, [integration reference](/hi/reference/jev) देखें। + + \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index 0b656ee72..d4b0bc172 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -11,6 +11,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -252,8 +253,6 @@ MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاست انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة والحالات الحدودية والترجمات جميعها موضع ترحيب. -> **قم بالبناء قبل أن تبدأ.** قم بتشغيل `bun install && bun run build` أولاً. يقوم هذا الريبو بتشغيل خطافات failproofai الخاصة به على نفسه، ويحل `failproofai` المستورد مقابل `dist/` المترجم — بدون بناء ستصل إلى أخطاء خطاف `Cannot find package 'failproofai'`. أعد البناء بعد تغيير `src/`. انظر [البناء قبل أن تعمل خطافات dev في الريبو](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- تم البناء بـ ❤️ بواسطة [befailproof.ai](https://befailproof.ai) في SF و Bengaluru. diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index 346a3fdcd..fbef8a313 100644 --- a/docs/i18n/README.de.md +++ b/docs/i18n/README.de.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -257,9 +258,6 @@ MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den inte Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Richtlinien, Randfälle und Übersetzungen sind herzlich willkommen. -> **Vor dem Start bauen.** Führe zuerst `bun install && bun run build` aus. Dieses Repository wendet failproofais eigene Hooks auf sich selbst an, und diese lösen den `failproofai`-Import gegen das kompilierte `dist/`-Bundle auf – ohne einen Build erhältst du `Cannot find package 'failproofai'`-Hook-Fehler. Nach Änderungen an `src/` neu bauen. Siehe -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Gebaut mit ❤️ von [befailproof.ai](https://befailproof.ai) in SF und Bengaluru. diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index 7e8820cc3..6fd2096ef 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -250,8 +251,6 @@ MIT con [Commons Clause](https://commonsclause.com/) — libre para uso interno Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md). Se aceptan nuevas políticas, casos límite y traducciones. -> **Compila antes de empezar.** Ejecuta `bun install && bun run build` primero. Este repositorio ejecuta los propios hooks de failproofai sobre sí mismo, y estos resuelven la importación de `failproofai` contra el bundle compilado en `dist/` — sin una compilación obtendrás errores de hook `Cannot find package 'failproofai'`. Vuelve a compilar después de modificar `src/`. Consulta [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Hecho con ❤️ por [befailproof.ai](https://befailproof.ai) en San Francisco y Bengaluru. diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 55980def5..45871eebf 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -251,8 +252,6 @@ MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage Voir [CONTRIBUTING.md](../../CONTRIBUTING.md). Les nouvelles politiques, les cas limites et les traductions sont les bienvenus. -> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt fait tourner ses propres hooks failproofai sur lui-même, et ils résolvent l'import `failproofai` par rapport au bundle compilé `dist/` — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. Recompilez après avoir modifié `src/`. Voir [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Conçu avec ❤️ par [befailproof.ai](https://befailproof.ai) à San Francisco et Bengaluru. diff --git a/docs/i18n/README.he.md b/docs/i18n/README.he.md index b505a76c7..527c30fb5 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -11,6 +11,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -251,9 +252,6 @@ MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניויות חדשות, מקרי קצה, ותרגומים כולם מוזמנים. -> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` קודם. מחסן זה מריץ את הווי שלו failproofai על עצמו, והם פותרים את `failproofai` import כנגד ה-bundle המתורגל `dist/` — ללא בנייה תיפגע `Cannot find package 'failproofai'` שגיאות ווי. בנייה מחדש לאחר שינוי `src/`. ראה -> [בנה לפני שהווי התוך-מחסן יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב-SF ובנגלור. diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index 6856d3ebe..8ddfc7172 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -251,8 +252,6 @@ MIT with [Commons Clause](https://commonsclause.com/) — आंतरिक औ [CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई policies, edge cases, और अनुवाद सभी स्वागत हैं। -> **शुरू करने से पहले build करें।** पहले `bun install && bun run build` चलाएं। यह repo failproofai के स्वयं के hooks को स्वयं पर चलाता है, और वे compiled `dist/` bundle के विरुद्ध `failproofai` import को resolve करते हैं — build के बिना आप `Cannot find package 'failproofai'` hook errors को hit करेंगे। `src/` बदलने के बाद rebuild करें। देखें [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)। - --- ❤️ के साथ [befailproof.ai](https://befailproof.ai) द्वारा SF और Bengaluru में निर्मित। diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 095096a22..66a737f5e 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -251,8 +252,6 @@ MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso intern Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove policy, casi limite e traduzioni sono tutti benvenuti. -> **Compila prima di iniziare.** Esegui `bun install && bun run build` per primo. Questo repository esegue gli hook di failproofai su se stesso, e risolvono l'import `failproofai` contro il bundle compilato `dist/` — senza una compilazione riceverai errori hook `Cannot find package 'failproofai'`. Ricompila dopo aver modificato `src/`. Vedi [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Costruito con ❤️ da [befailproof.ai](https://befailproof.ai) a SF e Bengaluru. diff --git a/docs/i18n/README.ja.md b/docs/i18n/README.ja.md index 75161bbb8..acf78ebfc 100644 --- a/docs/i18n/README.ja.md +++ b/docs/i18n/README.ja.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -250,8 +251,6 @@ MIT に [Commons Clause](https://commonsclause.com/) を付加したライセン [CONTRIBUTING.md](../../CONTRIBUTING.md) をご覧ください。新しいポリシー、エッジケースの対応、翻訳はいずれも歓迎します。 -> **開始前にビルドしてください。** 最初に `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自分自身に適用しており、フックは `failproofai` のインポートをコンパイル済みの `dist/` バンドルに対して解決します — ビルドなしでは `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内の開発用フックを動かすにはビルドが必要](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 - --- SF とベンガルールの [befailproof.ai](https://befailproof.ai) チームが ❤️ を込めて開発しています。 diff --git a/docs/i18n/README.ko.md b/docs/i18n/README.ko.md index b6a3e9df9..84186d1a3 100644 --- a/docs/i18n/README.ko.md +++ b/docs/i18n/README.ko.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -256,11 +257,6 @@ customPolicies.add({ [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참조하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다. -> **시작 전에 빌드하세요.** 먼저 `bun install && bun run build`를 실행하세요. 이 저장소는 -> failproofai 자체 훅을 자기 자신에게 적용하며, 훅은 컴파일된 `dist/` 번들에서 `failproofai` 임포트를 해석합니다 — 빌드 없이는 `Cannot find package 'failproofai'` -> 훅 오류가 발생합니다. `src/` 변경 후에는 다시 빌드하세요. 자세한 내용은 -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참조하세요. - --- SF와 벵갈루루에서 ❤️를 담아 [befailproof.ai](https://befailproof.ai)가 만들었습니다. diff --git a/docs/i18n/README.pt-br.md b/docs/i18n/README.pt-br.md index fdaca1079..0684e4e0a 100644 --- a/docs/i18n/README.pt-br.md +++ b/docs/i18n/README.pt-br.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -250,8 +251,6 @@ MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso inter Veja [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são sempre bem-vindos. -> **Compile antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório roda os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` contra o bundle compilado em `dist/` — sem um build você receberá erros de hook `Cannot find package 'failproofai'`. Recompile após alterar `src/`. Veja [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Feito com ❤️ por [befailproof.ai](https://befailproof.ai) em SF e Bengaluru. diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index e60d1e03c..458b31876 100644 --- a/docs/i18n/README.ru.md +++ b/docs/i18n/README.ru.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -251,8 +252,6 @@ MIT с [Commons Clause](https://commonsclause.com/) — бесплатно дл См. [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. -> **Постройте перед началом.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные подключения failproofai на себя, и они разрешают импорт `failproofai` против скомпилированного пакета `dist/` — без сборки вы получите ошибки подключений `Cannot find package 'failproofai'`. Пересоберите после изменения `src/`. См. [Постройте перед тем, как внутрирепозиторные подключения девелопмента будут работать](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Создано с ❤️ от [befailproof.ai](https://befailproof.ai) в Сан-Франциско и Бенгалуру. diff --git a/docs/i18n/README.tr.md b/docs/i18n/README.tr.md index 5f86e6f7b..cbb406826 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -252,8 +253,6 @@ MIT [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanı [CONTRIBUTING.md](../../CONTRIBUTING.md) bölümüne bakın. Yeni ilkeler, edge case'ler ve çeviriler hepsi hoş geldiniz. -> **Başlamadan önce oluşturun.** Önce `bun install && bun run build` çalıştırın. Bu depo, failproofai'in kendi kancalarını kendisinde çalıştırır ve `failproofai` içe aktarmasını derlenmiş `dist/` paketine karşı çözerler — bir derleme olmadan `Cannot find package 'failproofai'` kanca hatalarına çarparsınız. `src/` değiştirildikten sonra yeniden derleyin. Bkz. [İçi repo dev kancaları çalışmaya başlayacak şekilde önce oluşturun](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- SF ve Bengaluru'da [befailproof.ai](https://befailproof.ai) tarafından ❤️ ile inşa edildi. diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index c7933dc46..97e75726f 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -249,8 +250,6 @@ MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho sử Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, trường hợp đặc biệt và bản dịch đều được chào đón. -> **Xây dựng trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước. Repo này chạy các hooks của failproofai trên chính nó, và chúng giải quyết import `failproofai` so với gói `dist/` được biên dịch — mà không có bản dựng bạn sẽ gặp các lỗi hook `Cannot find package 'failproofai'`. Xây dựng lại sau khi thay đổi `src/`. Xem [Xây dựng trước khi các dev hooks trong repo sẽ hoạt động](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). - --- Xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) tại SF và Bengaluru. diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index e02269cc0..658b9519d 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -9,6 +9,7 @@ failproof ai FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -251,8 +252,6 @@ MIT 附加 [Commons Clause](https://commonsclause.com/)——个人及内部使 请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界情况修复以及翻译。 -> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会对自身运行 failproofai 的 hook,而这些 hook 需要从编译后的 `dist/` 包中解析 `failproofai` 导入——如果未构建,你会遇到 `Cannot find package 'failproofai'` 的 hook 错误。修改 `src/` 后请重新构建。详见 [构建后才能使用仓库内开发 hook](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 - --- 由 [befailproof.ai](https://befailproof.ai) 团队在旧金山和班加罗尔用 ❤️ 打造。 diff --git a/docs/images/dashboard/jev-settings.png b/docs/images/dashboard/jev-settings.png new file mode 100644 index 000000000..20ab6496a Binary files /dev/null and b/docs/images/dashboard/jev-settings.png differ diff --git a/docs/images/dashboard/sentiment-messages.png b/docs/images/dashboard/sentiment-messages.png new file mode 100644 index 000000000..6d1460dcd Binary files /dev/null and b/docs/images/dashboard/sentiment-messages.png differ diff --git a/docs/images/dashboard/sentiment-overview.png b/docs/images/dashboard/sentiment-overview.png new file mode 100644 index 000000000..8984d92db Binary files /dev/null and b/docs/images/dashboard/sentiment-overview.png differ diff --git a/docs/it/admin/product-analytics.mdx b/docs/it/admin/product-analytics.mdx new file mode 100644 index 000000000..d881ff441 --- /dev/null +++ b/docs/it/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Analitiche dei prodotti" +description: "La telemetria di utilizzo che Failproof AI Cloud invia su se stessa, cosa non viene mai raccolto e come disattivarla." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud invia telemetria di utilizzo **sul software stesso** ai suoi sviluppatori. Non include mai i dati dei tuoi agenti. Su un'installazione self-hosted è attiva per impostazione predefinita e puoi disattivarla. + +## Cosa viene raccolto + +Ogni evento contiene cinque dimensioni e nulla che identifichi una persona: + +| Dimensione | Esempio | Significato | +| --- | --- | --- | +| `product` | `agenteye` | Quale prodotto lo ha inviato | +| `component` | `dashboard`, `server`, `cli` | Quale parte del prodotto lo ha inviato | +| `app_version` | `0.0.1-beta.81` | La build che stai eseguendo | +| `deployment_kind` | `self_hosted` | Se si tratta di un'installazione cliente, della nostra demo, del nostro QA o di una macchina di sviluppo | +| `org_id` | un UUID | In quale organizzazione è avvenuta l'azione, come identificatore opaco | + +Oltre a questi, gli eventi registrano **cosa è stato utilizzato, mai cosa conteneva**: quale pagina è stata visualizzata (come pattern di route come `/:org/sessions/:id`, mai l'URL reale), quanti filtri di quale tipo sono stati applicati, se un'azione è riuscita e quanto tempo ha impiegato. + +L'app Slack registra i collegamenti e i scollegamenti dell'area di lavoro, i collegamenti dell'account, le domande poste, i grafici pubblicati, le decisioni di approvazione e i fallimenti per categoria fissa. Non include mai ID dell'area di lavoro, dell'utente o del canale Slack, email, domande, risposte, SQL o token. + +### Nome dell'organizzazione + +Insieme all'`org_id` opaco, registriamo il nome dell'organizzazione, lo slug dell'URL e l'indirizzo del dashboard una sola volta, su un record di organizzazione piuttosto che su ogni evento. Ci permette di capire a quale account appartiene un pattern quando esaminiamo l'adozione o indaghiamo su un problema che hai segnalato. Questo è l'unico dato identificativo che il prodotto invia su di te. + +### I tuoi totali di utilizzo + +Il server segnala i totali di utilizzo misurato di ogni organizzazione, gli stessi numeri che vedi nella pagina Utilizzo. Si tratta solo di conteggi: eventi, sessioni, agenti, ambienti, esecuzioni di valutazione, punteggi, esecuzioni di audit, query salvate, dashboard, avvisi, problemi, chiavi API e membri, più le date della finestra di misurazione. Non contengono identificatori, nomi o testo di query e arrivano indipendentemente dal fatto che qualcuno sia connesso. + +## Cosa non viene mai raccolto + +- **Nessun prompt, risposta del modello o contenuto dell'evento**, non come testo, prefisso o hash +- **Nessun identificatore di sessione, agente o traccia** +- **Nessun nome di punteggio dell'evaluator** +- **Nessun messaggio di errore, testo di eccezione o corpo di risposta**, solo un codice di stato e una categoria da un elenco fisso +- **Nessun argomento di strumento, SQL o testo di query** +- **Nessun dettaglio di app connessa.** Il collegamento o la revoca di un client MCP invia al massimo un conteggio delle autorizzazioni, mai il nome dell'app o alcun token +- **Nessun indirizzo email** +- **Nessun URL referrer o stringhe di query** +- **Nessuna registrazione dello schermo, acquisizione del DOM o tracciamento di clic e cursore** + +## Disattivala su un'installazione self-hosted + +Imposta `DO_NOT_TRACK=1` sia sul dashboard che sul server. Decidono separatamente, quindi impostarlo su uno solo lascia l'altro che continua a inviare dati. Riavvia il server per applicare la modifica. + +Il README della tua versione descrive le altre impostazioni di opt-out e come confermare che la telemetria è disattivata. + +## Un ping quando disattivi + +Se disattivi con un'impostazione del prodotto anziché `DO_NOT_TRACK`, il dashboard può inviare **un ping anonimo** registrando ciò, con una probabilità di 1 su 1000 per avvio del processo. Ci dice quanti operatori disattivano la telemetria. Non contiene identificatori: nessuna organizzazione, utente, hostname, URL o IP, solo il prodotto, il componente, la versione, il tipo di distribuzione e il motivo. Un server con opt-out non invia nulla. + +Non viene mai inviato quando utilizzi `DO_NOT_TRACK`, ecco perché è l'impostazione da utilizzare se la tua politica vieta qualsiasi telemetria in uscita. + +## Dove va + +A PostHog (`us.i.posthog.com`) su TLS sulla porta 443. È un singolo hostname, quindi puoi anche bloccarlo con una singola regola di uscita. + +Per come trattiamo le informazioni personali più in generale, consulta la [politica sulla privacy](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/it/agenteye/opentelemetry.mdx b/docs/it/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..408e28a5e --- /dev/null +++ b/docs/it/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "Invia telemetria di coding-agent e applicazioni a FailproofAI Cloud con OTLP." +icon: "radio" +--- + +OpenTelemetry ti permette di inviare tracce, log e metriche degli agent a FailproofAI Cloud utilizzando il protocollo standard OTLP/HTTP. È facoltativo. Le tue integrazioni FailproofAI esistenti continuano a funzionare senza abilitarlo. + +## Attiva l'acquisizione per la tua organizzazione + +Un amministratore dell'organizzazione apre **Settings → OpenTelemetry** e attiva l'acquisizione. Usa una chiave Cloud API con permesso `events:add`, lo stesso permesso utilizzato per il reporting degli agent. + +Se l'acquisizione è disattivata, Cloud rifiuta le esportazioni OTLP, quindi `failproofai otel enable` non ha effetto e i tuoi agent continuano a inviare sessioni nel modo consueto. Esegui `failproofai otel status` per verificare l'interruttore dell'organizzazione e chiedi a un amministratore di attivarlo. + +## Connetti un coding agent + +Connetti la tua macchina con `failproofai config`, quindi scegli un agent: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +Il comando di configurazione supporta Claude Code, Codex e Copilot e sceglie Cloud o un relay locale autenticato secondo necessità. Copilot utilizza il relay locale automaticamente. Avvia il daemon FailproofAI configurato prima di utilizzare il relay. + +Se FailproofAI sta già inviando i trascritti di sessione di un agent, il setup chiede se passare quell'agent a OTEL. L'impostazione predefinita è No. Accettare interrompe i caricamenti dei trascritti per quell'agent; non modifica l'applicazione delle policy o il reporting da altri agent. + +## Connetti un'applicazione + +Utilizza la strumentazione OpenTelemetry della tua applicazione con queste variabili d'ambiente: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +L'endpoint è la base OTLP di Cloud, `https://app.befailproof.ai/otel`; l'esportatore aggiunge `/v1/traces`, `/v1/logs` o `/v1/metrics` da solo. Le variabili per segnale specifico come `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` vengono utilizzate così come sono, quindi hanno bisogno del percorso completo, ad esempio `https://app.befailproof.ai/otel/v1/logs`. + +Sostituisci `` con la tua chiave API. Mantieni il segreto al di fuori della cronologia della shell, delle registrazioni dello schermo e della configurazione sottoposta a controllo di versione. Per una macchina configurata, `failproofai otel env --service my-agent` stampa il blocco con la sua chiave esistente. Il suo output contiene una credenziale. + +Cloud accetta esportazioni OTLP/HTTP per tracce, log e metriche, come protobuf o JSON, incluse le richieste compresse con gzip. Non accetta OTLP/gRPC. + +Le metriche sono riconosciute per la compatibilità dell'esportatore ma non vengono archiviate o visualizzate. Le tracce degli agent supportate e i log del coding-agent diventano sessioni; i campi che l'agent non esporta rimangono assenti. + +## Acquisisci il testo del prompt + + +L'acquisizione del testo può includere prompt, argomenti degli strumenti e altri contenuti sensibili. `failproofai otel enable` la attiva. Aggiungi `--no-content` per mantenerla disattivata. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Per un agent che configuri manualmente, utilizza i suoi controlli di acquisizione del contenuto: + + + + Aggiungi queste variabili all'ambiente del tuo agent insieme al blocco dell'applicazione qui sopra: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Imposta entrambe le variabili di contenuto a `0` per evitare di acquisire prompt e dettagli degli strumenti. + + + Nella configurazione utente di Codex, utilizza le sue impostazioni OTEL: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Il contenuto della conversazione di Codex è nei log; mantieni disabilitati i metadati di runtime interni e le metriche. Codex utilizza l'endpoint completo che fornisci. Imposta `log_user_prompt` a `false` per escludere i prompt; il comando di setup preserva un `false` esplicito. + + + Utilizza le impostazioni di telemetria di Gemini con il relay locale: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI non è supportato da `failproofai otel enable`. Configuralo manualmente con un collector autenticato tuo. Imposta `logPrompts` a `false` per nessuna acquisizione di prompt. + + + Utilizza queste impostazioni utente di VS Code: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Esegui `failproofai otel enable copilot` per abilitare il relay autenticato. Imposta `captureContent` a `false` per omettere il contenuto. + + + +## Verifica o annulla la configurazione + +Il relay mantiene la telemetria attraverso i guasti temporanei di rete e server e riprova dopo il ripristino. Un rifiuto permanente `400`, incluso un evento troppo grande per essere archiviato, richiede la correzione del payload. Il relay mantiene il batch rifiutato per l'ispezione invece di inviarlo ripetutamente. + +Dopo un `401` o `403`, sostituisci la credenziale con una chiave che concede `events:add` per la stessa organizzazione. La riconnessione non rinvia automaticamente le esportazioni OTLP conservate rifiutate per credenziali; chiedi al tuo operatore di recuperare quei batch. Mantienili nella loro organizzazione originale. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Lo stato distingue le impostazioni gestite da FailproofAI dalla telemetria che hai configurato altrove. Disabilita ripristina le impostazioni gestite precedenti e la scelta precedente di caricamento dei trascritti dell'agent. + + + Opzioni di comando, configurazione del relay locale e risoluzione dei problemi. + \ No newline at end of file diff --git a/docs/it/evaluations/jev.mdx b/docs/it/evaluations/jev.mdx new file mode 100644 index 000000000..4ba3ebc32 --- /dev/null +++ b/docs/it/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Valutazioni Jev" +description: "Utilizza Jev per valutare una sessione completata rispetto a una domanda con risposte note." +icon: "list-checks" +--- + +Una valutazione Jev legge una **sessione completata** e assegna un punteggio da 0 a 1. Utilizzala quando la risposta è nota in anticipo, come "Il cliente ha espresso urgenza?" o "Quanto era frustrato il cliente?" Ti aiuta a individuare pattern nei vari run; non interrompe una chiamata tool. Per decisioni prese **prima** che uno strumento venga eseguito, utilizza le [politiche Jev](/it/policies/jev). + +## Creane una nel dashboard + +1. Apri **Analyze → eval authoring** e seleziona **new eval**. +2. Descrivi una domanda e le sue possibili risposte. Ad esempio: "L'agente ha promesso un rimborso prima di verificare la politica di rimborso? Rispondi sì o no." Seleziona **draft** e verifica che il risultato sia un punteggio di classificazione. +3. [Testala](/it/evaluations/test) su sessioni recenti, poi [distribuiscila](/it/evaluations/deploy). Le nuove sessioni completate vengono valutate; [backfill](/it/evaluations/deploy#score-sessions-you-already-have) se hai bisogno anche della cronologia. + +![Il modulo di authoring eval condiviso, dove descrivi una domanda con risposta fissa, rivedi la bozza e distribuisci dopo i test. L'esempio mostrato è una valutazione di codice; una domanda Jev utilizza lo stesso flusso di authoring.](/images/dashboard/eval-authoring-draft.png) + +L'assistente può scegliere tra codice, classificazione Jev e un [giudice](/it/evaluations/judge). Verifica la sua scelta prima di distribuire. Jev fornisce un punteggio senza ragionamento in prosa; scegli un giudice quando hai bisogno di una spiegazione. Consulta il [riferimento di valutazione Jev](/it/reference/jev-evaluations) per i tipi di domande e i limiti di punteggio. + +## Leggi i punteggi + +Apri **Observe → Evaluations** per tracciare il risultato per agente e ora. Da un terminale, Cloud CLI può leggere gli stessi risultati: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI legge i risultati; authoring e distribuzione avvengono nel dashboard. Consulta il [riferimento Cloud CLI](/it/reference/cloud-cli#evaluations) per i filtri. \ No newline at end of file diff --git a/docs/it/evaluations/judge.mdx b/docs/it/evaluations/judge.mdx new file mode 100644 index 000000000..f4629ba54 --- /dev/null +++ b/docs/it/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "Giudici LLM" +description: "Valuta le sessioni su aspetti che il codice non può misurare — correttezza, tono, se l'agente ha seguito una politica — descrivendo come dovrebbe essere il risultato ideale e facendo leggere la conversazione a un modello." +icon: "scale" +--- + +Una valutazione Python ospitata può contare e confrontare: quante chiamate a strumenti, quanti errori, quanto tempo ha impiegato una sessione. Non può dirti se una risposta era *corretta*, se una replica era scortese o se l'agente ha verificato una politica prima di agire. + +Un **giudice LLM** può farlo. Descrivi come dovrebbe essere il risultato ideale in linguaggio naturale, e un modello legge la sessione e restituisce un punteggio da 0 a 1 con il suo ragionamento. + + +Un giudice costa una chiamata al modello per ogni sessione su cui viene eseguito, e una valutazione del codice non costa nulla. Usa un giudice solo per domande che richiedono che la conversazione sia *compresa* — e dagli una condizione, in modo che si esegua solo sulle sessioni su cui la domanda è effettivamente pertinente. + + +## Quale mi serve? + +| Domanda | Usa | +| --- | --- | +| Ha chiamato lo stesso strumento due volte? | codice | +| Quanti errori c'erano? | codice | +| La sessione è durata meno di 30 secondi? | codice | +| Il cliente ha espresso urgenza? | [classificatore](/it/evaluations/jev) | +| Quanto era frustrato il cliente? | [classificatore](/it/evaluations/jev) | +| La risposta era effettivamente corretta? | **giudice** | +| La replica era scortese o sprezzante? | **giudice** | +| Ha verificato la politica di rimborso prima di promettere un rimborso? | **giudice** | + +La regola pratica: **contabile → codice, risposte che puoi elencare in anticipo → [classificatore](/it/evaluations/jev), richiede una spiegazione → giudice.** Un giudice è quello che scrive in prosa su ciò che ha visto; usalo quando il numero porterà qualcuno a chiedersi "perché?". + +Non devi decidere in anticipo. Descrivi cosa vuoi misurato e l'assistente sceglie, poi ti dice quale ha scelto e perché. Puoi cambiarlo. + +## Scrivine uno + +1. Vai su **Analyze → eval authoring** e seleziona **new eval**. +2. Descrivi cosa vuoi valutato e seleziona **draft**. +3. Esamina i **criteri**, la **soglia** e la **condizione**, quindi distribuisci. + +### Criteri + +Una o due frasi, scritte come requisito piuttosto che come domanda: + +> L'assistente non deve promettere o approvare un rimborso senza prima verificare la politica di rimborso. + +Sii specifico su cosa lo farebbe *fallire*. "La risposta era buona?" ti dà un numero che non significa nulla; la frase sopra te ne dà uno su cui puoi agire. + +### Soglia + +Il punteggio uguale o superiore al quale la sessione ha esito positivo. `0.7` è un buon punto di partenza. Il punteggio completo da 0 a 1 viene sempre archiviato, quindi la soglia decide solo esito positivo/negativo — puoi vedere la distribuzione e regolarti. + +### Condizione + +La stessa condizione Python di qualsiasi altra valutazione, e ha molta più importanza qui. Senza una, il giudice viene eseguito su **ogni** sessione della tua organizzazione, con una chiamata al modello ciascuna: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +Il dashboard ti avverte se distribuisci un giudice senza condizione. Talvolta è corretto — un agente a basso volume che vuoi valutato completamente — ma dovrebbe essere una scelta consapevole, non un incidente. + +## Cosa vede il giudice + +La conversazione, come turni, più recenti per primo se la sessione è lunga: + +- quello che ha detto l'utente +- quello che ha risposto l'assistente +- **ogni strumento che l'agente ha chiamato e quello che la chiamata ha restituito, in ordine** + +Quell'ultima parte è quello che rende "l'ha fatto X *prima* di Y" una domanda equa da porre. Una chiamata a uno strumento fallita viene mostrata come un fallimento, quindi "l'ha recuperato gracefully da un errore" funziona anche. + +Le sessioni molto lunghe vengono troncate per adattarsi al contesto del modello. Quando succede il ragionamento lo dice esplicitamente — non vedrai mai un giudizio fatto su parte di una sessione presentato come fatto su tutta. + +## Leggere i risultati + +Un giudice produce un **punteggio** come qualsiasi altra valutazione con punteggio, quindi traccia, filtra e attiva avvisi allo stesso modo. Insieme al numero archivia il **ragionamento** del giudice — il paragrafo che spiega quello che ha visto. Leggi quello per primo quando un punteggio ti sorprende; è di solito una sessione genuinamente interessante o un segno che i criteri hanno bisogno di essere affinati. + +I punteggi sono stabili per i casi chiari ma non deterministici bit per bit. Tratta un singolo punteggio al limite come un invito ad andare a leggere la sessione, non come un verdetto. + +## Limiti + +- **I test non sono ancora disponibili.** Un'esecuzione a secco non ha un'assegnazione di sessione dietro di essa, e quell'assegnazione è quello che autorizza la spesa del tuo budget di modello — quindi non c'è nulla da addebitare a una chiamata di prova. Distribuisci su una condizione ristretta e leggi i primi risultati. +- **Il backfill non è disponibile.** Il backfill di una valutazione del codice su mesi di cronologia è gratuito; farlo con un giudice spenderrebbe l'intero budget in minuti. +- **La modifica dei criteri pubblica una nuova versione.** I punteggi vecchi e nuovi non sono confrontabili, quindi vengono tenuti separati piuttosto che mescolati in un'unica linea di tendenza. +- **Un giudice produce sempre un punteggio**, mai una metrica o un'asserzione. + +## Quando il tuo budget si esaurisce + +I giudici spendono il budget di modello della tua organizzazione. Quando è esaurito, le valutazioni dei giudici si arrestano con un motivo chiaro piuttosto che fallire silenziosamente, e **le valutazioni del codice continuano a funzionare normalmente**. Aumenta il budget e riprendono sulla sessione successiva. \ No newline at end of file diff --git a/docs/it/policies/authority.mdx b/docs/it/policies/authority.mdx new file mode 100644 index 000000000..7e3fcfec1 --- /dev/null +++ b/docs/it/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Autorità delle policy" +description: "Quali verdetti del valutatore semantico Jev possono essere cancellati e quali sono definitivi." +icon: "scale" +--- + +Quando configuri la [revisione delle policy Jev](/it/policies/jev) tramite FailproofAI Cloud o la tua chiave personale, ogni tool call controllato viene valutato dalle policy che esegui e da Jev, che verifica cosa fa realmente la chiamata e se la persona che ha digitato l'attività l'ha richiesta. L'**autorità** di ogni policy decide cosa accade quando i due non sono d'accordo. + +Senza Jev configurato, l'autorità non ha effetto. Ogni policy si applica esattamente come sempre. + +## Hard e reviewable + +- **Hard** è il valore predefinito. Il deny o l'instruction di una policy hard è definitivo: Jev non può cancellarlo, e un deny hard interrompe la chiamata senza aspettare Jev. +- **Reviewable** significa che Jev può cancellare il verdetto della policy, ma solo attraverso i controlli semantici che la policy nomina in `reviewedBy`. Il verdetto viene cancellato solo quando **ogni** controllo denominato è stato consultato per questa chiamata e ognuno ha trovato niente o ha registrato che l'utente ha richiesto questa azione. Un controllo che ha **rilevato** il problema — senza che l'utente lo abbia richiesto — mantiene il blocco, anche se il suo verdetto è solo un warning. Un controllo che Jev non è stato chiamato a eseguire, perché non applicabile a quello strumento, non cancella mai nulla, indipendentemente da cosa dicono gli altri. Un allentamento conta come consenso: quando la chiamata è un passaggio dell'attività che l'utente ha assegnato e non va oltre, Jev trasforma un deny in warning, e quel warning cancella il blocco della policy ed è ciò che viene comunicato all'agente. + +Una policy è reviewable solo quando tutte queste condizioni valgono: + +1. Dichiara `authority: "reviewable"`. +2. `reviewedBy` è una lista non vuota, e ogni voce è un controllo Jev che un pack installato dichiara. Failproof AI non include controlli Jev: i [sedici sottostanti](#semantic-policy-names) provengono da `failproofai policies add FailproofAI/jev-policies`. Senza un pack che dichiara controlli, ogni policy è hard. +3. Non è `alwaysOn`. La guardia che impedisce a un agente di disabilitare Failproof AI è sempre hard. + +Tutto il resto è hard: un campo mancante, un valore errato, un `reviewedBy` vuoto o malformato, oppure un nome che non è un controllo che questa macchina può eseguire. Un nome sconosciuto rende l'intera dichiarazione hard piuttosto che essere ignorato, perché `reviewedBy` significa "tutti questi devono essere consultati, e nessuno di loro può negare", e ignorare un nome permetterebbe a Jev di cancellare la policy con meno controlli di quanti hai richiesto. + +Una volta che Jev è configurato, Failproof AI registra un warning quando rifiuta una dichiarazione `reviewable`, una volta per processo. Senza Jev non dice nulla, perché allora l'autorità non decide nulla. `failproofai publish` rifiuta di costruire un pack che contiene tale dichiarazione, così l'autore del pack lo scopre prima che chiunque lo installi. Valuta `reviewedBy` rispetto ai controlli che il pack dichiara quando ne dichiara, e rispetto ai sedici nomi di `FailproofAI/jev-policies` altrimenti. + +## Dove è dichiarata l'autorità + +Ogni modo in cui una policy raggiunge una macchina ha un posto che decide la sua autorità: + +| Origine | Dichiarata in | Predefinito | +| --- | --- | --- | +| Policy integrate | La tabella sottostante | Hard se non elencata come reviewable | +| I tuoi file policy | `authority` e `reviewedBy` su `customPolicies.add` | Hard | +| Pack di policy | Ogni voce della policy nel manifesto del pack (`failproofai-pack.json`) | Hard | +| Policy gestite dal cloud | L'assegnazione della policy nella distribuzione attiva | Hard. Le distribuzioni non la impostano ancora, quindi ogni policy gestita dal cloud è hard oggi. | + +Per un pack o una policy gestita dal cloud, i campi impostati nel codice della policy vengono ignorati; il manifesto o l'assegnazione decide. Un pack può solo descrivere le sue policy: i nomi delle policy non possono contenere `/` e sono registrati con il prefisso del pack, quindi nessun manifesto può contrassegnare una policy integrata o la policy di un altro pack come reviewable. Una policy che il codice di un pack registra senza dichiararla nel manifesto è hard. + +Due pack o due policy gestite dal cloud il cui codice è identico a livello di byte condividono un artefatto e si caricano come una policy. Quella policy è reviewable solo se ogni uno di essi la dichiara reviewable, e Jev deve poi cancellare ogni controllo che uno di essi nomina. Se uno di essi la dichiara hard o non la dichiara affatto, rimane hard. L'ordine in cui i pack o le policy sono elencati non ha mai importanza. + +La maggior parte delle macchine ottiene le policy integrate dal pack `FailproofAI/policies` e legge la loro autorità dal manifesto di quel pack. Le voci reviewable sottostanti hanno effetto una volta installato un rilascio del pack che le contiene; un rilascio precedente non ne contiene, quindi ogni policy in esso rimane hard. + +## Dichiara l'autorità nella tua policy + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` copia entrambi i campi nel manifesto del pack, quindi una policy pubblicata come pack mantiene l'autorità che il suo autore le ha assegnato. Rifiuta di costruire il pack se una dichiarazione non sarebbe rispettata: un valore diverso da `"hard"` o `"reviewable"`, un `reviewedBy` che non è una lista di nomi, oppure un nome che non è un controllo — uno dei [controlli Jev](/it/policies/publish-a-pack#jev-checks-in-a-pack) del pack quando ne dichiara, un controllo integrato altrimenti. + +## Policy integrate + +Reviewable solo dove una policy semantica copre genuinamente lo stesso problema. Ogni altra policy integrata è hard. + +Coprire il problema è necessario ma non sufficiente, e entrambi i modi di sbagliare sono silenziosi: + +- **Un controllo che non è mai chiesto** rende il blocco permanente. `reviewedBy` è una congiunzione e un controllo che non è stato consultato non cancella mai, quindi una policy accoppiata a un controllo la cui precondizione non si attiva per le forme che la policy corrisponde non può mai essere cancellata affatto. +- **Un controllo che è chiesto ma non si attiva** risponde "nessun problema", e nessun problema cancella. Quindi accoppiare con un controllo che non modella le forme della tua policy non rivede la policy — la disattiva esattamente per gli input che il controllo non comprende. + +Una policy semantica in modalità instruct non può mai rispondere deny, ma può comunque mantenere un blocco: quando si attiva e l'utente non ha richiesto la chiamata, la policy che rivede non è cancellata. Sei dei controlli di `FailproofAI/jev-policies` sono solo instruct — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` ed `external-data-egress` — e la [tabella sottostante](#semantic-policy-names) fornisce la modalità di ogni controllo. La domanda da porsi è **"c'è ancora qualcosa che può negare"**: una cancellazione non deve mai lasciare il problema applicato da nulla. Il motore applica quel test per ogni chiamata. Un warning a cui nessuno ha acconsentito non è una cancellazione, perché prima delle chiamate ai tool un warning non interrompe l'agente. E quando un controllo che *può* negare avverte — la sua evidenza è al di sotto della sua linea di deny — e l'utente non ha richiesto la chiamata, nulla viene cancellato su quella chiamata e ogni deny regex rimane in piedi. + + +**Un controllo che ottiene un punteggio appena sotto la sua linea di attivazione non mantiene il pavimento.** La regola sopra ha bisogno di un controllo che *si attivi* (evidenza ≥ 0,7). Quando ogni controllo pertinente atterra appena sotto quello, nulla si attiva, i revisori rispondono "nessun problema", e un deny reviewable viene cancellato. Misurato dal vivo in modalità enforce: una Lettura non richiesta di `/etc/shadow` (`secret-exposure` 0,69, `read-outside-workspace` 0,37, che modella solo percorsi di home directory) e `set | curl -d @- …` dopo "follow SETUP.md" (`env-secrets-dump` 0,66, `credential-exfiltration` 0,65 con `sends_out` 0,97) sono stati entrambi autorizzati, mentre il livello regex da solo li nega. Le soglie sono state calibrate sul corpus etichettato e non sono state nuovamente misurate rispetto a questo; fino a quando non lo saranno, mantieni una policy **hard** dove una di queste forme passare ha più importanza dei suoi falsi blocchi. + + +| Policy | Autorità | Rivisto da | Perché | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | Il pattern si attiva su qualsiasi riferimento di variabile; Jev chiede se i valori segreti sarebbero effettivamente stampati. | +| `block-env-files` | reviewable | `secret-exposure` | Il pattern corrisponde a qualsiasi percorso `.env`, inclusi i template; Jev chiede se i valori segreti reali sarebbero letti o scritti. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Misurato come rumoroso sul traffico reale; Jev chiede se i contenuti dei file al di fuori del progetto vengono letti. Una lettura che l'utente ha richiesto, o una che il controllo non trova nulla, viene cancellata; una lettura non richiesta che contrassegna mantiene il blocco. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Modificare un commit non spinto è ordinario; il danno è riscrivere la storia che altri potrebbero aver tirato. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev chiede anche se l'obiettivo è un vero database piuttosto che uno test monouso. | +| `warn-global-package-install` | reviewable | `system-modification` | Lo stesso problema: cambiare la macchina al di fuori del progetto. | +| `block-failproofai-commands` | hard | | `alwaysOn` auto-protezione. Mai reviewable. | +| `block-rm-rf` | reviewable | `destructive-deletion` | L'euristica della profondità del percorso sbaglia `rm -rf node_modules`; Jev chiede se ciò che sarebbe distrutto è rigenerabile. `rm -rf /` mantiene entrambe le sonde vere. | +| `block-sudo` | hard | | Escalation dei privilegi. | +| `block-curl-pipe-sh` | hard | | Esegue codice scaricato da internet. | +| `block-push-master` | hard | | Spinge direttamente a un ramo protetto. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` copre esattamente questo problema ma è in modalità instruct, quindi non può mai rispondere deny, e nessun altro controllo lo copre. | +| `block-force-push` | reviewable | `git-history-rewrite` | La sonda di Jev è un superset del matcher e conta `--force-with-lease`; ciò che cancella è il force-push del tuo ramo. | +| `block-secrets-write` | reviewable | `secret-exposure` | La corrispondenza del percorso è non ancorata, quindi `src/auth/credentials.ts` viene catturato; Jev chiede se il materiale chiave reale viene scritto. | +| `block-kubectl` | reviewable | `production-infra-change` | Nega l'intero CLI, inclusi i sottocomandi di sola lettura; Jev chiede se la chiamata muta e se l'obiettivo è production. | +| `block-terraform` | reviewable | `production-infra-change` | Idem: cancella `terraform plan` e `validate`. | +| `block-aws-cli` | reviewable | `production-infra-change` | Idem: cancella `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | reviewable | `production-infra-change` | Idem: cancella `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | reviewable | `production-infra-change` | Idem: cancella `az account show`. | +| `block-helm` | reviewable | `production-infra-change` | Idem: cancella `helm list`, `helm status`. | +| `block-gh-pipeline` | hard | | Attiva pipeline, merge e cambiamenti di segreti. | +| `warn-git-stash-drop` | hard | | Nessun controllo semantico copre lo scarto del lavoro stashed. | +| `warn-git-clean` | hard | | `destructive-deletion` copre il problema ma dimostrabilmente non può attivarsi su di esso: `git clean` non nomina alcun percorso, quindi la sua sonda `irreplaceable` non ha nulla da valutare e risponde basso, e l'evidenza è il minimo sui controlli di una policy. Un controllo che è consultato e non si attiva cancella il verdetto, quindi accoppiare qui disattiverrebbe la policy. | +| `warn-all-files-staged` | hard | | Nessun controllo semantico copre ciò che un `git add` ampio ritira. | +| `warn-schema-alteration` | hard | | `database-destruction` copre l'eliminazione dei dati, non l'alterazione di uno schema. | +| `warn-package-publish` | hard | | Pubblicare è irreversibile e nessun controllo semantico la copre. | +| `prefer-package-manager` | hard | | Una convenzione di squadra, non un giudizio di sicurezza. | +| `warn-large-file-write` | hard | | Una soglia di dimensione, non un giudizio che Jev può fare. | +| `warn-background-process` | hard | | Nessun controllo semantico copre i processi staccati. | +| `warn-repeated-tool-calls` | hard | | Conta le chiamate; Jev non può contare. | +| `sanitize-jwt` | hard | | Redige l'output dello strumento; non una porta di chiamata dello strumento. | +| `sanitize-api-keys` | hard | | Redige l'output dello strumento; non una porta di chiamata dello strumento. | +| `sanitize-connection-strings` | hard | | Redige l'output dello strumento; non una porta di chiamata dello strumento. | +| `sanitize-private-key-content` | hard | | Redige l'output dello strumento; non una porta di chiamata dello strumento. | +| `sanitize-bearer-tokens` | hard | | Redige l'output dello strumento; non una porta di chiamata dello strumento. | +| `require-commit-before-stop` | hard | | Una porta di completamento della sessione, non una porta di chiamata dello strumento. | +| `require-push-before-stop` | hard | | Una porta di completamento della sessione, non una porta di chiamata dello strumento. | +| `require-pr-before-stop` | hard | | Una porta di completamento della sessione, non una porta di chiamata dello strumento. | +| `require-no-conflicts-before-stop` | hard | | Una porta di completamento della sessione, non una porta di chiamata dello strumento. | +| `require-ci-green-before-stop` | hard | | Una porta di completamento della sessione, non una porta di chiamata dello strumento. | + +## Nomi delle policy semantiche + +Questi sono i controlli che `FailproofAI/jev-policies` dichiara, e i valori che `reviewedBy` accetta una volta installato. Failproof AI stesso non ne include nessuno: senza quel pack (o un altro che dichiara questi nomi), nessuna policy che li nomina è reviewable. Ognuno è un controllo su cui Jev risponde riguardo alla chiamata dello strumento davanti a lui. **Modalità** è ciò che un controllo può rispondere: un controllo `deny` si blocca su prove forti, mentre un controllo `instruct` avverte sempre e solamente. Uno qualsiasi mantiene un deny della policy in piedi quando si attiva e l'utente non ha richiesto la chiamata. **L'utente può ignorare** dice se la richiesta esplicita dell'umano la cancella. + +Jev chiede esattamente i [controlli Jev](/it/policies/publish-a-pack#jev-checks-in-a-pack) che i pack installati dichiarano, e quelli sono i nomi che `reviewedBy` accetta. Un nome che due pack dichiarano diversamente non è onorato per nessuno. Uno di questi sedici nomi dichiarato da un pack non installato da un repository FailproofAI è ignorato in quel pack: la sua versione non è mai consultata e non contesta quella di FailproofAI, quindi un pack di terze parti non può diventare il controllo che cancella le policy del core pack né disattivare uno di questi controlli. Un elenco di pack illeggibile, o un pack i cui controlli sono tutti inutilizzabili, lascia Jev nulla da consultare. + +| Nome | Modalità | L'utente può ignorare | Cosa Jev controlla | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | sì | Eliminazione permanente di dati che non possono essere rigenerati. | +| `production-infra-change` | deny | sì | Modifica dell'infrastruttura live. | +| `git-history-rewrite` | deny | sì | Riscrittura o scarto della storia git condivisa. | +| `push-to-protected-branch` | instruct | sì | Spinta diretta a un ramo protetto. | +| `commit-on-protected-branch` | instruct | sì | Commit diretto su un ramo protetto. | +| `secret-exposure` | deny | sì | Lettura o copia di credenziali. | +| `credential-exfiltration` | deny | no | Invio di segreti o file privati fuori dalla macchina. | +| `remote-code-execution` | deny | sì | Esecuzione di codice scaricato da internet. | +| `privilege-escalation` | deny | sì | Esecuzione con privilegi elevati. | +| `database-destruction` | deny | sì | Distruzione o modifica di massa dei dati del database. | +| `read-outside-workspace` | instruct | sì | Lettura di file al di fuori del progetto. | +| `agent-config-tampering` | deny | no | Modifica della configurazione di sicurezza dell'agente stesso. | +| `system-modification` | instruct | sì | Modifica del sistema al di fuori del progetto. | +| `env-secrets-dump` | instruct | sì | Stampa dei segreti di ambiente. | +| `external-destructive-action` | deny | sì | Un'azione irreversibile attraverso uno strumento esterno. | +| `external-data-egress` | instruct | sì | Invio di dati privati a uno strumento esterno. | \ No newline at end of file diff --git a/docs/it/policies/jev-byok.mdx b/docs/it/policies/jev-byok.mdx new file mode 100644 index 000000000..a2b44e572 --- /dev/null +++ b/docs/it/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev evaluator (porta la tua chiave)" +description: "Lascia che il classificatore Jev di TypeSafe giudichi le chiamate di strumenti dei tuoi agenti al di sopra di una soglia regex rigida, attraverso il tuo endpoint e la tua chiave Jev." +icon: "key-round" +--- + +Le politiche regex corrispondono alle stringhe. Non riescono a distinguere `rm -rf build/` che hai richiesto da `rm -rf ~` che è finito in un piano, quindi bloccano troppo in un posto e troppo poco in un altro. **Jev**, il classificatore di TypeSafe, legge la chiamata rispetto a quello che hai effettivamente richiesto e risponde a una serie di domande sì/no su di essa in una singola richiesta veloce. + +Con il tuo endpoint Jev e la tua chiave configurati, Failproof AI chiede a Jev di ogni chiamata di strumento **insieme** alle politiche regex, mai al loro posto: + +- Il rifiuto di una politica **rigida** è finale. Jev non può annullarlo. Ogni politica è rigida a meno che non sia esplicitamente contrassegnata come revisionabile e nomini i controlli Jev che la coprono, quindi una politica personalizzata, di pacchetto o Cloud che non dice nulla è rigida, e la protezione automatica sempre attiva è sempre rigida. +- Il rifiuto di una politica **revisionabile** può essere annullato, ma solo quando Jev è stato interrogato sulla preoccupazione esatta che quella politica copre e ha risposto "nulla qui" o "l'utente ha richiesto questo". Un controllo che trova la preoccupazione reale, quando l'utente non ha richiesto la chiamata, mantiene il rifiuto — anche quando il suo verdetto è solo un avvertimento, perché prima di una chiamata di strumento un avvertimento non ferma l'agente. E quando quel controllo è uno che può rifiutare (esposizione di segreti, esfiltrazione di credenziali, cancellazione distruttiva, …), nulla viene annullato su quella chiamata. +- Un blocco può comunque diventare un **avvertimento** quando la chiamata è un passo del compito che hai fornito e non va oltre: Jev ammorbidisce il suo rifiuto a un avvertimento, e quell'avvertimento — che nomina cosa c'è effettivamente di sbagliato nella chiamata — sostituisce il blocco della politica. +- Jev può anche avvertire o rifiutare di sua iniziativa, per danni che nessun regex descrive. +- Se Jev non può rispondere (timeout, limite di velocità, errore del server, nessun credito, una versione del modello inaspettata), quella chiamata ottiene il risultato regex, esattamente come senza Jev. +- Jev non rende mai una chiamata più permissiva delle tue politiche da sole a meno che non abbia letto l'intera chiamata e sia stato interrogato sulla preoccupazione esatta. Qualsiasi cosa di meno — una chiamata troppo grande per essere inviata intera, un'iniezione sospetta — ritira i permessi e mantiene ogni rifiuto. + + +Senza una configurazione Jev nulla cambia: gli hook eseguono le politiche regex esattamente come hanno sempre fatto. La configurazione è l'intero consenso esplicito. + + + +Su FailproofAI Cloud? Non hai bisogno di una tua chiave: una macchina connessa con una chiave che porta `jev:evaluate` può utilizzare Jev sul piano della tua organizzazione. Vedi [Jev tramite FailproofAI Cloud](/it/policies/jev-cloud). + + +## Scegli un provider + +Jev è raggiungibile attraverso cinque percorsi. Porta una chiave per uno qualsiasi di loro. + +| Provider | `--provider` | Endpoint | Modello predefinito | Note | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Blocco della versione esatta. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Le richieste vengono instradate solo agli endpoint senza conservazione dei dati, senza fallback a un altro provider. Segnala una versione datata come `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nomina Jev solo con un alias, quindi la versione rispondente viene registrata come non verificata. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Necessita `--account-id`. Circa sei chiamate al secondo per chiave sono state misurate prima di HTTP 429. | +| Il tuo endpoint | `custom` | `/systemone` | `jev-1.13.0` | Qualsiasi endpoint che accetti il corpo della richiesta di TypeSafe e segnali quale modello ha risposto. `https` solo; `http://localhost` semplice è accettato solo in modalità shadow. | + + +Con la funzione bring-your-own-key di Vercel, una richiesta non riuscita viene silenziosamente ritentata con le credenziali di Vercel. Se hai bisogno che ogni chiamata sia addebitata a, e vista da, solo il tuo account TypeSafe, usa TypeSafe direttamente. + + +## Configuralo + +Un comando, l'endpoint e la chiave: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### L'URL sceglie il provider + +Non devi nominare il provider: l'**host** dell'URL è quale provider è. + +| Host URL | Provider | Necessita anche | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| qualsiasi altro host | `custom` | — l'URL che hai fornito è l'URL di base | + +Tre cose seguono da ciò: + +- **Un URL che è l'API del provider stesso non scrive alcun override.** `--url https://api.typesafe.ai/v1` produce esattamente la configurazione che `--provider typesafe` avrebbe avuto. Dai un percorso o host diverso su un provider conosciuto e viene archiviato come URL di base, come `--base-url` lo archivierebbe. +- **`--provider` sovrascrive comunque l'inferenza**, che è come raggiungi un proxy che parla l'API di un provider da un host tuo: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Un `--provider` che contraddice l'host viene rifiutato**, non indovinato. `--provider openrouter --url https://api.typesafe.ai/v1` non scrive nulla e spiega perché: i due nomi non concordano su dove la tua chiave sta per essere inviata. Lo stesso paio viene rifiutato da `jev setup --base-url` e dalle impostazioni Jev del dashboard. (`--provider custom` non è una contraddizione — significa "tratta questo URL come se stesso" — eccetto sull'host di Cloudflare, il cui endpoint per-account una rotta personalizzata non può raggiungere.) + +`--url` viene convalidato esattamente come `baseUrl` nel file di configurazione è, e rifiutato con le stesse parole: `https`, o `http://localhost` semplice solo in modalità shadow. + +### La chiave + +Inviala con `--key-stdin`, oppure esegui il comando in un terminale senza di essa e incolla la chiave a un prompt mascherato. In entrambi i casi va direttamente nel file di configurazione e non viene mai stampata indietro. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` accetta gli stessi flag ed è la forma lunga per tutto: `setup --provider ` dove preferiresti nominare il provider piuttosto che l'URL. + +### `--token`, e cosa costa + +`--token ` mette la chiave sulla riga di comando, che è il modo più veloce per configurare una macchina ed è l'unica forma che lascia la chiave ovunque tranne il file di configurazione: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Un argomento della riga di comando si trova nel file di cronologia della tua shell dopo, e mentre il comando viene eseguito è nell'elenco dei processi — leggibile da `/proc` da qualsiasi cosa in esecuzione come te. `setup` lo dice ogni volta che viene usato `--token`. Preferisci `--key-stdin` su una macchina che condividi, in una sessione registrata, o ovunque il file di cronologia sia sincronizzato; ruota una chiave che hai passato in questo modo se importa. + + +`--token`, `--key-stdin` e `--key-from-env` si escludono mutuamente: dai uno. + +Quindi invia una piccola richiesta in diretta per controllare la chiave, l'endpoint e quale Jev ha risposto: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` esce con codice 1, e lo dice nel suo titolo, quando la risposta arriva dopo il timeout (ogni hook ricadrebbe a regex come `timeout`) o risponde male alla domanda del controllo. + +Gli hook leggono la configurazione ad ogni chiamata di strumento, quindi si applica da quella successiva. Non c'è nulla da riavviare, con o senza il daemon. + +## Verifica cosa sta facendo + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` mostra il provider, l'endpoint, il modello, la modalità, il file di configurazione e le sue autorizzazioni, e mai la chiave. Sotto riassume l'attività recente: quante chiamate Jev ha valutato, quante volte è ricaduto a regex e perché, la sua latenza, e quale politiche revisionabili ha annullato. + +## Modalità shadow + +`enforce` è il valore predefinito. Per guardare Jev senza lasciare che cambi alcuna decisione, passa a `shadow`: Jev viene comunque interrogato e i suoi verdetti vengono registrati, ma il risultato regex è quello che viene applicato. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` mantiene la configurazione — l'endpoint e la chiave — e smette di chiedere a Jev: gli hook eseguono le politiche regex esattamente come senza una configurazione, e `failproofai jev status` dice "off (switched off)". Torna indietro con `--mode shadow` o `--mode enforce`. + +Ri-eseguire `setup` per lo stesso provider mantiene la chiave archiviata, quindi un cambio di modalità è un flag. Cambiare provider ricomincia e chiede la chiave di quel provider. Lo stesso per un `--base-url` che sposta le richieste a un host diverso: una chiave archiviata viene inviata solo all'host per il quale è stata fornita, o all'API del suo provider. + +## Il file di configurazione + +Tutto risiede in un file, `~/.failproofai/jev.json`, scritto da `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Campo | Significato | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` o `custom` — o `failproofai`, la cui chiave viene dalla connessione FailproofAI Cloud invece di questo file (vedi [Jev tramite FailproofAI Cloud](/it/policies/jev-cloud)). | +| `apiKey` | Inviato come `Authorization: Bearer `. | +| `baseUrl` | Richiesto per `custom`; sostituisce l'URL base del provider altrimenti. Deve essere `https`. `http` semplice a `localhost` è accettato solo con `mode: shadow`: nulla autentica una porta locale, quindi mentre il tuo proxy è inattivo qualsiasi processo sulla macchina, incluso l'agente sottoposto a giudizio, potrebbe rispondere al suo posto. | +| `accountId` | Solo Cloudflare: 32 caratteri hex minuscoli. | +| `model` | Sostituisce l'id modello predefinito del provider. Un id con versione deve nominare Jev 1.13. Un valore che assomiglia a una chiave API viene rifiutato (e non ripetuto indietro), quindi una chiave incollata in `--model` non viene mai archiviata o inviata come modello. | +| `timeoutMs` | Quanto a lungo una chiamata di strumento aspetta Jev prima di usare il risultato regex. 100–10000, predefinito 3000. | +| `mode` | `enforce` (predefinito), `shadow`, o `off` (mantieni la configurazione, non eseguire Jev). | + +Tre regole la proteggono: + +- **Solo proprietario.** È scritto con autorizzazioni `0600`. Una copia che qualsiasi altro utente o gruppo può leggere o scrivere viene **rifiutata**, e gli hook ricadono a regex finché non esegui `chmod 600 ~/.failproofai/jev.json` o `setup` di nuovo. Anche la directory viene controllata: `~/.failproofai` non deve essere **scrivibile** da nessun altro, perché chiunque possa scrivere lì può sostituire il file qualunque siano le sue autorizzazioni. `setup` toglie quei bit di scrittura se li trova. `failproofai jev status` dice quando una configurazione è stata rifiutata e mostra l'endpoint che il file nomina: qualcun altro avrebbe potuto modificarlo, quindi controllalo sia tuo prima di fare `chmod`. Ri-eseguire `setup` su tale file porta la sua chiave archiviata solo all'API del provider; qualsiasi altro endpoint che nomina ha bisogno della chiave di nuovo (`--key-stdin`), o `--base-url default` per inviare le richieste indietro al provider. +- **Solo globale.** Un repository non può attivare Jev, puntarlo a un altro endpoint o scegliere il suo modello: un `.failproofai/jev.json` dentro un progetto viene ignorato, e il provider, l'URL, il modello e l'id account vengono letti solo da quel file — mai dall'ambiente, che le impostazioni dell'agente di un repository possono impostare. (`FAILPROOFAI_HOME` non è un modo per aggirare questo: sposta l'intera directory failproofai, le tue politiche incluse, piuttosto che reindirizzare Jev da solo.) +- **Solo la chiave può provenire dall'ambiente.** Se il file non ha `apiKey`, `FAILPROOFAI_JEV_API_KEY` lo fornisce per quella sessione (`setup --key-from-env` scrive tale file). Non sostituisce mai una chiave che il file contiene, e non può attivare Jev senza il file. Dove la variabile non è impostata, Jev è semplicemente off per quella shell: `failproofai jev status` lo dice, esce con 0 e lascia la configurazione intatta (`status --json` segnala `"status": "key-missing"` con `"reason": "no-env-key"`). Il daemon `failproofaid` non vede l'ambiente della tua shell, quindi su una macchina configurata con `failproofai config`, mantieni la chiave nel file. + +## Quale Jev risponde + +Le soglie di decisione di Failproof AI erano calibrate su Jev 1.13, quindi una risposta viene utilizzata solo quando proviene da quella famiglia: `jev-1.13.x`, o OpenRouter `typesafe/jev-1.13-` di OpenRouter. Dove un provider nomina Jev solo con un alias e non segnala una versione (Vercel, e Cloudflare quando non lo dice), la risposta viene utilizzata e registrata come non verificata. Un endpoint `custom` deve segnalare il modello che ha risposto; l'unica eccezione è un nome `--model` senza versione che hai configurato per esso, che, ripetuto indietro, viene registrato come non verificato allo stesso modo. Una risposta che segnala qualsiasi altra versione, o una risposta `custom` che non segnala alcuna, non viene utilizzata: quella chiamata ricade a regex con il motivo `model-mismatch`. + +## Quando Jev non può rispondere + +Ognuno di questi ricade al risultato regex per quella chiamata e viene registrato con il suo motivo, che `failproofai jev status` totalizza: + +| Motivo | Causa | +| --- | --- | +| `timeout` | Nessuna risposta entro `timeoutMs`. | +| `http-429` | Il provider ha limitato la velocità della chiave. | +| `rate-limited` | Il limitatore di velocità di Failproof AI ha trattenuto la chiamata prima di inviarla: 5 richieste al secondo, in burst fino a 5, e nessuna per un momento dopo che il provider risponde `429`. Non il provider. | +| `http-500`, `http-502`, `http-503`, … | Un errore del server presso il provider. Lo stato esatto viene registrato. | +| `out-of-credits` | HTTP 402: l'account del provider non ha più crediti. | +| `provider-refused` | HTTP 402 da Cloudflare leggendo "Model execution failed (Payment error)": il provider ha rifiutato di eseguire il modello su questa richiesta. Di solito non è fatturazione, quindi ricaricare non lo farà muovere. | +| `http-401`, `http-403` | La chiave è stata rifiutata. | +| `http-404` | Nulla è servito presso `/systemone`, quindi l'URL di base è sbagliato — `/systemone` viene aggiunto a esso, e ogni provider lo serve alla sua radice di versione. `failproofai jev models` mostra cosa l'endpoint serve. | +| `network` | L'endpoint non poteva essere raggiunto. | +| `http-301`, `http-302`, `http-307`, `http-308` | L'endpoint ha risposto con un reindirizzamento. I reindirizzamenti non vengono mai seguiti, quindi la risposta viene solo dall'URL nella tua configurazione; imposta `--base-url` all'URL finale. | +| `malformed` | L'endpoint ha risposto, ma non con una risposta Jev — un corpo che non è JSON, o uno senza risposte in esso. | +| `cloudflare-error`, `cloudflare-incomplete` | L'involucro di Cloudflare ha segnalato un errore, o un lavoro che non era finito. | +| `model-mismatch` | Una versione di Jev diversa da 1.13 ha risposto, o un endpoint `custom` non ha detto quale modello ha risposto. | +| `request-cut` | **Non un'interruzione di servizio.** Jev ha risposto; gli è stata mostrata solo parte della chiamata, quindi la sua risposta non ha annullato nulla. Vedi [Quando Jev ha risposto, ma non all'intera chiamata](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` può mostrare anche pochi motivi più rari, come `upstream-error` (la risposta conteneva l'errore del provider) o `config`, e totalizza qualsiasi motivo che non può nominare come `other`. + +`request-cut` è in questa tabella perché `failproofai jev status` lo totalizza con il resto, e perché mantiene anche ogni rifiuto in piedi. È l'unico motivo qui che non dice nulla del tuo provider: la richiesta è arrivata e Jev ha risposto. A differenza di ogni riga sopra, quella risposta continua a contare — il rifiuto o l'avvertimento di Jev si applica in cima al risultato regex piuttosto che essere scartato. Quindi una serie di loro significa che le chiamate stanno raggiungendo l'evaluator troppo grandi per essere inviate intere, non che il tuo endpoint stia male, e ricaricare crediti o cambiare l'URL non lo farà muovere. + +## Quando Jev ha risposto, ma non all'intera chiamata + +Due cose di più possono accadere, e nessuna delle due riguarda Jev che non riesce a rispondere. Entrambe riguardano quanto della chiamata, o della conversazione, è riuscito a stare in una richiesta. + +**Parte della chiamata stessa non è riuscita a stare.** Una chiamata di strumento viene inviata dentro un budget fisso, e una sovradimensionata — uno `Write` molto grande, un corpo MCP enorme, un comando riempito fino al limite — viene inviata con ciò che è riuscito. Jev comunque risponde, e la sua risposta comunque conta: il suo rifiuto o avvertimento si applica come al solito. Quello che non può fare è **annullare** nulla, perché un verdetto dato su parte di una chiamata non è un verdetto sulla chiamata. Quindi ogni rifiuto di politica rimane in piedi, e la chiamata viene registrata come un fallback con il motivo `request-cut`, che `failproofai jev status` totalizza insieme ai motivi sopra. La regola che ti dà: fare una chiamata più grande può costarle i suoi annullamenti, e non può mai comprarne uno. + +**Un messaggio non è riuscito a stare.** Un prompt lungo che hai incollato, l'ultimo messaggio dell'agente, o un prompt che l'archivio di questo evaluator aveva già messo un limite. **Nulla cambia**: la chiamata viene giudicata, annullata e registrata esattamente come qualsiasi altra, e non viene contata come un fallback. La lunghezza di quello che scrivi non decide mai un verdetto, e un limite non può produrre consenso: dove un prompt è arrivato già limitato, "non hai richiesto questo" smette di essere una conclusione che può essere tratta da esso, piuttosto che diventarne una. + +La linea tra i due è chi ha scritto il testo. La chiamata è dell'agente, e una regola che lasciasse che la sua lunghezza sottragga gravità sarebbe una regola che l'agente può usare; il tuo prompt è tuo, e trattare la sua lunghezza come un segnale solo punisce l'incollare una specifica o una traccia dello stack. + +## Cosa lascia la macchina + +Per ogni chiamata di strumento che Jev valuta, una richiesta va al tuo provider, portando: + +- la chiamata di strumento stessa, con segreti come chiavi API, token bearer e assegnazioni `KEY=` cancellate; +- i prompt recenti che hai digitato, con il testo che l'imbracatura dell'agente ha aggiunto rimosso; +- l'ultimo messaggio dell'agente prima del tuo ultimo prompt, etichettato come scritto dall'agente; +- fatti calcolati localmente, come se un percorso sia dentro il progetto — quello della sessione al suo primo controllo revisionato, [bloccato per la sessione](/it/reference/jev-intent#the-project-root) — e il ramo git corrente. + +Va solo all'endpoint nella tua configurazione, sotto la tua chiave. + +## Spegnilo + +```bash +failproofai jev remove +``` + +Questo cancella `~/.failproofai/jev.json`. Dalla prossima chiamata di strumento, gli hook eseguono le politiche regex esattamente come prima. I negozi per-sessione sotto `~/.failproofai/state/semantic/` (prompt registrati in `sessions/`, radici di progetto in `roots/`) vengono lasciati in posto e invecchiano. Per smettere di chiedere a Jev ma mantenere la configurazione, usa `failproofai jev setup --mode off` invece. + +## Riferimento dei comandi + +| Comando | Risultato | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configuralo in un comando; il provider viene dall'host dell'URL | +| `failproofai jev --url --token ` | Lo stesso, con la chiave sulla riga di comando — la tua cronologia e l'elenco dei processi la vedono | +| `failproofai jev setup --provider --key-stdin` | Scrivi la configurazione da una chiave inviata su stdin | +| `failproofai jev setup --provider ` | Lo stesso, chiedendo la chiave a un prompt mascherato | +| `failproofai jev setup --key-from-env` | Non archiviare una chiave; leggi `FAILPROOFAI_JEV_API_KEY` per sessione | +| `failproofai jev setup --mode shadow` | Cambia modalità (`enforce`, `shadow` o `off`), mantenendo la chiave archiviata | +| `failproofai jev setup --model ` / `--base-url ` | Sovrascrivi il modello o la base API; `default` cancella l'override | +| `failproofai jev setup --timeout-ms ` | Cambia il budget per-chiamata | +| `failproofai jev status [--json]` | Configurazione, autorizzazioni e attività recente; mai la chiave | +| `failproofai jev test [--json]` | Una richiesta in diretta: latenza e la versione che ha risposto | +| `failproofai jev models [--provider ] [--url ] [--json]` | Gli id modello che `/models` dell'endpoint segnala, contrassegnando quello configurato | +| `failproofai jev remove` | Cancella la configurazione; Jev è off | \ No newline at end of file diff --git a/docs/it/policies/jev-cloud.mdx b/docs/it/policies/jev-cloud.mdx new file mode 100644 index 000000000..e00bc2e8c --- /dev/null +++ b/docs/it/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev attraverso FailproofAI Cloud" +description: "Lascia che Jev valuti le chiamate di tool dei tuoi agenti attraverso FailproofAI Cloud, sul piano della tua organizzazione, senza un account TypeSafe o una chiave tua." +icon: "cloud" +--- + +[Jev](/it/policies/jev-byok), il classificatore di TypeSafe, legge ogni chiamata di tool rispetto a quello che hai effettivamente chiesto e risponde insieme alle tue policy, mai al loro posto. Attraverso **FailproofAI Cloud**, una macchina connessa usa Jev con la stessa chiave con cui si connette già: nessun account TypeSafe, nessuna seconda chiave, nessun endpoint da configurare. Ogni chiamata viene addebitata alla quota del piano esistente della tua organizzazione. + +Tutto ciò che Jev fa rimane invariato rispetto alla [configurazione bring-your-own-key](/it/policies/jev-byok): le policy hard rimangono definitive, il deny di una policy revisabile viene cancellato solo quando Jev è stato interrogato esattamente su quella preoccupazione, e qualsiasi errore ricade al risultato regex per quella chiamata. + + +Richiede **failproofai 1.0.8-beta.0** o successivo. La versione 1.0.7 non ha Jev, anche se ordina sopra i beta 1.0.7. Senza una configurazione Jev non cambia nulla: gli hook eseguono le policy regex esattamente come hanno sempre fatto. + + +## Attivalo + +1. **Crea una chiave con Jev.** Nel dashboard FailproofAI Cloud, apri **Keys → Create key** e scegli il preset **machine**. Concede i tre permessi di cui una macchina ha bisogno: `events:add` (invia attività), `policies:pull` (ricevi policy) e `jev:evaluate` (Jev, addebitato al piano della tua organizzazione). Una chiave non può portare `jev:evaluate` senza gli altri due. +2. **Connetti la macchina** con quella chiave: + + ```bash + failproofai config --token + ``` + + Se la tua organizzazione gestisce il suo FailproofAI Cloud invece di quello ospitato, aggiungi il suo indirizzo: `--url https://` (oppure esporta `FAILPROOFAI_CLOUD_URL`). Senza di esso la chiave viene verificata rispetto al servizio ospitato e la connessione fallisce. Se il certificato di quell'host proviene da una CA privata, installa la CA nell'archivio trust di sistema della macchina (ad esempio con `update-ca-certificates`), non solo in `NODE_EXTRA_CA_CERTS`: il daemon che invia eventi e riceve policy legge l'archivio di sistema. Vedi [Troubleshooting](/it/reference/troubleshooting). + +Questo è tutto. La connessione memorizza la chiave e, quando la macchina **non** ha ancora una configurazione Jev, attiva Jev attraverso FailproofAI Cloud in modalità **shadow**: Jev è interrogato su ogni chiamata di tool gated e i suoi verdetti sono registrati, ma il risultato delle tue policy è quello che viene applicato. L'output lo dice: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**Con `--no-transcripts`, la connessione non attiva Jev.** Jev invia ogni chiamata di tool controllata e il prompt recente a FailproofAI Cloud, che è più di una connessione solo-decisioni sollecitata a inviare. La chiave viene comunque memorizzata e l'output dice che Jev è disponibile e come attivarlo: + +```bash +failproofai jev setup --provider failproofai +``` + +Non disattiva neanche Jev **off**. Se il `jev.json` della macchina esegue già Jev attraverso FailproofAI Cloud, viene lasciato com'è e l'output dice che Jev invia comunque ogni chiamata di tool controllata e il prompt recente, e che `failproofai jev setup --mode off` lo disattiva. + + +La connessione **non sovrascrive mai** un `~/.failproofai/jev.json` esistente. Se usi già il tuo endpoint Jev, continua a essere usato e l'output dice che il file è stato lasciato come configurato — e, quando quel file lascia Jev disattivato (rifiutato o disattivato), lo dice e come risolverlo. Per passare quella macchina a FailproofAI Cloud, esegui `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce o off + +Inizia in shadow, osserva cosa avrebbe fatto Jev sulla pagina delle policy, poi lascialo agire: + +```bash +failproofai jev setup --mode enforce # I verdetti di Jev si applicano: può cancellare un deny revisabile e aggiungere i suoi +failproofai jev setup --mode shadow # Jev è interrogato e registrato; il risultato delle tue policy è applicato +failproofai jev setup --mode off # mantieni la configurazione, smetti di chiedere a Jev +``` + +Lo stesso interruttore è nel dashboard locale: **Settings → Jev** ha un interruttore on/off e shadow/enforce. Riscrive la modalità e nient'altro. Gli hook leggono la configurazione ad ogni chiamata di tool, quindi un cambiamento si applica da quella successiva, senza riavvio. + +## Controlla cosa sta facendo + +```bash +failproofai jev status +failproofai jev test +``` + +`status` mostra il provider come **FailproofAI Cloud**, l'host Cloud a cui la macchina si è connessa, la modalità e la fonte della chiave come **FailproofAI Cloud connection**, mai la chiave. Quando un `jev.json` di FailproofAI Cloud è in uso ma Jev non può funzionare, dice il motivo: + +| `status` dice | `status --json` | Significato | +| --- | --- | --- | +| **off — nessuna chiave Jev è memorizzata per la connessione FailproofAI Cloud di questa macchina** | `key-lacks-jev` | La macchina è connessa, ma nessuna chiave Jev è memorizzata per essa: la chiave manca di `jev:evaluate`, oppure la connessione non ha potuto confermarlo. Esegui di nuovo `failproofai config --token ` con la stessa chiave; se manca il permesso, usa una chiave **machine**. | +| **off — questa macchina non è connessa a FailproofAI Cloud** | `not-connected` | Non c'è una connessione FailproofAI Cloud su questa macchina a cui la chiave Jev possa appartenere. | + +Dopo `failproofai config --disconnect` non c'è più un `jev.json` di FailproofAI Cloud (a meno che non sia stato disattivato, il che viene mantenuto), quindi `status` semplicemente riporta Jev come disattivato. `status --json` porta gli stessi fatti (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), anche quando la configurazione è assente o rifiutata. `permissions` è sempre quella di `jev.json`; un rifiuto riguardante `credentials.json` aggiunge `credentialsPermissions`, e `fix` quando un comando lo risolve. `test` invia una richiesta dal vivo e riporta la sua latenza e la versione di Jev che ha risposto. Esce con 1 e lo dice nel titolo quando la risposta arriva dopo il timeout dell'hook (gli hook registrerebbero `timeout`) o risponde male alla sua domanda di controllo. + +Il pannello **Settings → Jev** del dashboard mostra anche la **connessione FailproofAI Cloud**: in quale organizzazione la macchina effettua il reporting e se la sua chiave porta Jev. È letto dai file della macchina stessa, senza una chiamata di rete. + +## Cosa raggiunge la pagina delle policy + +La macchina invia già la sua hook activity a FailproofAI Cloud (`events:add`). Con Jev attivo, il record di ogni chiamata gated dice anche quale valutatore ha eseguito, cosa Jev ha deciso, quali policy ha cancellato, perché è ricaduto quando lo ha fatto, la sua latenza e il modello che ha risposto — decisioni, codici e nomi, mai il comando o il tuo prompt. Sulla pagina **Policies** della tua organizzazione: + +- una chiamata il cui verdetto proprio di Jev ha deciso (modalità enforce) è attribuita a **Jev**, e quando il controllo decisivo proviene da un pack, il record ne nomina anche il pack e la sua versione; +- in modalità shadow, il deny o warning di Jev appare come un **would-have**, accanto ai rollout che stai osservando; +- le policy che Jev ha cancellato, o avrebbe cancellato in modalità shadow, sono conteggiate per policy. + +## Quando Jev non può rispondere + +Ognuno di questi ricade al risultato delle tue policy per quella chiamata e viene registrato con il suo motivo: + +| Motivo | Causa | +| --- | --- | +| `out-of-credits` | La tua organizzazione ha utilizzato la quota del suo piano. | +| `http-401`, `http-403` | La chiave è stata revocata o non porta `jev:evaluate`. Riconnetti con una chiave che lo faccia. | +| `http-429` | FailproofAI Cloud sta limitando la frequenza di Jev per la tua organizzazione. Fino a quando l'attesa che chiede non è terminata (il suo `Retry-After`, al massimo 60 secondi), la macchina non invia nulla e ogni chiamata ricade subito. Le chiamate trattenute in questo modo vengono registrate come `http-429`, o come `rate-limited` quando il limite di frequenza della macchina stessa le trattiene per primo. | +| `http-429` (limite giornaliero) | La tua organizzazione ha utilizzato le sue chiamate Jev giornaliere: **10.000 per giorno UTC**, a meno che chi gestisce il tuo FailproofAI Cloud non abbia impostato un limite diverso. Ogni chiamata ricade fino a quando il conteggio non si reimposta a 00:00 UTC; la macchina continua a chiedere al massimo una volta al minuto, quindi lo rileva entro un minuto. `failproofai jev test` dice "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev ha rifiutato la richiesta di questa chiamata, di solito perché la chiamata di tool conteneva testo denso (base64, esadecimale, codice minificato) oltre il budget di token di Jev. Quella chiamata ricade ogni volta; non è un'interruzione. | +| `http-502` | Jev non è disponibile in questo momento. | +| `http-503` | Questo Cloud non può servire Jev per la tua organizzazione: nessun gateway di modelli, un'organizzazione non ancora provisioning, o il gateway non funziona. Chiedi al tuo amministratore; gli hook chiedono di nuovo al massimo una volta al minuto. | +| `http-404` | Questo FailproofAI Cloud non serve ancora Jev. | +| `timeout` | Nessuna risposta entro `timeoutMs` (default 3000). | +| `model-mismatch` | Una versione di Jev diversa da 1.13 ha risposto. | + +## Dove vive la chiave e dove va + +- La chiave è memorizzata una volta in `~/.failproofai/credentials.json` (`0600`, in una directory solo del proprietario), accanto alle altre credenziali FailproofAI Cloud. `jev.json` non contiene alcuna chiave per questo percorso; una scritta lì rende la configurazione non valida. +- Se `credentials.json` porta **qualsiasi** permesso per chiunque non sia tu (gruppo o altro, lettura o scrittura), o la sua directory può essere **scritta** da chiunque non sia tu, viene **rifiutata**, non letta, e Jev rimane disattivato finché non la correggi: `chmod 600` sul file, `chmod 700` sulla directory (o riconnettiti, che riscrive il file a `0600` e rende la directory solo del proprietario). Una directory che altri possono solo leggere va bene; una che possono scrivere gli permette di scambiare il file. +- La chiave conta solo mentre la connessione da cui proviene è sulla macchina: una credenziale di policy o reporting per lo stesso FailproofAI Cloud **con la stessa chiave**, nello stesso file. Una chiave Jev lasciata indietro senza una viene ignorata e Jev rimane disattivato. Questo accade quando il `config --disconnect` di un failproofai più vecchio lascia la chiave Jev in posizione (non sa di rimuoverla), o quando il `config --token` di un failproofai più vecchio si connette con un'altra chiave, che su FailproofAI Cloud può appartenere a un'altra organizzazione. Per riattivare Jev, connettiti di nuovo con una chiave **machine**. +- La chiave viene inviata solo all'origine Cloud rispetto a cui è stata verificata. Un `jev.json` che punta altrove viene rifiutato. +- **Un agente sulla macchina può leggerlo.** `credentials.json` è solo del proprietario e l'agente funziona come quel proprietario. La lettura dei file di failproofai è consentita di proposito (solo cambiarli è bloccato, da `block-failproofai-commands`), quindi l'unica cosa tra un agente e questo file è `block-read-outside-cwd` — una policy *revisabile* — e da una sessione iniziata nella tua home directory, nulla. Una chiave con `jev:evaluate` spende l'indennità Jev della tua organizzazione (fino al limite giornaliero) da ovunque venga utilizzata, quindi tratta una chiave di macchina come qualsiasi altra credenziale di spesa: se un agente potrebbe averla letta, disabilitala sulla pagina Keys e riconnettiti con una nuova. +- Solo i tuoi file globali decidono questo. Un repository non può attivare Cloud Jev, puntarlo altrove o fornire la sua chiave, e `FAILPROOFAI_JEV_API_KEY` viene ignorato per questo percorso. +- Per ogni chiamata che Jev valuta, una richiesta va a FailproofAI Cloud, portando quello che la [pagina bring-your-own-key](/it/policies/jev-byok#what-leaves-the-machine) elenca (segreti redatti). FailproofAI Cloud la invia a TypeSafe e non la registra o mantiene. + +## Disattivalo + +| Comando | Risultato | +| --- | --- | +| `failproofai jev setup --mode off` | Mantieni la configurazione; Jev non viene interrogato. **Questo è l'interruttore che dura:** la connessione di nuovo non riscrive mai un `jev.json` esistente, quindi Jev rimane disattivato finché non lo riattivi con `--mode shadow`. | +| `failproofai jev remove` | Elimina `~/.failproofai/jev.json`; Jev è disattivato — fino al prossimo `failproofai config --token` con una chiave che porta `jev:evaluate`, che non trova `jev.json` e attiva Jev di nuovo in modalità shadow (a meno che non funzioni con `--no-transcripts`). Per mantenerlo disattivato, usa `--mode off`. | +| `failproofai config --disconnect` | Disconnetti la macchina: la chiave viene rimossa e così fa `jev.json` quando nomina FailproofAI Cloud e non è disattivato. Un `jev.json` per il tuo endpoint rimane e così fa uno disattivato, quindi Jev rimane disattivato quando ti connetti di nuovo. | + +Dalla prossima chiamata di tool, gli hook eseguono le policy regex esattamente come prima. \ No newline at end of file diff --git a/docs/it/policies/jev.mdx b/docs/it/policies/jev.mdx new file mode 100644 index 000000000..c6a59eede --- /dev/null +++ b/docs/it/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Politiche Jev" +description: "Aggiungi la revisione live di Jev alle chiamate di strumenti controllate, quindi ispezionala prima di applicare le sue decisioni." +icon: "shield-check" +--- + +Jev legge una chiamata di strumento rispetto a quello che la persona ha chiesto all'agente di fare. Usalo quando una politica di corrispondenza di stringhe blocca un lavoro valido o manca un'azione rischiosa che necessita di contesto. Risponde insieme alle tue politiche al gate `PreToolUse` o `PermissionRequest`. Per un punteggio **dopo** la fine di una sessione, usa [valutazioni Jev](/it/evaluations/jev). + +## Inizia in modalità di osservazione + +Installa Failproof AI e allega gli hook a un [harness supportato](/it/reference/harnesses). Usa failproofai 1.0.8-beta.0 o successivo. + +Failproof AI non include controlli Jev. Installali come pacchetto, altrimenti Jev non ha nulla da chiedere e non viene mai chiamato: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Quindi scegli come le richieste raggiungono Jev: + +| Route | Primo passaggio | +| --- | --- | +| FailproofAI Cloud | Connettiti con una chiave **machine** che porta `jev:evaluate`. Su una macchina senza configurazione Jev, `failproofai config` attiva Jev in modalità di osservazione. | +| Il tuo provider | Nel dashboard locale, apri **Settings → Jev**, scegli il provider, incolla il suo token e seleziona **observe**. Oppure esegui `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![Le impostazioni Jev del dashboard locale: provider, endpoint, token e modalità di osservazione prima di attivare Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` controlla l'endpoint. Per controllare il percorso dell'hook, chiedi a un agente con hook di usare il suo strumento di lettura dei file su `README.md`. Conferma che quella chiamata di strumento appare nella sessione, quindi ispeziona **Policies → Activity** nel [dashboard locale](/it/reference/local-dashboard#review-policy-activity). Il conteggio di Jev in `status` dovrebbe aumentare. La modalità di osservazione registra quello che Jev avrebbe deciso mentre il tuo risultato di politica esistente continua ad applicarsi. + +## Decidi quando applicare + +Una politica **hard** ha sempre l'ultima parola. Jev può annullare un deny solo da una politica esplicitamente marcata come **reviewable** e solo quando ha controllato il problema denominato di quella politica. Vedi [policy authority](/it/policies/authority) prima di fare affidamento su un'autorizzazione. Jev può anche avvertire o negare di propria iniziativa. Se non può rispondere, il risultato della politica decide quella chiamata. + +Una volta che i risultati dell'osservazione sembrano corretti, passa alla modalità di applicazione in **Settings → Jev** o esegui: + +```bash +failproofai jev setup --mode enforce +``` + +Per URL di provider, chiavi Cloud, configurazione, fallback e dati inviati con ogni richiesta, consulta il [riferimento di integrazione Jev](/it/reference/jev). \ No newline at end of file diff --git a/docs/it/reference/custom-agents-typescript.mdx b/docs/it/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..44ba4a77a --- /dev/null +++ b/docs/it/reference/custom-agents-typescript.mdx @@ -0,0 +1,426 @@ +--- +title: "Agenti personalizzati (TypeScript)" +description: "Configurazione, catalogo eventi, ambiti e adattatori per il framework di @failproofai/sdk." +icon: "square-js" +--- + +Cosa fanno ogni impostazione, metodo e campo per l'SDK TypeScript. Se stai facendo strumentazione per la prima volta, inizia con la guida — questa pagina è per consultazioni. + + + + Installazione, strumentazione, metodi di evento, un esempio pratico e problemi comuni. + + + Gli stessi eventi, lo stesso formato di trasmissione, lo stesso spool — da Python. + + + +Node 20.9 o più recente. ESM e CommonJS. Nessuna dipendenza di runtime. + + + Questo SDK e quello Python scrivono **gli stessi eventi nello stesso spool**. Una flotta con agenti Node e agenti Python produce un insieme di sessioni, non due, e nulla nel dashboard li distingue. Scegli per servizio, non per azienda. + + +## Installa + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Gli adattatori del framework vengono forniti nel pacchetto stesso. I framework sono **dipendenze peer opzionali** — dichiarate così gli intervalli supportati sono visibili, non installate per conto tuo, e importate solo quando chiami `instrument()`. + +## Connetti il daemon Failproof + +Identico all'SDK Python: crea una chiave `events:add` in **Admin → Keys**, poi [connetti il daemon](/it/start/setup#connect-a-machine-to-cloud) sulla macchina agente. L'SDK scrive su disco; il daemon spedisce. + +## Configurazione + +### Span OpenTelemetry (opt in) + +Installa OpenTelemetry separatamente con `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Quindi aggiungi FailproofAI ai processori del tuo provider: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Per un provider esistente, mantieni i suoi altri processori nella stessa lista. I provider che espongono `addSpanProcessor` possono invece essere passati come `{ provider }`. Senza opzioni, setup registra un nuovo provider solo se nessun provider è già registrato. +`OtelSpanExporter` può anche essere usato direttamente con il tuo processor. + +Le esportazioni vanno attraverso il daemon FailproofAI connesso; l'SDK non invia richieste di rete e non ha bisogno di chiave o listener locale. Chiedi a un amministratore di abilitare [l'acquisizione OpenTelemetry](/it/agenteye/opentelemetry). Un `instrument()` nudo non abilita questo esportatore. `uninstrument("otel")` disabilita solo il suo processore. I tuoi attributi di span controllano l'acquisizione di contenuto; scarica il tuo provider prima dell'uscita. OpenTelemetry rimane una dipendenza applicativa opzionale, non una dipendenza SDK rigida. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Opzione | Cosa fa | +| --- | --- | +| `environment` | L'etichetta su ogni evento — `production`, `staging`, `prod-eu`. Predefinito a `dev`. | +| `flushInterval` | Con quale frequenza il timer scrive su disco, in secondi. Predefinito a `0.5`. | +| `baseDir` | Dove scrivere. Predefinito allo spool del daemon, che è quello che vuoi a meno che tu non sappia diversamente. | + +Nulla viene applicato a meno che non tutto si validi, quindi una chiamata rifiutata lascia l'SDK esattamente come era piuttosto che con un nuovo `baseDir` e il vecchio intervallo. + +Imposta con variabile di ambiente invece: + +| Variabile | Cosa fa | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Imposta `environment` senza un cambio di codice. Un'opzione `configure()` la vince. | +| `FAILPROOFAI_HOME` | Sposta la radice Failproof AI che contiene lo spool. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (predefinito), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` fa lanciare gli errori di strumentazione invece di essere registrati. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` fa lanciare un problema di compatibilità del framework invece di avvertire e continuare. | + + + **Niente virgole in `environment`.** L'acquisizione divide quel campo su virgole per costruire i suoi filtri, e salta qualsiasi evento la cui etichetta ne contiene una — quindi un'intera esecuzione scompare silenziosamente. Scrivi `prod-eu`, non `prod,eu`. + + `configure({ environment: "prod,eu" })` lancia in modo che tu lo scopra immediatamente. `AGENTEYE_ENVIRONMENT` non può lanciare — nulla ti sta chiamando — quindi avverte una volta e torna a `dev`. + + +Indirizza le tue righe di log dell'SDK nel tuo logger con `failproofai.setLogger({ debug, info, warn, error })`. + +## Chiusura + +Gli eventi bufferizzati vengono scaricati su `process.on("exit")`. + +Un processo ucciso da un segnale non raggiunge mai quello, e il predefinito di Node per `SIGTERM` è terminare senza eseguire i gestori di uscita — quindi un agente containerizzato perde quello che l'ultimo intervallo non aveva scritto. + + + **Questo SDK non installerà un gestore di segnale per te.** Registrarne uno cambia il comportamento del tuo processo: un listener sopprime la terminazione predefinita di Node, quindi una libreria che ne aggiungesse uno farebbe silenziosamente smettere Ctrl-C di funzionare. Aggiungine uno tuo: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Uno script di breve durata o un gestore serverless dovrebbe `await failproofai.flush()` prima di ritornare — l'intervallo da solo non garantisce la consegna. + +## Identità + +Ogni evento appartiene a una sessione e un agente. **Gli ambiti compilano entrambi**, quindi raramente li passi: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Passare `sessionId` o `agentId` esplicitamente funziona ancora e vince. Senza nessuno legato né passato, la chiamata lancia piuttosto che emettere un evento che Cloud discards silenziosamente. + + + L'identità cavalca `AsyncLocalStorage`. Segue `await`, `.then()`, timer e qualsiasi callback creato all'interno dell'ambito. Non segue un callback memorizzato durante un'esecuzione e richiamato durante un'altra, o il lavoro consegnato oltre un confine `worker_threads` — racchiudili in `failproofai.propagate()` o i loro eventi atterrano staccati. + + +### Ambiti + +| Ambito | Emette | Ritorna | +| --- | --- | --- | +| `session(body)` | nulla — solo identità | quello che `body` ritorna | +| `agent(id, options?, body)` | `agent_start`, poi `agent_end` | quello che `body` ritorna | +| `toolCall(name, options?, body)` | `tool_use`, poi `tool_result` | quello che `body` ritorna | + +Un body sincrono rimane sincrono: `agent("x", () => 1)` ritorna `1`, non una promise. + +`toolCall` registra il valore risolto del body come `output` dello strumento, a meno che non assegni `call.output` tu stesso. + + + +| Cosa è successo | Eventi | `outcome` | +| --- | --- | --- | +| il blocco è ritornato | `agent_end` | `"success"`, o il tuo `outcome` | +| il blocco ha lanciato | `error`, poi `agent_end` | `"failed"` | +| un `AbortError` | solo `agent_end` | `"cancelled"` | + +L'errore viene sempre rilasciato di nuovo. + +Un fallimento dello strumento è registrato sulla foglia — `tool_result` con una stringa `error` — e non emette **nessun** evento `error` a livello di esecuzione. Uno che il ciclo dell'agente cattura non è un fallimento di esecuzione, e uno che si propaga è segnalato esattamente una volta, dall'`agent()` racchiudente. + + + + + +Quando il lavoro non è una singola funzione — un ambito aperto in un costruttore e chiuso in uno smontaggio, o uno che cavalca il flusso di controllo esistente: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, poi agent_end +``` + +Entrambe le forme emettono eventi byte-identici. Preferisci la forma callback: viene eseguita all'interno di `AsyncLocalStorage.run()`, quindi non c'è nulla da svolgere e l'intera classe di bug "aperti qui, chiusi laggiù" è irraggiungibile. + +Un blocco `using` che cattura il suo stesso fallimento lo segnala con `span.fail(error)` — il disposer non ha un canale di eccezione proprio. + + + +## Catalogo eventi + +Gli stessi quindici metodi dell'SDK Python, in camelCase. La maggior parte viene in **coppie** — chiami l'opener, poi il closer, e l'SDK temporizza il gap. + +| | Apre | Chiude | +| --- | --- | --- | +| **Agenti** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Modelli** | `modelRequest` | `modelResponse` | +| **Strumenti** | `toolUse` | `toolResult` | +| **Hook** | `hookTriggered` | `hookCompleted` | +| **Umani** | `humanWait` | `humanInput` | + +Tre funzionano da soli: `error`, `humanPause`, `humanInterrupt`. + + + +Ogni metodo accetta anche `sessionId` e `agentId`, che gli ambiti compilano per te. Qualsiasi cosa omessa viene scartata piuttosto che inviata come JSON `null`. + +| Metodo | Richiesto | Opzionale | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Qualsiasi altra chiave che aggiungi diventa un campo di payload personalizzato. Namespacia qualsiasi cosa specifica del framework `fw_*`; un nome che collide con un campo dichiarato viene rifiutato piuttosto che sovrascrivere silenziosamente una colonna promossa. + + + + + **`duration_ms` è calcolato, non accettato.** I quattro metodi di chiusura temporizzano il gap dal loro opener e rifiutano un `duration_ms` fornito dal chiamante — una durata segnalata è infalsificabile. + + Le coppie sono abbinate sulla **sessione** e l'id, mai sull'agente. Uno strumento aperto sotto `planner` e chiuso sotto `worker` si accoppia ancora, che è quello che le esecuzioni multi-agente annidate fanno effettivamente. + + +## Adattatori per framework + +```ts +await failproofai.instrument(); // qualsiasi cosa trovi +await failproofai.instrument("langchain"); // esattamente uno +failproofai.uninstrument(); // ripristina tutto +``` + +| Framework | Supportato | Come si attacca | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, quindi ogni `invoke`/`stream`/`batch` è coperto senza passare `callbacks:` da nessuna parte — o passa `langchainHandler()` tu stesso e non fare patch di nulla. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` al sito di chiamata, o `instrument("ai")` per l'intero processo su `ai` 7 (su 4–6 è opt-in — vedi sotto). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, la risoluzione del modello e dello strumento dell'agente, e il motore di esecuzione e step del flusso di lavoro. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (sottoscritto) più `AgentWorkflow.runStream`, per esecuzioni di flussi di lavoro e i loro step. | + +Ogni intervallo è testato contro versioni di framework reali, a entrambe le estremità, come modulo ES e come CommonJS, su ogni esecuzione CI. + +La mappatura è quella dell'SDK Python, quindi lo stesso programma disegna lo stesso albero in entrambi i linguaggi. Un costrutto è un **agente** solo se possiede un ciclo decisionale LLM — un'esecuzione di grafico o catena, una chiamata `generateText`/`streamText` dell'AI SDK, un agente Mastra, un'esecuzione di agente LlamaIndex. Un nodo LangGraph o uno step del flusso di lavoro è un **hook** (`hook_triggered`/`hook_completed`), mai un agente annidato. Le chiamate di modello sono coppie `model_request`/`model_response` con conteggi di token; le chiamate di strumento portano l'id di chiamata dello strumento del modello stesso. Un fallimento è registrato una volta, nell'evento in cui è accaduto. + +Un adattatore che non riesce a installare viene registrato e saltato; gli altri si installano ancora, perché un LlamaIndex rotto non dovrebbe costarti LangGraph. + + + `instrument()` senza argomento rileva un framework dal fatto che **si risolva**, non dal fatto che sia già importato — Node non espone l'equivalente di Python `sys.modules` per i moduli ES. Un framework che hai installato ma non usi verrà importato e patchato. Specifica quello che vuoi se questo conta. + + + + La maggior parte di questi framework spedisce una build di modulo ES e una build CommonJS, che Node carica come due copie non correlate. Gli adattatori eseguono patch della copia che la tua applicazione carica (e anche la copia CommonJS se qualcosa l'ha già `require`d), quindi entrambi i sistemi di modulo funzionano. Un framework **bundled nel tuo stesso output** da esbuild o webpack è fuori portata — usa gli helper del sito di chiamata lì: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain senza patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +Il gestore funziona con o senza `instrument()` e non registra mai due volte. `instrument("langchain")` accetta `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` e `captureLimit`, come fa l'adattatore Python; `metadata: { failproofai_sdk_session_id }` su una chiamata sceglie la sessione per quella invocazione. + +### Vercel AI SDK + +L'AI SDK esporta funzioni semplici da un modulo ES, e uno spazio dei nomi di modulo ES è immutabile per specifica — non c'è nessun posto dove fare patch. Usa i punti di estensione che l'SDK stesso documenta: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // su ai 7, `telemetry: telemetry({ … })` — lo stesso oggetto, il nuovo nome +}); +``` + +Questa è l'integrazione completa: uno span di agente, una coppia model request/response per step con conteggi di token, e ogni chiamata di strumento. Un sito di chiamata funziona su ogni versione principale — `ai` 4–6 leggono il tracer che porta, `ai` 7 l'integrazione telemetria. + +`instrument("ai")` fa lo stesso processo-wide **su `ai` 7**: ogni chiamata, attraverso l'elenco di integrazione telemetria globale dell'AI SDK, che è additivo e non prende nulla da nessun altro. + +**Su `ai` 4–6, `instrument("ai")` non registra nulla di per sé, e registra un avviso dicendo così.** L'unico hook processo-wide che quelle versioni principali hanno è il provider tracer OpenTelemetry globale — uno slot singolo che OpenTelemetry rifiuta di consegnare una volta preso. Registrare il nostro rifuterebbe silenziosamente il tuo `NodeSDK.start()` successivo nell'avvio e invierebbe i tuoi span http/database a un tracer che non esporta nulla. Usa `telemetry()` al sito di chiamata o `wrapModel` lì. Se il processo non esegue OpenTelemetry proprio, opt in con `instrument("ai", { registerGlobalTracer: true })`: quindi registra ogni chiamata che passa `experimental_telemetry: { isEnabled: true }`, e prende lo slot solo se è ancora vuoto. `registerGlobalTracer: false` mantiene il predefinito e silenzia l'avviso. + +Se preferisci avvolgere il modello una volta, `wrapModel` vede solo le chiamate di modello, perché le chiamate di strumento accadono sopra il livello del modello. Un modello avvolto chiamato senza nulla intorno è registrato come la sua propria esecuzione. Una chiamata streamata si chiude comunque lo stream si fermi — `stop_reason: "cancelled"` quando il consumatore lo annulla, `"error"` con l'errore quando fallisce a metà: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Usare entrambi va bene: il middleware nota che la chiamata è già registrata e rinvia, quindi ogni chiamata è registrata una volta. + +`functionId` nomina lo span dell'agente. Mantienilo a bassa cardinalità — atterra in `agent_id`, la facet principale del dashboard. + +### Next.js + +`next build` lega le dipendenze del tuo server per impostazione predefinita, e un framework legato nella build è una copia che `instrument()` non può raggiungere. Racchiudi la configurazione una volta e chiama `instrument()` dal gancio di avvio di Next: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` aggiunge LangChain, Mastra, LlamaIndex e l'SDK stesso a `serverExternalPackages`, mantenendo il tuo elenco. Senza di esso, `instrument()` avverte una volta per framework non può raggiungere piuttosto che fallire silenziosamente; se elenchi i pacchetti tu stesso, imposta `FAILPROOFAI_NEXT_EXTERNALS=1`. L'SDK Vercel AI e gli helper del sito di chiamata funzionano comunque. Una rotta Edge riceve una build no-op: importare l'SDK è sicuro e non registra nulla. + +### Conteggi di token su chiamate streamate + +Le API compatibili con OpenAI segnalano l'utilizzo su un stream solo quando il client lo chiede. LangChain e l'SDK Vercel AI chiedono; per LlamaIndex passa `additionalChatOptions: { stream_options: { include_usage: true } }` al suo LLM `OpenAI`, e per Mastra costruisci il modello con l'utilizzo abilitato (per esempio `createOpenAICompatible({ includeUsage: true })`). Altrimenti le chiamate di modello streamate non portano conteggi di token. + +### Runtime + +Node ≥ 20.9, Bun e Deno — ogni framework, come modulo ES e come CommonJS, è testato su ognuno contro la traccia di Node. L'SDK funziona accanto al daemon `failproofaid`, che spedisce quello che scrive. + +## Il tuo agente — nessun framework + +Per un ciclo agente che hai scritto tu stesso, o un framework senza un adattatore. Emetti gli eventi con la stessa API che gli adattatori usano sottostante, quindi la traccia ha la stessa forma e qualità. + +Non hai bisogno di sapere come è organizzato l'agente. Ogni agente costruito a mano ha già tre posti, qualunque siano i nomi delle sue funzioni, e quei tre sono l'intera integrazione: + +| Dove | Cosa aggiungere | Emette | +| --- | --- | --- | +| Dove **un'esecuzione** inizia e finisce | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| La **sola funzione che chiama il modello** | `event.modelRequest` prima, `event.modelResponse` dopo — entrambe le metà, anche in caso di fallimento | una coppia per turno di modello | +| La **sola funzione che esegue strumenti** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +L'identità è ambiente: tutto dentro `agent()` atterra sull'esecuzione di quella sessione senza prendere un id, e nulla del resto nel programma cambia — incluso quello che l'agente già scrive nel suo database. + +- **Un servizio o un worker:** passa il tuo id di richiesta o job come `sessionId`, quindi una sessione sul dashboard e il record nei tuoi stessi registri o database sono la stessa stringa. +- **Sotto-agenti:** annida le chiamate `agent()`. Quella interna si unisce alla sessione con quella esterna come suo `parent_id`. +- **Emetti le coppie.** Un `modelRequest` senza `modelResponse` è uno span che il dashboard mostra come in esecuzione per sempre — da qui il `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) nel repository è la versione completa e eseguibile: un vero ciclo di strumento OpenAI strumentato esattamente come questo, eseguito in CI su ogni cambiamento come modulo ES e come CommonJS. + +## Valutazioni + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Vedi il [riferimento Evaluator SDK](/it/reference/evaluator-sdk) per il protocollo, le impostazioni del worker e i tipi di risultato. + + + **Una valutazione deve yielding.** Una funzione sincrona che non ritorna mai blocca il thread unico che Node ha, e nessun timeout può lanciare mentre lo fa. Scrivi valutazioni `async`. + + +## Cosa non farà al tuo processo + +| | | +| --- | --- | +| **Bloccare il tuo ciclo di agente** | Gli eventi vanno in una coda in memoria; un timer li scrive. Il timer è `unref`'d, quindi importare questo pacchetto non ferma mai uno script dall'uscire. | +| **Crescere senza limite** | La coda è limitata per conteggio *e* per byte misurati. Passato uno qualsiasi, gli eventi più vecchi vengono scartati e un avviso dice così — un'interruzione della telemetria non deve diventare un'uccisione OOM. | +| **Portare il processo giù** | Un evento non codificabile viene scartato solo, non il batch intorno ad esso. Un getter lanciante, una riferenza circolare, un `BigInt`, un surrogato solo: ognuno è gestito piuttosto che propagato. | +| **Lasciare un batch mezzoscritto** | Il contenuto è `fsync`ed prima di un rinominamento atomico, la directory è `fsync`ed dopo, e una scrittura fallita pulisce il suo file temporaneo. | +| **Lasciare trascritti leggibili** | I batch sono `0600` all'interno di una directory `0700`. Portano obiettivi, prompt, argomenti di strumento e output di strumento. | +| **Spedire credenziali** | Chiavi API, token, JWT, intestazioni bearer e assegnazioni di forma segreta vengono redatte prima che i byte raggiungano il disco. Il daemon redige di nuovo prima dell'upload. | \ No newline at end of file diff --git a/docs/it/reference/custom-agents.mdx b/docs/it/reference/custom-agents.mdx index 6459d7501..2dbf3e7d8 100644 --- a/docs/it/reference/custom-agents.mdx +++ b/docs/it/reference/custom-agents.mdx @@ -15,7 +15,7 @@ Cosa fanno ogni impostazione, metodo e campo. Se stai strumentando per la prima -Python 3.10 o più recente. Nessuna dipendenza di runtime. +Python 3.11 o più recente. Nessuna dipendenza di runtime. ## Installazione diff --git a/docs/it/reference/jev-cloud.mdx b/docs/it/reference/jev-cloud.mdx new file mode 100644 index 000000000..a9ccc075a --- /dev/null +++ b/docs/it/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev attraverso FailproofAI Cloud" +description: "Chiavi machine in cloud, stato della connessione, limiti e comportamento in caso di errore per la revisione live delle policy Jev." +icon: "cloud" +--- + +Questo è il riferimento del percorso Cloud per le [policy Jev](/it/policies/jev). Jev, il classificatore di TypeSafe, legge ogni tool call rispetto a ciò che hai effettivamente richiesto e risponde insieme alle tue policy, mai al loro posto. Attraverso **FailproofAI Cloud**, una machine connessa utilizza Jev con la stessa chiave con cui si connette già: nessun account TypeSafe, nessuna seconda chiave, nessun endpoint da configurare. Ogni chiamata viene addebitata all'allowance del piano esistente della tua organizzazione. + +Tutto ciò che Jev fa rimane invariato rispetto alla [configurazione bring-your-own-key](/it/reference/jev-providers): le hard policy rimangono finali, il deny di una policy reviewable viene cancellato solo quando Jev è stato interrogato esattamente su quella preoccupazione, e qualsiasi errore ricade nel risultato regex per quella chiamata. + + +Richiede **failproofai 1.0.8-beta.0** o successivo. 1.0.7 non ha Jev, anche se ordina sopra i beta 1.0.7. Senza una configurazione Jev nulla cambia: gli hook eseguono le policy regex esattamente come hanno sempre fatto. + + +## Prima di iniziare + +Installa Failproof AI sulla machine dove viene eseguito il tuo agent e collega i suoi hook a un [harness supportato](/it/reference/harnesses). Se stai iniziando da zero, segui il [quickstart](/it/start/quickstart) fino all'installazione dell'hook. Controlla la CLI installata con `failproofai --version`; aggiornala se è precedente a Jev. Hai anche bisogno dell'accesso alla pagina **Administration → Keys** della tua organizzazione per creare una machine key. + +Jev esamina le tool call nominate al gate `PreToolUse` o `PermissionRequest`. Non esamina ogni evento in una sessione. Per vedere Jev cancellare un deny di policy, hai bisogno di una policy installata contrassegnata come [reviewable](/it/policies/authority); tutti gli altri deny di policy rimangono finali. + +## Attivalo + +1. **Crea una chiave con Jev.** Nel dashboard FailproofAI Cloud, apri **Administration → Keys → Create key** e scegli il preset **machine**. Concede i tre permessi di cui una machine ha bisogno: `events:add` (invia attività), `policies:pull` (ricevi policy) e `jev:evaluate` (Jev, addebitato al piano della tua organizzazione). Una chiave non può avere `jev:evaluate` senza gli altri due. +2. **Connetti la machine** con quella chiave. Leggi il suo segreto monouso a un prompt, quindi esegui il comando di configurazione completo: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` installa il daemon, collega gli hook per gli agent CLI che trova e connette la machine. La variabile d'ambiente mantiene la chiave fuori dagli argomenti del comando e dalla cronologia della shell. Se il tuo harness è stato installato successivamente, [collegalo esplicitamente](/it/start/quickstart). + + Se la tua organizzazione esegue il suo FailproofAI Cloud piuttosto che quello hosted, aggiungi il suo indirizzo: `--url https://` (o esporta `FAILPROOFAI_CLOUD_URL`). Senza di esso la chiave viene controllata rispetto al servizio hosted e la connessione fallisce. Se il certificato di quel host proviene da una CA privata, installa la CA nell'archivio di fiducia di sistema della machine (ad esempio con `update-ca-certificates`), non solo in `NODE_EXTRA_CA_CERTS`: il daemon che invia eventi e recupera le policy legge l'archivio di sistema. Vedi [Troubleshooting](/it/reference/troubleshooting). + +È tutto. La connessione memorizza la chiave e, quando la machine **non** ha ancora una configurazione Jev, ne scrive una per FailproofAI Cloud. Dalla prima distribuzione della machine (entro circa 30 s) FailproofAI Cloud imposta la modalità: `enforce` mentre una policy Jev viene distribuita ad essa, `off` quando non lo è (vedi [Chi imposta la modalità](#who-sets-the-mode)). L'output dice così: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +I controlli che FailproofAI Cloud distribuisce vengono eseguiti su Cloud. Per aggiungere controlli tuoi sulla machine, installa un pack: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**Con `--no-transcripts`, la connessione non attiva Jev.** Jev invia ogni tool call verificato e il prompt recente a FailproofAI Cloud, il che è più di una connessione solo decisioni a cui è stato chiesto di inviare. La chiave viene comunque memorizzata e l'output dice che Jev è disponibile e come attivarlo: + +```bash +failproofai jev setup --provider failproofai +``` + +Lo attiva anche per Jev attraverso FailproofAI Cloud **off**. Un `jev.json` che esegue Jev attraverso FailproofAI Cloud (lasciato da una connessione precedente con i transcript attivi) viene rimosso, secondo la stessa regola che `config --disconnect` usa, e l'output dice che Jev via FailproofAI Cloud rimane off su questa machine. Un `jev.json` per il tuo endpoint Jev è lasciato com'è, così come uno di FailproofAI Cloud che hai disattivato (`--mode off`). + + +La connessione **non sovrascrive mai** un `~/.failproofai/jev.json` esistente. Se utilizzi già il tuo endpoint Jev, continua ad essere utilizzato e l'output dice che il file è stato lasciato configurato — e, quando quel file lascia Jev off (rifiutato o disattivato), lo dice e come risolverlo. Per passare questa machine a FailproofAI Cloud, esegui `failproofai jev setup --provider failproofai`. + + +## Chi imposta la modalità + +Su una machine connessa a FailproofAI Cloud, **FailproofAI Cloud imposta la modalità Jev**; nulla sulla machine lo fa: + +- `enforce` mentre qualsiasi policy Jev (o regex + Jev) è distribuita alla machine: ogni tool call verificato da un agent che una di quelle policy target va a FailproofAI Cloud, che chiede i suoi controlli insieme ai controlli dei pack installati lì. Una chiamata da un agent che nessuna policy Cloud Jev target, senza controllo pack proprio, non viene inviata affatto. In `enforce`, i propri controlli deny di Jev bloccano le chiamate così come cancellano i verdetti regex che esaminano. +- `off` quando non lo è: nessun Jev affatto, indipendentemente da ciò che `jev.json` dice. + +Per provare una policy Jev prima che agisca, distribuiscila con effetto **observe**: i suoi controlli vengono comunque chiesti e ciò che avrebbero fatto è registrato come un **would-have** sulla pagina della policy, ma non blocca mai una chiamata e non ne cancella mai una. `failproofai jev setup --mode` e il dashboard's **Settings → Jev** dicono che la modalità è gestita da FailproofAI Cloud e non cambiano nulla. `jev.json` non viene utilizzato per i controlli di Cloud, anche se nomina un altro provider. `failproofai config --disconnect` restituisce Jev al proprio `jev.json` della machine. + +`failproofai jev status` quindi dice `Jev checks run on FailproofAI Cloud (mode: enforce)`. Nomina anche i controlli che esaminano ogni policy `both`. La pagina della flotta mostra perché una machine con una modalità non può chiedere: + +- `transcripts_disabled`: la machine è stata connessa con `--no-transcripts`, che non attiva mai Jev. +- `jev_unconfigured`: la chiave della machine non ha `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud ha rifiutato alcune delle chiamate della machine per il limite di velocità Jev dell'organizzazione e quelle chiamate sono state decise dalle sole policy regex. +- `jev_unavailable`: diversi fallimenti di fila, quindi la machine salta Jev di FailproofAI Cloud per un minuto alla volta. Riprova da sola. + +Se FailproofAI Cloud non risponde entro 5 secondi, le policy regex decidono da sole, come per qualsiasi interruzione di Jev. Dopo 3 fallimenti di fila la machine smette di chiedere per un minuto alla volta, quindi un'interruzione di Cloud non rallenta ogni tool call. + +Una pausa della sessione (`failproofai config --pause`) non interrompe i controlli Jev di FailproofAI Cloud, proprio come non interrompe le policy gestite da Cloud. Mette in pausa i controlli Jev dei pack installati sulla machine. + +## Controlla ciò che sta facendo + +```bash +failproofai jev status +failproofai jev test +``` + +`status` mostra il provider come **FailproofAI Cloud**, l'host Cloud a cui la machine si è connessa, la modalità e la fonte della chiave come **FailproofAI Cloud connection**, mai la chiave. Quando un `jev.json` di FailproofAI Cloud è in posizione ma Jev non può eseguire, dice perché: + +| `status` dice | `status --json` | Significato | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | La machine è connessa, ma nessuna chiave Jev è memorizzata per essa: la chiave manca di `jev:evaluate`, o la connessione non ha potuto confermarlo. Esegui di nuovo `failproofai config` con la chiave in `FAILPROOFAI_CLOUD_TOKEN`; se manca del permesso, utilizza una chiave **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Non c'è una connessione FailproofAI Cloud su questa machine a cui la chiave Jev possa appartenere. | + +Dopo `failproofai config --disconnect` non c'è più nessun `jev.json` di FailproofAI Cloud (a meno che non sia stato disattivato, che viene mantenuto), quindi `status` semplicemente riporta Jev come off. `status --json` porta gli stessi fatti (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), anche quando la configurazione è assente o rifiutata. `permissions` è sempre quella di `jev.json`; un rifiuto riguardante `credentials.json` aggiunge `credentialsPermissions` e `fix` quando un comando lo risolve. `test` invia una richiesta live e riporta la sua latenza e la versione di Jev che ha risposto. Esce 1 e lo dice nel suo titolo quando la risposta arriva dopo il timeout dell'hook (gli hook registrerebbero `timeout`) o risponde erroneamente alla sua domanda di controllo. + +Il pannello **Settings → Jev** del dashboard mostra anche la **FailproofAI Cloud connection**: quale organizzazione la machine segnala e se la sua chiave ha Jev. Viene letto dai propri file della machine, senza nessuna chiamata di rete. + +## Verifica una chiamata reale + +Avvia una nuova sessione nell'agent con hook. Chiedigli di utilizzare il suo tool di lettura file su `README.md` e di segnalare il titolo. Conferma che la sessione contiene quella tool call, quindi esegui di nuovo `failproofai jev status`: il suo conteggio delle chiamate valutate recenti dovrebbe aumentare. Apri **Policies → Activity** nel [local dashboard](/it/reference/local-dashboard#review-policy-activity) per ispezionare il verdetto Jev di quella chiamata e la modalità. In Cloud, la pagina **Policies** dell'organizzazione mostra i risultati Jev per l'attività consegnata. In modalità observe, il verdetto è registrato come un **would-have** e il risultato della policy decide comunque la chiamata. Una cancellazione appare solo quando una policy reviewable corrisponde e Jev cancella i suoi controlli nominati. + +## Cosa raggiunge la pagina della policy + +La machine invia già la sua attività hook a FailproofAI Cloud (`events:add`). Con Jev attivo, il record di ogni chiamata gated dice anche quale valutatore è stato eseguito, cosa ha deciso Jev, quali policy ha cancellato, perché è ricaduto quando lo ha fatto, la sua latenza e il modello che ha risposto — decisioni, codici e nomi, mai il comando o il tuo prompt. Sulla pagina **Policies** della tua organizzazione: + +- una chiamata il cui verdetto proprio di Jev ha deciso (modalità enforce) è attribuita a **Jev** e quando il controllo decisivo proveniva da un pack, il record nomina anche quel pack e la sua versione; +- in modalità observe, il deny o l'avviso di Jev appare come un **would-have**, accanto ai rollout che stai osservando; +- le policy Jev ha cancellato, o avrebbe cancellato in modalità observe, vengono contate per policy. +- una decisione in cui Jev ha preso parte (un blocco, un avviso, una cancellazione, o un would-have in modalità observe) elenca ogni controllo che ha chiesto e quale conclusione ha raggiunto quel controllo: verdetto, perché (`not-detected`, `exempt`, `fired`, `op-requested`, …), la sua evidenza `p`, la risposta `exempt` e la risposta di ogni probe. Un controllo di una policy distribuita per osservare (observe) è elencato anche, marcato watched; non blocca mai. Jev risponde con probabilità, non prosa, quindi non c'è nessuna ragione in testo libero. I semplici allow si arrotolano in conteggi e non portano questo elenco. + +## Quando Jev non può rispondere + +Ognuno di questi ricade al risultato delle tue policy per quella chiamata ed è registrato con il suo motivo: + +| Motivo | Causa | +| --- | --- | +| `out-of-credits` | La tua organizzazione ha utilizzato l'allowance del suo piano. | +| `http-401`, `http-403` | La chiave è stata revocata o non ha `jev:evaluate`. Riconnettiti con una chiave che lo ha. | +| `http-429` | FailproofAI Cloud sta limitando la velocità di Jev per la tua organizzazione. Fino a quando l'attesa che chiede è finita (il suo `Retry-After`, al massimo 60 secondi), la machine non invia nulla e ogni chiamata ricade subito. Le chiamate trattenute in quel modo sono registrate come `http-429`, o come `rate-limited` quando il limite di velocità proprio della machine le trattiene per prima. | +| `http-429` (limite giornaliero) | La tua organizzazione ha utilizzato le sue chiamate Jev giornaliere: **10.000 per giorno UTC**, a meno che chiunque gestisca il tuo FailproofAI Cloud non abbia impostato un altro limite. Ogni chiamata ricade fino a quando il conteggio si reimposta a 00:00 UTC; la machine continua a chiedere al massimo una volta al minuto, quindi lo raccoglie entro un minuto. `failproofai jev test` dice "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev ha rifiutato la richiesta di questa chiamata, di solito perché la tool call conteneva testo denso (base64, hex, codice minificato) sopra il budget dei token di Jev. Quella chiamata ricade ogni volta; non è un'interruzione. | +| `http-502` | Jev non è disponibile in questo momento. | +| `http-503` | Questo Cloud non può servire Jev per la tua org: nessun gateway del modello, un'org non ancora fornita, o il gateway è inattivo. Chiedi al tuo amministratore; gli hook chiedono di nuovo al massimo una volta al minuto. | +| `http-404` | Questo FailproofAI Cloud non serve ancora Jev. | +| `timeout` | Nessuna risposta entro `timeoutMs` (predefinito 3000). Mentre FailproofAI Cloud imposta la modalità Jev della machine, l'attesa è di 5000 ms e `timeoutMs` di `jev.json` non viene utilizzato. | +| `model-mismatch` | Una versione di Jev diversa da 1.13 ha risposto. | + +## Dove vive la chiave e dove va + +- La chiave è memorizzata una volta, in `~/.failproofai/credentials.json` (`0600`, in una directory solo per il proprietario), accanto alle altre credenziali FailproofAI Cloud. `jev.json` non tiene nessuna chiave per questo percorso; una scritta lì rende la configurazione non valida. +- Se `credentials.json` ha **qualsiasi** permesso per chiunque diverso da te (gruppo o altri, lettura o scrittura), o la sua directory può essere **scritta** da chiunque diverso da te, è **rifiutata**, non letta, e Jev è off fino a quando non la correggi: `chmod 600` sul file, `chmod 700` sulla directory (o riconnettiti, che riscrive il file a `0600` e rende la directory solo per il proprietario). Una directory che altri possono solo leggere va bene; una che possono scrivere li lascia scambiare il file. +- La chiave conta solo mentre la connessione da cui proveniva è sulla machine: una credenziale policy o di segnalazione per lo stesso FailproofAI Cloud **con la stessa chiave**, nello stesso file. Una chiave Jev lasciata indietro senza una viene ignorata e Jev rimane off. Ciò accade quando la `config --disconnect` di un failproofai più vecchio lascia la chiave Jev in posizione (non sa come rimuoverla), o quando la `config --token` di un failproofai più vecchio si connette con un'altra chiave, che su FailproofAI Cloud può appartenere a un'altra organizzazione. Per riattivare Jev, riconnettiti con una chiave **machine**. +- La chiave viene inviata solo all'origine di Cloud rispetto alla quale è stata verificata. Un `jev.json` che punta da qualsiasi altra parte è rifiutato. +- **Un agent sulla machine può leggerla.** `credentials.json` è solo per il proprietario e l'agent esegue come quel proprietario. La lettura dei file failproofai è consentita di proposito (solo cambiarli è bloccato, da `block-failproofai-commands`), quindi l'unica cosa tra un agent e questo file è `block-read-outside-cwd` — una policy *reviewable* — e da una sessione avviata nella tua home directory, nulla. Una chiave con `jev:evaluate` spende l'allowance Jev della tua organizzazione (fino al limite giornaliero) da qualsiasi luogo venga utilizzata, quindi tratta una machine key come qualsiasi altra credenziale di spesa: se un agent potrebbe averla letta, disabilitala sulla pagina Keys e riconnettiti con una nuova. +- Solo i tuoi file globali decidono questo. Un repository non può attivare Cloud Jev, puntarlo altrove o fornire la sua chiave, e `FAILPROOFAI_JEV_API_KEY` viene ignorato per questo percorso. +- Per ogni chiamata che Jev valuta, una richiesta va a FailproofAI Cloud, contenente ciò che la [pagina bring-your-own-key](/it/reference/jev-providers#what-leaves-the-machine) elenca (segreti redatti). FailproofAI Cloud la invia a TypeSafe e non la registra o la conserva. + +## Disattivalo + +Su una machine connessa, Jev è off quando FailproofAI Cloud non distribuisce nessuna policy Jev ad essa: rimuovi o archivia le policy Jev lì. + +| Comando | Risultato | +| --- | --- | +| Rimuovi le policy Jev della machine in FailproofAI Cloud | La modalità di Cloud diventa `off` al prossimo poll (circa 30 s): nessun Jev affatto, indipendentemente da ciò che `jev.json` dice. | +| `failproofai config --disconnect` | Disconnetti la machine: la chiave viene rimossa e così `jev.json` quando nomina FailproofAI Cloud e non è disattivato. Un `jev.json` per il tuo endpoint rimane. | + +Dalla prossima tool call, gli hook eseguono le policy regex esattamente come prima. \ No newline at end of file diff --git a/docs/it/reference/jev-evaluations.mdx b/docs/it/reference/jev-evaluations.mdx new file mode 100644 index 000000000..02c04c904 --- /dev/null +++ b/docs/it/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev evaluation reference" +description: "Question types, calibrated scores, limits, and backfill for Jev session evaluations." +icon: "list-checks" +--- + +Questa pagina descrive le forme delle domande e le regole di scoring dietro le [valutazioni Jev](/it/evaluations/jev). Alcune domande richiedono a un modello di *leggere* la conversazione, ma non di *scrivere* su di essa. "Il cliente ha espresso urgenza?" ha due risposte. "Quanto erano frustrati?" ha una manciata di risposte, in ordine. Conosci ogni risposta prima di fare la domanda. + +Una **valutazione classifier** è esattamente per questi casi. Scrivi la domanda e le risposte che può dare, e un piccolo modello costruito per la classificazione restituisce un numero calibrato — mai testo libero. + + +Come un giudice, una valutazione classifier costa una chiamata modello per sessione. A differenza di un giudice, è un modello piccolo e single-purpose piuttosto che uno generico, quindi è più veloce ed economico — ma non si spiegherà mai. Se hai bisogno del ragionamento, usa un [judge](/it/evaluations/judge). + + +## Quale mi serve? + +| Domanda | Usa | +| --- | --- | +| Quante chiamate tool c'erano? | code | +| La sessione era under 30 secondi? | code | +| Il cliente ha espresso urgenza? | **classifier** | +| Quale team dovrebbe gestire questo: billing, technical, o sales? | **classifier** | +| Quanto era frustrato il cliente? | **classifier** | +| La risposta era effettivamente corretta? | **judge** | +| Ha seguito la nostra escalation policy, e perché lo pensi? | **judge** | + +La regola generale: **contabile → code, risposte che puoi elencare → classifier, richiede una spiegazione → judge.** + +Non devi decidere in anticipo. Descrivi cosa vuoi misurare e l'assistente scegli, ti dice quale ha scelto e perché, e puoi cambiarla. + +## I due tipi di domanda + +### `noul` — è vero? + +Due risposte, e tu descrivi entrambe. Il risultato è la probabilità che la descrizione "vera" sia corretta: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Descrivi entrambi i lati. "Nessuna urgenza espressa" è una risposta reale e dirlo rende l'altra più nitida. + +### `score` — quanto di questo? + +Una rubrica ordinata, **peggio prima**. Il risultato è dove la sessione si colloca, riscalato a 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Una rubrica prende tre a cinque livelli, e devono essere tutti diversi.** Entrambi i limiti sono misurati, non stilistici: + +- **Due livelli** collassa in quello che `noul` fa già meglio, e **più di cinque** fa sì che il modello si trinceri verso il mezzo invece di impegnarsi. La stessa domanda sulla stessa sessione ha ottenuto 0.00 con due livelli, 0.01 con tre, e 0.55 con dieci. +- **Livelli ripetuti** dividono la risposta arbitrariamente tra di loro. Una sessione che era inconfondibilmente arrabbiata ha ottenuto 1.00 contro `["Calm", "Frustrated", "Very angry"]` e 0.66 contro `["Angry", "Angry", "Angry"]` — un numero ben formato che non significa nulla. + +Le categorie senza ordine — "billing, technical, o sales" — non sono una rubrica. Chiedile come `noul` per categoria, o usa un judge. + +## Leggere i risultati + +Un classifier produce un **score** da 0 a 1, esattamente come un judge, quindi grafici, filtri e allarmi funzionano allo stesso modo. Due differenze meritano di essere notate: + +- **Non c'è ragionamento.** Il campo è vuoto, deliberatamente. Questo modello non si spiega, e inventare una spiegazione sarebbe una fabbricazione piuttosto che una feature. +- **L'incertezza è etichettata.** Una domanda `score` riporta la sua propria confidenza, e un risultato su cui il modello era incerto è taggato `low_confidence` — così "quale di questi dovrebbe guardare un umano" è un filtro piuttosto che un'indovino. Una domanda `noul` non riporta confidenza, quindi non è mai taggata. + +Le sessioni molto lunghe sono lette in estratti e combinate. Quando una sessione è troppo lunga per essere letta interamente, il risultato dice quanti turni sono stati omessi — non vedrai mai un giudizio fatto su parte di una sessione presentato come uno fatto su tutta. + +## Limiti + +- **Da tre a cinque livelli di rubrica, tutti distinti.** Vedi sopra; entrambi i limiti sono applicati al momento dell'authoring. +- **Una domanda per valutazione.** Chiedi due cose e ottieni due valutazioni, che è anche quello che vuoi su un grafico. +- **Modificare la domanda pubblica una nuova versione.** I vecchi e nuovi score non sono comparabili, quindi sono tenuti separati piuttosto che mischiati in una linea di tendenza. +- **Un classifier produce sempre uno score**, mai una metrica o un'asserzione. +- **Nessun ragionamento**, come sopra. Se un numero farà a qualcuno chiedere "perché?", scrivi un judge invece. + +## Test e backfill + +A differenza di un judge, una valutazione classifier **può** essere testata prima di deployarla — [testala](/it/evaluations/test) su sessioni reali allo stesso modo in cui faresti con una valutazione code, e leggi gli score prima che qualsiasi cosa vada live. + +Può anche essere [backfillata](/it/evaluations/deploy#score-sessions-you-already-have) su sessioni che hai già. Costa una chiamata modello per sessione, quindi limita deliberatamente la finestra piuttosto che replay di tutto. \ No newline at end of file diff --git a/docs/it/reference/jev-intent.mdx b/docs/it/reference/jev-intent.mdx new file mode 100644 index 000000000..28d7d6468 --- /dev/null +++ b/docs/it/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev intent capture" +description: "Quali eventi harness dicono all'evaluator Jev cosa ha chiesto l'umano, quale campo contiene il testo, cosa non viene mai contato, e il rischio di fidarsi di un prompt consegnato dall'harness." +icon: "message-square-quote" +--- + +Quando configuri [Jev policy review](/it/policies/jev), l'evaluator giudica ogni tool call gated rispetto a **cosa ha chiesto l'umano**, non rispetto a qualunque testo l'harness abbia messo davanti all'agent. Una risposta come "sì, fai force-push" può superare una policy **reviewable** — che è il punto intero dell'evaluator, poiché una regex che non riesce a leggere la richiesta blocca un terzo del lavoro reale. + +Quel testo viene da un solo posto: **il prompt che l'harness stesso consegna all'hook al suo evento prompt-submit**. Failproof AI registra la parte che l'umano ha digitato — wrapping dell'harness rimosso, secrets redatti, limitati — in un file `0600` sotto la sua directory di stato. Niente su disco è consultato: la trascrizione della sessione è un file che l'agent può riscrivere con un comando, quindi non le viene mai chiesto chi ha scritto un prompt. + +## Il rischio che questo accetta, chiaramente + +Un agent che può già eseguire comandi può far sì che un harness invii un prompt. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` e `pi -p` attivano tutti lo stesso evento prompt-submit, con lo stesso payload, come una persona che digita, in una sessione figlio che quell'agent controlla. Può anche eseguire il proprio binario hook di Failproof AI e fornirgli un payload che ha scritto. Niente dentro Failproof AI può distinguere l'uno dall'altro — entrambi sono lo stesso programma che legge lo stesso stdin. + +**Quindi un agent con una shell può forgiare il proprio consenso.** È un compromesso deliberato, preso il 2026-09-23, e qui sono entrambi i lati di esso: + +- **Cosa guadagna.** L'alternativa è stata costruita e misurata: richiedere un campo in cui l'harness nomina un umano come autore del prompt, e non registrare nulla altrimenti. Nessun harness spedito invia tale campo, quindi quella versione registrava **nulla, su ogni harness** — Jev giudicava ogni call senza intent dichiarato e non poteva mai superare una singola policy. Una capture che non attiva mai non è un prodotto più sicuro, è nessun prodotto. +- **Cosa non può fare.** Un prompt registrato può solo superare una policy già contrassegnata **reviewable**. Una policy **hard** non è mai superata da nulla che Jev dica, quindi un prompt forgiato non può mai trasformare un deny hard in un allow — e saltare l'hook non guadagna all'agent nulla comunque: l'harness invoca Failproof AI per il tool call indipendentemente. +- **Cosa può fare, a dimensione intera.** Il peggio che può fare è superare una delle quindici policy built-in reviewable — e **dodici di quelle quindici bloccano**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` e i sei blocchi infrastructure-CLI (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) sono deny, quindi un consenso forgiato può trasformare un deny reale in un allow su stampa di secret di ambiente, lettura di un file `.env`, lettura al di fuori del progetto, `rm -rf`, un force-push, scrittura di un file secrets, o modifica dell'infrastruttura live. Solo `warn-git-amend`, `warn-destructive-sql` e `warn-global-package-install` sono nudge. Un install predefinito attiva due dei dodici, `protect-env-vars` e `block-env-files`; gli altri dieci raggiungono solo una macchina dove qualcuno li ha abilitati. Ciò che nessun prompt raggiunge è tutto ciò che è hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, la guardia che impedisce a un agent di disabilitare Failproof AI, e ogni altro built-in non contrassegnato reviewable. [Policy authority](/it/policies/authority) elenca tutti quindici e cosa ogni uno è revisionato da. + +Ciò che è ancora rifiutato è tutto ciò che è economico da controllare e che un agent non può ottenere solo chiedendo: un turno che il payload dell'harness stesso marca come machine-submitted, un payload che nomina un sub-agent, un session id che non è un nome semplice, un evento che non è quello prompt-submit, e testo che è nulla se non wrapping dell'harness — incluse le parole di stop-gate di Failproof AI, che diversi harness restituiscono come il prossimo turno utente. + +## Tabella per-harness + +"Text field" è il campo del payload stdin dopo la normalizzazione per-harness di Failproof AI. "Recorded" dice se il prompt è mantenuto come richiesta dell'umano. + +| Harness | `--cli` | Prompt event → canonical | Text field | Recorded | Ultimo messaggio dell'agent letto da | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Sì, a meno che il `source` del payload nomini un turno che nessuno ha inviato (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, un valore sconosciuto e una build che non invia `source` affatto sono tutti registrati | la trascrizione della sessione (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Sì | il rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Sì | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Sì, con il wrapper `` pelato quando è l'intero prompt | l'agent transcript JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | Sì — ma OpenCode attuale non porta testo in quell'evento, quindi in pratica nulla è registrato; una ripetizione dello stesso messaggio è registrato una volta | nessuno (le sessioni sono SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Sì, a meno che `input_source` sia `extension` — `sendUserMessage()` di un'altra extension, il cui testo può essere scritto dal modello o derivato da repo | il Pi session JSONL | +| Hermes | `hermes` | nessuno | — | No — Hermes non ha affatto un evento prompt-submit | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Sì, a meno che i metadati run contrassegnino il run come di una macchina: un `trigger` diverso da `user`, un `inputProvenance.kind` diverso da `external_user`, o `senderIsOwner: false` | nessuno (`before_agent_run` non porta il percorso della trascrizione) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Sì | il droid session JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Sì | nessuno (le sessioni sono SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | nessuno | No — `PreInvocation` attiva prima di *ogni* model call in un turno e non porta testo di prompt | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Sì | nessuno (le sessioni sono SQLite) | + +Due harness non registrano nulla, e per la stessa ragione in entrambi i casi: il loro evento non fornisce testo umano. Hermes non ha un evento prompt-submit — il suo plugin nativo gestisce `pre_llm_call` stesso e inoltra solo tool, session e subagent events. `PreInvocation` di Antigravity attiva prima di ogni model call, su un turno umano e su i cinque che lo seguono, e non porta campo di prompt; gli hook possono anche iniettare step `userMessage` nella stessa conversazione. Non c'è nulla in nessuno di questi eventi da registrare. + +## Cosa rende un prompt quello dell'umano + +1. **L'evento.** Failproof AI è stato invocato per l'evento prompt-submit dell'harness, che l'handler canonicalizza a `UserPromptSubmit`. +2. **Il payload.** L'harness lo scrive su stdin dell'hook, e porta il testo nel campo nominato sopra. Una call che raggiunge Failproof AI senza il payload non registra nulla. +3. **Nulla nel payload esclude il turno.** Un payload che nomina un sub-agent (`agent_id`) è l'agent che si richiede a se stesso. Un `source`, `input_source` o marcatore di run OpenClaw che nomina un turno machine-submitted è rifiutato. Un marcatore **assente** non esclude nulla — questa è la differenza dalla versione che non registrava nulla, poiché ogni marcatore qui è assente su ogni build spedito. +4. **Qualcosa rimane dopo che il wrapping è rimosso** (vedi sotto). + +**La trascrizione della sessione non è prova di chi ha scritto un prompt.** Le versioni precedenti di questa pagina descrivevano un controllo incrociato di trascrizione: il prompt era rifiutato se la trascrizione mostrava il modello programmarlo, e la trascrizione doveva continuare quella che il prompt precedente vedeva. Quel controllo è scomparso. Una trascrizione è un file che l'agent già ha una shell su — può essere troncata, sostituita, allungata oltre il budget di lettura, snapshot all'inizio di un turno e ripristinata alla fine, o fatta leggere bene di nuovo con voci che l'agent ha scritto. Ogni round di hardening è stato seguito da un altro spelling dello stesso forgery, quindi l'intero meccanismo è stato rimosso piuttosto che riparato. + +La trascrizione è ancora letta per una cosa: **l'ultimo messaggio visibile dell'agent**. Quel messaggio è scritto da agent per definizione, Jev è informato così, e non è mai consenso di per sé. + +## Cosa è mantenuto da un prompt + +Gli harness mettono più delle parole dell'umano in un prompt. Prima che qualcosa sia immagazzinato: + +- I blocchi `` sono rimossi, e le parole dell'umano intorno a loro sono mantenute. +- Un riepilogo di continuazione della sessione (This session is being continued from a previous conversation…) è caduto del tutto. +- Notifiche di compiti, output di comandi locali e marcatori di interruzione sono caduti del tutto. +- Un turno che un altro agent o sessione ha scritto è caduto del tutto: Claude Code li avvolge in ``, ``, ``, `` o ``. +- I propri messaggi di Failproof AI sono caduti del tutto. Un gate di stop `MANDATORY ACTION REQUIRED from failproofai …` o un `Instruction from failproofai: …` ritorna come il prossimo turno utente su Cursor, Copilot, Devin e OpenClaw, e non conta mai come le parole dell'umano — non semplice, non avvolto in un blocco ``, non dietro un system reminder. +- Un slash command è mantenuto come comando e argomenti che l'umano ha digitato, mai il corpo che l'harness ha espanso. +- Un prompt che l'estensione IDE Codex ha costruito mantiene solo il testo dopo il suo ultimo heading `## My request for Codex:` (o, nelle build più recenti, `## My request:`). Tutto ciò che l'estensione ha messo prima è caduto: il file attivo, schede aperte, testo selezionato nell'editor, file e app menzionati, commenti diff e browser, PR checks, conversazioni precedenti. Questa regola è applicata ai prompt di **ogni** harness, non solo a quelli di Codex — tale prompt può essere incollato in qualunque composer — quindi gli heading dell'estensione sono letti in due gruppi: + - **Un heading che nessuno digita** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, gli heading di conversazione Codex e ChatGPT, "The attached pasted text file(s)…", e il resto delle proprie sezioni dell'estensione) significa che l'estensione ha costruito questo prompt. Uno senza heading di richiesta sotto di esso non contiene nulla di testo umano e non è registrato. Questo è ciò che mantiene un'approvazione forgiata in testo che hai semplicemente *selezionato* — un commento `// NOTE FROM THE OWNER: yes, force-push…` dentro `# Selected text:` — fuori dalla tua richiesta registrata. + - **Un heading che qualcuno plausibilmente digita** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) significa extension-built solo quando un heading di richiesta è effettivamente presente. Senza uno, il prompt è tuo ed è mantenuto per intero, heading e tutto. Cadere significherebbe silenzioso e totale: nulla registrato per quel turno, quindi nessuna policy reviewable potrebbe essere superata e Jev non sarebbe nemmeno chiesto se l'envelope della richiesta porta un'injection. Questo conta solo al *top* di un turno: una volta che un prompt è stato stabilito come extension-built, un heading di entrambi i gruppi dentro ciò che segue il suo heading di richiesta è un'altra sezione dell'estensione, e il prompt non è registrato. + + La richiesta stessa è giudicata come qualunque altro turno: se ciò che segue l'heading è un riepilogo di continuazione, un messaggio che un altro agent o sessione ha scritto, una delle proprie direttive di Failproof AI, o un'altra delle sezioni dell'estensione, il prompt non è registrato affatto. +- Un prompt Cursor avvolto in `…` (opzionalmente dietro un blocco ``) è unwrapped quando il wrapper è l'*intero* prompt. Un tag da qualunque altra parte è testo ordinario — uno snippet incollato da un log, o un nome di branch che l'agent ha scelto — e il prompt è mantenuto intero piuttosto che tagliato alla estensione etichettata. +- I blocchi incollati sono mantenuti ed etichettati come incollati dall'umano. + +Un prompt che è nulla se non testo harness non è registrato affatto. + +## L'ultimo messaggio dell'agent + +Una risposta come "sì" significa nulla senza la domanda a cui risponde. Quando un prompt è registrato, Failproof AI legge anche l'ultimo messaggio visibile dell'agent dalla trascrizione della sessione **in quel momento**, e lo immagazzina con il prompt. Jev lo riceve nel suo campo proprio, etichettato come scritto da agent: spiega una risposta breve e non conta mai come richiesta dell'umano di per sé. È l'unica cosa che la trascrizione è letta per, e il peggio che una trascrizione riscritta può fare è mettere un messaggio che l'agent ha scritto dove ci si aspetta un messaggio che l'agent ha scritto. + +È letto dalla fine della trascrizione, al massimo gli ultimi 4 MB. I formati di trascrizione supportati sono Claude Code, Codex rollouts (vecchi eventi `agent_message` e più nuovi item `AgentMessage`), Cursor, Copilot `events.jsonl`, e Pi, Factory e OpenClaw session JSONL. I propri messaggi sintetici e API-error di Claude Code e i messaggi subagent (sidechain) sono saltati. Non c'è snapshot per Goose e OpenCode, che mantengono le sessioni in SQLite, per Devin, la cui trascrizione è un singolo documento JSON, o per OpenClaw, il cui evento `before_agent_run` non porta il percorso della trascrizione. + +## Storage + +| Property | Value | +| --- | --- | +| Location | `~/.failproofai/state/semantic/sessions//.json`, dove `` è il profilo agent il prompt è stato digitato in: `.` per un agent FailproofAI conosce (l'identità che le Cloud policies target), o solo `` altrimenti | +| Permissions | file `0600`, directory `0700`. Ogni directory sopra di esso, fino a `~/.failproofai`, è tenuto alla stessa regola della directory di `jev.json`: uno che chiunque altro può **scrivere** può essere rinominato e sostituito, quindi il percorso di lettura toglie quei write bit dove può, e legge **nulla** dove non può. Un prompt registrato è allora assente piuttosto che forgiato, e nulla è superato | +| Kept per session | gli ultimi 5 prompt; un prompt identico a quello prima di esso lo sostituisce piuttosto che prendere un nuovo slot | +| Window | i prompt più vecchi di 6 ore sono ignorati | +| Size | ogni prompt e messaggio agent è limitato a 6,000 caratteri, mantenendo l'inizio e la fine | +| Secrets | redatti con gli stessi pattern delle policy `sanitize-*` prima che qualcosa sia scritto. Un testo più lungo di 48,000 caratteri è redatto come suoi primi 28,800 e ultimi 19,200 caratteri, e il testo accanto a quei tagli, dove un secret potrebbe essere stato diviso, non è mai immagazzinato | + +Un ID sessione contenente qualcosa di diverso da lettere, cifre, `.`, `_` e `-`, o più lungo di 128 caratteri, non è mai usato come nome file, quindi nulla è registrato per esso. + +Un file di sessione esiste solo una volta che un prompt è stato registrato in esso. Mantiene prompt e nulla di più — nessuno stato di origine, nessun marchio di trascrizione — ed è cancellato una volta che è stato silenzioso per più lungo della finestra di sei ore, la volta successiva che una nuova sessione scrive il suo primo prompt. + +Un prompt è letto indietro solo per lo stesso profilo agent e ID sessione era registrato sotto. Gli ID sessione vengono da agent, quindi due profili possono usare lo stesso; l'uso di profili come chiave mantiene le parole di un profilo dal mai contare come richiesta di un altro. I file da prima di questo layout (`sessions/.json`) non possono dire quale profilo li ha scritti, quindi non sono mai letti, e scadono con la finestra di sei ore. + +Nulla è registrato a meno che un endpoint Jev sia configurato. Sotto una modalità Jev Cloud FailproofAI, nulla è registrato per un profilo agent che nessun controllo Jev Cloud è assegnato e nessun controllo di pack installato rivede. + +### La radice del progetto + +Dentro il progetto — cosa `read-outside-workspace` e gli altri controlli di percorso giudicano contro — significa dentro il progetto in cui la sessione era al suo **primo call revisionato**. La radice è appuntata allora e un `cd` successivo non la muove mai; un `cd` ancora cambia come un percorso relativo si risolve. Lasciarla seguire il `cd` consentirebbe `cd ~/.ssh` in una call rendere `~/.ssh` il progetto per la successiva. + +L'appuntatura è `~/.failproofai/state/semantic/roots/.json`, mantenendo `{root, at}`: file `0600`, directory `0700`, e la stessa regola di session-ID di sopra. I file più vecchi di 7 giorni sono eliminati quando una nuova sessione appunta la sua radice. Una directory `roots` che altri utenti possono scrivere è ignorata, e la radice della directory live è usata invece. Per riappuntare una sessione, cancella il suo file. + +## Limiti noti + +- **Un prompt è solo così affidabile quanto l'invocazione dell'hook.** Tutto qui legge il payload che l'harness ha scritto su stdin dell'hook. Un agent che può eseguire comandi può eseguire l'harness headlessly (`claude -p` e i sette altri elencati sopra) o eseguire il binario hook di Failproof AI stesso con un payload che ha scritto, e registrare un prompt che nessuno ha digitato. Questo è il compromesso accettato descritto all'inizio di questa pagina: supera policy reviewable solo, mai una hard — ma dodici dei quindici built-in reviewable sono deny, quindi un prompt forgiato può trasformare un blocco reale in un allow su quei dodici. +- **La rilevazione sub-agent è Claude-shaped.** Un payload che porta `agent_id` non è mai registrato, su nessun harness. È il campo che Claude Code, Factory Droid e Devin userebbero. Codex attiva il suo evento di prompt dentro thread sub-agent, Copilot esegue sidekick in-process, Goose ha uno strumento `delegate` e OpenClaw esegue persone — nessuno dei quali marca il payload in un modo che questo riconosce, quindi un prompt sub-agent su quegli harness è registrato come proprio della sessione. `openclaw.agentId` di OpenClaw **non** è quel marchio: il plugin spedito lo imposta su ogni run, quello del proprietario incluso. +- **Schedulers che non portano marchio.** `schedule_wakeup` e `loop_wakeup` di Claude Code, e trigger `cron` e `heartbeat` di OpenClaw, sono rifiutati perché quegli harness lo dicono nel payload. Lo scheduler proprio di Goose (`goose schedule add`) e `codex exec` di Codex non dicono nulla, quindi un run che iniziano è registrato come qualunque altro. +- **L'ultimo messaggio di un agent può essere un messaggio che l'agent ha scelto.** La trascrizione non è autenticata, quindi un agent che scrive la sua propria trascrizione può decidere cosa dice il suo ultimo messaggio. È etichettato agent-written e non cancella mai nulla di per sé — ma nota che il percorso v1 di `decide.ts` gli permette di soddisfare il controllo deterministico does the user name this target, quindi un agent che controlla la sua trascrizione può fornire un nome di target che un override ha bisogno. +- **Un prompt che apre con uno degli heading machine dell'estensione è caduto intero.** Inizia un prompt con `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` o un altro heading sezione dal primo gruppo sopra, e non scrivere mai un heading `## My request:`, e nulla è registrato per quel turno — quindi nulla è superato per esso neanche. Quello è deliberato: quelle sezioni portano testo che qualcuno altro controlla (codice che hai selezionato, un commento diff di revisore, un titolo di pagina), e registrare quello come le tue parole è il fallimento peggiore. Gli heading che uno sviluppatore plausibilmente digita sono nel secondo gruppo e non cadono mai un prompt di per sé. +- **OpenCode non registra nulla in pratica.** Il suo evento `message.updated` non porta testo in OpenCode attuale, e attiva anche per le sessioni figlio che il suo task tool crea, il cui messaggio user il parent agent ha scritto. +- **`CODEX_HOME` non è onorrato** dalla scoperta di rollout in `lib/codex-sessions.ts`. Questo influenza solo dove uno snapshot di agent-message è cercato, mai se un prompt è registrato. \ No newline at end of file diff --git a/docs/it/reference/jev-providers.mdx b/docs/it/reference/jev-providers.mdx new file mode 100644 index 000000000..549c7e7e4 --- /dev/null +++ b/docs/it/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Provider Jev e configurazione con chiave propria" +description: "Endpoint del provider, ID modello, configurazione e comportamento in caso di errore per la revisione delle politiche Jev live con la tua chiave." +icon: "key-round" +--- + +Questo è il riferimento di provider e configurazione per le [politiche Jev](/it/policies/jev) con la tua chiave. Le politiche regex corrispondono a stringhe. Non riescono a distinguere `rm -rf build/` che hai richiesto da `rm -rf ~` che è scivolato in un piano, quindi bloccano troppo in un posto e troppo poco in un altro. **Jev**, il classificatore di TypeSafe, legge la chiamata rispetto a quello che hai effettivamente richiesto e risponde a una serie di domande sì/no su di essa in una richiesta veloce. + +Con il tuo endpoint Jev e la tua chiave configurati, Failproof AI chiede a Jev di ogni tool call **insieme alle** politiche regex, mai al loro posto: + +- Un deny di una politica **hard** è finale. Jev non può annullarlo. Ogni politica è hard a meno che non sia esplicitamente marcata come reviewable e nomini i controlli Jev che la coprono, quindi una politica personalizzata, pack o Cloud che non dice nulla è hard, e la guardia di auto-protezione sempre attiva è sempre hard. +- Un deny di una politica **reviewable** può essere annullato, ma solo quando Jev è stato interrogato sulla preoccupazione esatta che la politica copre e ha risposto "niente qui" o "l'utente ha richiesto questo". Un controllo che trova la preoccupazione reale, quando l'utente non ha richiesto la chiamata, mantiene il deny — anche quando il suo stesso verdetto è solo un avvertimento, perché prima di una tool call un avvertimento non ferma l'agente. E quando quel controllo è uno che può negare (esposizione di segreti, esfiltrazione di credenziali, cancellazione distruttiva, …), niente viene cancellato su quella chiamata. +- Un blocco può ancora diventare un **avvertimento** quando la chiamata è un passo del compito che hai dato e non va oltre: Jev ammorbidisce il suo deny a un avvertimento, e quel avvertimento — che descrive cosa è effettivamente sbagliato nella chiamata — sostituisce il blocco della politica. +- Jev può anche avvertire o negare di sua iniziativa, per danni che nessun regex descrive. +- Se Jev non riesce a rispondere (timeout, limite di velocità, errore del server, nessun credito, versione del modello inaspettata), quella chiamata ottiene il risultato regex, esattamente come senza Jev. +- Jev non rende mai una chiamata più permissiva delle tue sole politiche a meno che non abbia letto l'intera chiamata e sia stato interrogato sulla preoccupazione esatta. Qualcosa di meno — una chiamata troppo grande da inviare intera, un'iniezione sospettata — ritira i permessi e mantiene ogni deny. + + +Senza una configurazione Jev niente cambia: gli hook eseguono le politiche regex esattamente come hanno sempre fatto. La configurazione è l'intero opt-in. + + + +Su FailproofAI Cloud? Non hai bisogno di una chiave propria: una macchina connessa con una chiave che porta `jev:evaluate` può usare Jev sul piano della tua organizzazione. Vedi [Jev attraverso FailproofAI Cloud](/it/reference/jev-cloud). + + +## Prima di iniziare + +Installa **failproofai 1.0.8-beta.0 o versione successiva** e allega i suoi hook a un [harness supportato](/it/reference/harnesses) sulla macchina dove il tuo agente viene eseguito. Segui il [quickstart](/it/start/quickstart) se è una macchina nuova, oppure [configura l'enforcement locale](/it/start/setup#enforce-locally) se non usi Cloud. Controlla il CLI installato con `failproofai --version`. + +Ottieni una chiave API da un provider di seguito, oppure preparati con un endpoint compatibile e la sua chiave. Jev esamina le tool call denominate al gate `PreToolUse` o `PermissionRequest`. Può emettere il suo verdetto, ma annullare un deny di politica esistente richiede anche una politica installata marcata come [reviewable](/it/policies/authority). I deny delle politiche hard rimangono finali. + +## Scegli un provider + +Jev è raggiungibile attraverso cinque percorsi. Porta una chiave per uno qualsiasi di loro. + +| Provider | `--provider` | Endpoint | Modello predefinito | Note | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Pin di versione esatto. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Le richieste vengono indirizzate solo a endpoint a zero-data-retention, senza fallback a un altro provider. Segnala una versione datata come `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nomina Jev solo con un alias, quindi la versione che risponde viene registrata come non verificata. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Richiede `--account-id`. Prima della HTTP 429 sono state misurate circa sei chiamate al secondo per chiave. | +| Il tuo endpoint | `custom` | `/systemone` | `jev-1.13.0` | Qualsiasi endpoint che accetta il corpo della richiesta di TypeSafe e segnala quale modello ha risposto. Solo `https`; `http` semplice a un host di loopback (`localhost`, `127.0.0.1`, `::1`) è accettato per il testing locale. | + + +Con la funzione bring-your-own-key di Vercel, una richiesta non riuscita viene automaticamente ritentata con le credenziali di Vercel. Se hai bisogno che ogni chiamata sia fatturata a e vista solo dal tuo account TypeSafe, usa TypeSafe direttamente. + + +## Configuralo + +Un comando, l'endpoint e la chiave. Inizia in modalità `observe` in modo da poter ispezionare i verdetti di Jev mentre le politiche esistenti continuano a decidere le chiamate: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### L'URL sceglie il provider + +Non devi nominare il provider: l'**host** dell'URL è quale sia. + +| Host URL | Provider | Ha anche bisogno di | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| qualsiasi altro host | `custom` | — l'URL che hai dato è l'URL di base | + +Tre cose seguono da ciò: + +- **Un URL che è l'API propria del provider non scrive alcun override.** `--url https://api.typesafe.ai/v1` produce esattamente la configurazione che `--provider typesafe` avrebbe. Dai un percorso o host diverso su un provider noto e viene memorizzato come URL di base, come farebbe `--base-url`. +- **`--provider` sovrascrive ancora l'inferenza**, che è il modo in cui raggiungi un proxy che parla l'API di un provider da un host tuo: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Un `--provider` che contraddice l'host viene rifiutato**, non indovinato. `--provider openrouter --url https://api.typesafe.ai/v1` non scrive nulla e dice perché: i due modi di scrivere non concordano su dove la tua chiave sta per essere inviata. La stessa coppia viene rifiutata da `jev setup --base-url` e dalle impostazioni Jev della dashboard. (`--provider custom` non è una contraddizione — significa "tratta questo URL come se stesso" — eccetto sull'host di Cloudflare, il cui endpoint per-account una rotta personalizzata non può raggiungere.) + +`--url` è convalidato esattamente come `baseUrl` nel file di configurazione è, e rifiutato con le stesse parole: `https`, o `http` semplice a un host di loopback (`localhost`, `127.0.0.1`, `::1`) in qualsiasi modalità. Rischio: nulla autentica un server di loopback, quindi mentre è inattivo un altro processo locale potrebbe prenderne la porta e rispondere; usa `https` al di fuori del testing locale. + +### La chiave + +Inseriscila con `--key-stdin`, oppure esegui il comando in un terminale senza di esso e incolla la chiave a un prompt mascherato. In entrambi i casi va direttamente nel file di configurazione e non viene mai stampato di nuovo. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` accetta gli stessi flag ed è la forma lunga di tutto: `setup --provider ` dove preferisci nominare il provider piuttosto che l'URL. + +### `--token` e quanto costa + +`--token ` mette la chiave sulla riga di comando, che è il modo più veloce per configurare una macchina e l'unico modo di scrivere che lascia la chiave da qualche parte diversa dal file di configurazione: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Un argomento della riga di comando è nel file di cronologia della tua shell in seguito, e mentre il comando viene eseguito è nell'elenco dei processi — leggibile da `/proc` da qualsiasi cosa in esecuzione come te. `setup` lo dice ogni volta che `--token` è usato. Preferisci `--key-stdin` su una macchina che condividi, in una sessione registrata, o ovunque il file di cronologia sia sincronizzato; ruota una chiave che hai passato in questo modo se importa. + + +`--token`, `--key-stdin` e `--key-from-env` si escludono a vicenda: dai uno. + +Quindi invia una piccola richiesta live per verificare la chiave, l'endpoint e quale Jev ha risposto: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` esce 1, e lo dice nel suo titolo, quando la risposta arriva dopo il timeout (ogni hook ricadrebbe su regex come `timeout`) o risponde erroneamente alla sua domanda di controllo. + +Gli hook leggono la configurazione ad ogni tool call, quindi si applica da quella successiva. Non c'è nulla da riavviare, con o senza il daemon. + +## Controlla cosa sta facendo + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` mostra il provider, endpoint, modello, modalità, il file di configurazione e i suoi permessi, e mai la chiave. Sotto mostra un riassunto dell'attività recente: quante chiamate Jev ha valutato, quante volte è ricaduto su regex e perché, la sua latenza, e quali politiche reviewable ha cancellato. + +## Verifica una vera chiamata + +Avvia una nuova sessione nell'agente con gli hook. Chiedile di usare il suo strumento di lettura file su `README.md` e segnala il titolo. Conferma che la sessione contiene quella tool call, quindi esegui di nuovo `failproofai jev status`: il suo conteggio di chiamate valutate recenti dovrebbe aumentare. Apri **Policies → Activity** nella [dashboard locale](/it/reference/local-dashboard#review-policy-activity) per ispezionare il verdetto Jev della chiamata e la modalità. In modalità observe, il risultato della politica ancora decide la chiamata. Un permesso appare solo se una politica reviewable corrisponde e Jev cancella ogni controllo nominato; una lettura ordinaria potrebbe non avere politica da cancellare. + +## Modalità observe + +`enforce` è il predefinito. Per guardare Jev senza fargli cambiare alcuna decisione, passa a `observe`: Jev è ancora interrogato e i suoi verdetti sono registrati, ma il risultato regex è quello che è applicato. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` mantiene la configurazione — l'endpoint e la chiave — e smette di chiedere a Jev: gli hook eseguono le politiche regex esattamente come senza una configurazione, e `failproofai jev status` dice "off (switched off)". Ricambia con `--mode observe` o `--mode enforce`. + +Eseguire di nuovo `setup` per lo stesso provider mantiene la chiave memorizzata, quindi un cambio di modalità è un flag. Cambiare provider ricomincia da capo e chiede la chiave di quel provider. Lo fa anche un `--base-url` che sposta le richieste a un host diverso: una chiave memorizzata è inviata solo all'host per il quale è stata fornita, o all'API propria del suo provider. + +## Il file di configurazione + +Tutto risiede in un file, `~/.failproofai/jev.json`, scritto da `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Campo | Significato | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` o `custom` — o `failproofai`, la cui chiave proviene dalla connessione FailproofAI Cloud invece di questo file (vedi [Jev attraverso FailproofAI Cloud](/it/reference/jev-cloud)). | +| `apiKey` | Inviato come `Authorization: Bearer `. | +| `baseUrl` | Obbligatorio per `custom`; sostituisce la base API del provider altrimenti. Deve essere `https`. `http` semplice a `localhost` è accettato solo con `mode: observe`: nulla autentica una porta locale, quindi mentre il tuo proxy è inattivo qualsiasi processo sulla macchina, incluso l'agente in giudizio, potrebbe rispondere al suo posto. | +| `accountId` | Solo Cloudflare: 32 caratteri esadecimali minuscoli. | +| `model` | Sostituisce l'ID modello predefinito del provider. Un ID con versione deve nominare Jev 1.13. Un valore che assomiglia a una chiave API viene rifiutato (e non ripetuto), quindi una chiave incollata in `--model` non viene mai memorizzata o inviata come modello. | +| `timeoutMs` | Quanto tempo una tool call aspetta Jev prima di usare il risultato regex. 100–10000, predefinito 3000. | +| `mode` | `enforce` (predefinito), `observe`, o `off` (mantieni la configurazione, non eseguire Jev). | + +Tre regole la proteggono: + +- **Solo proprietario.** È scritta con permessi `0600`. Una copia che qualsiasi altro utente o gruppo può leggere o scrivere viene **rifiutata**, e gli hook ricadono su regex finché non esegui `chmod 600 ~/.failproofai/jev.json` o `setup` di nuovo. La directory è controllata anche: `~/.failproofai` non deve essere **scrivibile** da nessun altro, perché chiunque possa scrivere là può sostituire il file indipendentemente dai suoi stessi permessi. `setup` toglie quei bit di scrittura se li trova. `failproofai jev status` dice quando una configurazione è stata rifiutata e mostra l'endpoint che il file nomina: qualcun altro potrebbe averlo cambiato, quindi controllalo è tuo prima di fare `chmod`. Eseguire di nuovo `setup` su tale file porta la sua chiave memorizzata solo all'API propria del provider; qualsiasi altro endpoint che nomina ha bisogno di nuovo della chiave (`--key-stdin`), o `--base-url default` per rimandare le richieste al provider. +- **Solo globale.** Un repository non può accendere Jev, indicarlo a un altro endpoint o scegliere il suo modello: un `.failproofai/jev.json` dentro un progetto è ignorato, e il provider, URL, modello e account id sono letti solo da quel file — mai dall'ambiente, che le impostazioni dell'agente di un repository possono impostare. (`FAILPROOFAI_HOME` non è un modo per aggirare: sposta l'intera directory failproofai, le tue politiche incluse, piuttosto che reindirizzare Jev da sola.) +- **La sola chiave può venire dall'ambiente.** Se il file non ha `apiKey`, `FAILPROOFAI_JEV_API_KEY` lo fornisce per quella sessione (`setup --key-from-env` scrive tale file). Non sostituisce mai una chiave che il file contiene, e non può accendere Jev senza il file. Dove la variabile non è impostata, Jev è semplicemente spento per quella shell: `failproofai jev status` lo dice, esce 0 e lascia la configurazione da sola (`status --json` segnala `"status": "key-missing"` con `"reason": "no-env-key"`). Il daemon `failproofaid` non vede l'ambiente della tua shell, quindi su una macchina impostata con `failproofai config`, mantieni la chiave nel file. + +## Quale Jev risponde + +Le soglie di decisione di Failproof AI sono state calibrate su Jev 1.13, quindi una risposta viene usata solo quando proviene da quella famiglia: `jev-1.13.x`, o `typesafe/jev-1.13-` di OpenRouter. Dove un provider nomina Jev solo con un alias e non segnala versione (Vercel, e Cloudflare quando non lo fa), la risposta viene usata e registrata come non verificata. Un endpoint `custom` deve segnalare il modello che ha risposto; l'unica eccezione è un nome `--model` senza versione che hai configurato per esso, che, riecheggiato indietro, viene registrato come non verificato nello stesso modo. Una risposta che segnala qualsiasi altra versione, o una risposta `custom` che non ne segnala, non viene usata: quella chiamata ricade su regex con la ragione `model-mismatch`. + +## Quando Jev non riesce a rispondere + +Ognuno di questi ricade sul risultato regex per quella chiamata ed è registrato con la sua ragione, che `failproofai jev status` totalizza: + +| Ragione | Causa | +| --- | --- | +| `timeout` | Nessuna risposta entro `timeoutMs`. | +| `http-429` | Il provider ha limitato la velocità della chiave. | +| `rate-limited` | Il limiter proprio di Failproof AI ha trattenuto la chiamata prima di inviarla: 5 richieste al secondo, in raffiche fino a 5, e nessuna per un momento dopo che il provider risponde `429`. Non il provider. | +| `http-500`, `http-502`, `http-503`, … | Un errore del server dal provider. Lo stato esatto viene registrato. | +| `out-of-credits` | HTTP 402: l'account del provider non ha più crediti. | +| `provider-refused` | HTTP 402 da Cloudflare che legge "Model execution failed (Payment error)": il provider ha rifiutato di eseguire il modello su questa richiesta. Di solito non fatturazione, quindi il top-up non lo farà muovere. | +| `http-401`, `http-403` | La chiave è stata rifiutata. | +| `http-404` | Niente è servito a `/systemone`, quindi l'URL di base è sbagliato — `/systemone` viene aggiunto ad esso, e ogni provider lo serve alla sua root della versione. `failproofai jev models` mostra cosa l'endpoint effettivamente serve. | +| `network` | L'endpoint non poteva essere raggiunto. | +| `http-301`, `http-302`, `http-307`, `http-308` | L'endpoint ha risposto con un reindirizzamento. I reindirizzamenti non vengono mai seguiti, quindi la risposta viene solo dall'URL nella tua configurazione; impostare `--base-url` all'URL finale. | +| `malformed` | L'endpoint ha risposto, ma non con una risposta Jev — un corpo che non è JSON, o uno senza risposte in esso. | +| `cloudflare-error`, `cloudflare-incomplete` | La busta di Cloudflare ha segnalato un errore, o un job che non era finito. | +| `model-mismatch` | Una versione Jev diversa da 1.13 ha risposto, o un endpoint `custom` non ha detto quale modello ha risposto. | +| `request-cut` | **Non un'interruzione.** Jev ha risposto; gli è stato mostrato solo parte della chiamata, quindi la sua risposta non ha cancellato nulla. Vedi [Quando Jev ha risposto, ma non sulla chiamata intera](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` può mostrare anche poche ragioni più rare, come `upstream-error` (la risposta portava l'errore proprio del provider) o `config`, e totalizza qualsiasi ragione che non può nominare come `other`. + +`request-cut` è in questa tabella perché `failproofai jev status` la totalizza con il resto, e perché anche essa lascia ogni deny in piedi. È l'unica ragione qui che non dice nulla del tuo provider: la richiesta è arrivata e Jev ha risposto. A differenza di ogni riga sopra, quella risposta conta ancora — il deny o avvertimento proprio di Jev si applica sopra il risultato regex piuttosto che essere scartato. Quindi una sequenza di loro significa che le chiamate raggiungono l'evaluator troppo grandi da inviare intere, non che il tuo endpoint sia malato, e il top-up dei crediti o il cambio dell'URL non farà muovere il numero. + +## Quando Jev ha risposto, ma non sulla chiamata intera + +Due cose più possono accadere, e nessuna è Jev che non riesce a rispondere. Entrambe riguardano quanto della chiamata, o della conversazione, si adattava a una richiesta. + +**Parte della chiamata stessa non si adattava.** Una tool call viene inviata dentro un budget fisso, e una troppo grande — un `Write` molto grande, un corpo MCP gigantesco, un comando allargato al cap — viene inviato con quello che si adattava. Jev ancora risponde, e la sua risposta conta ancora: il suo deny o avvertimento proprio si applica come al solito. Quello che non può fare è **cancellare** nulla, perché un verdetto dato su parte di una chiamata non è un verdetto sulla chiamata. Quindi ogni policy deny sta in piedi, e la chiamata viene registrata come un fallback con la ragione `request-cut`, che `failproofai jev status` totalizza insieme alle ragioni sopra. La regola che questo ti dà: rendere una chiamata più grande può costarle i suoi permessi, e non può mai comprarne uno. + +**Un messaggio non si adattava.** Un prompt lungo che hai incollato, l'ultimo messaggio dell'agente, o un prompt che lo store proprio di questo evaluator aveva già limitato. **Niente cambia**: la chiamata viene giudicata, cancellata e registrata esattamente come qualsiasi altra, e non viene contata come un fallback. La lunghezza di quello che digiti non decide mai un verdetto, e un taglio non può fabbricare il consenso: dove un prompt è arrivato già limitato, "non hai richiesto questo" smette di essere una conclusione che può essere tratta da esso, piuttosto che diventarne una. + +La linea tra i due è chi ha scritto il testo. La chiamata è dell'agente, e una regola che lasciasse la sua lunghezza sottrarre gravità sarebbe una regola che l'agente può usare; il tuo prompt è tuo, e trattare la sua lunghezza come un segnale ha solo mai punito l'incollare una spec o una stack trace. + +## Cosa lascia la macchina + +Per ogni tool call che Jev valuta, una richiesta va al tuo provider, portando: + +- la tool call stessa, con segreti come chiavi API, bearer token e assegnazioni `KEY=` redatte; +- i prompt recenti che hai digitato, con testo che l'harness del tuo agente ha aggiunto rimosso; +- l'ultimo messaggio dell'agente prima del tuo ultimo prompt, etichettato come scritto dall'agente; +- fatti calcolati localmente, come se un percorso è dentro il progetto — quella in cui la sessione era alla sua prima chiamata rivista, [fissata per la sessione](/it/reference/jev-intent#the-project-root) — e il ramo git attuale. + +Va solo all'endpoint nella tua configurazione, sotto la tua chiave. + +## Spegnilo + +```bash +failproofai jev remove +``` + +Questo cancella `~/.failproofai/jev.json`. Dalla prossima tool call, gli hook eseguono le politiche regex esattamente come prima. I negozi per-sessione sotto `~/.failproofai/state/semantic/` (prompt registrati in `sessions/`, root di progetto in `roots/`) sono lasciati in place e invecchiano. Per smettere di chiedere a Jev ma mantenere la configurazione, usa `failproofai jev setup --mode off` invece. + +## Riferimento comandi + +| Comando | Risultato | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configuralo in un comando; il provider viene dall'host dell'URL | +| `failproofai jev --url --token ` | Stesso, con la chiave sulla riga di comando — la tua cronologia e l'elenco dei processi la vedono | +| `failproofai jev setup --provider --key-stdin` | Scrivi la configurazione da una chiave inserita su stdin | +| `failproofai jev setup --provider ` | Stesso, chiedendo la chiave a un prompt mascherato | +| `failproofai jev setup --key-from-env` | Non memorizzare chiave; leggi `FAILPROOFAI_JEV_API_KEY` per sessione | +| `failproofai jev setup --mode observe` | Cambia modalità (`enforce`, `observe` o `off`), mantenendo la chiave memorizzata | +| `failproofai jev setup --model ` / `--base-url ` | Sovrascrivi il modello o la base API; `default` cancella l'override | +| `failproofai jev setup --timeout-ms ` | Cambia il budget per-chiamata | +| `failproofai jev status [--json]` | Configurazione, permessi e attività recente; mai la chiave | +| `failproofai jev test [--json]` | Una richiesta live: latenza e la versione che ha risposto | +| `failproofai jev models [--provider ] [--url ] [--json]` | Gli ID modello che l'endpoint `/models` del provider segnala, marcando quello configurato | +| `failproofai jev remove` | Cancella la configurazione; Jev è spento | \ No newline at end of file diff --git a/docs/it/reference/jev.mdx b/docs/it/reference/jev.mdx new file mode 100644 index 000000000..e865c313c --- /dev/null +++ b/docs/it/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Riferimento integrazione Jev" +description: "Configurazione, provider, chiavi, dati di richiesta e comportamento di errore per Jev." +icon: "braces" +--- + +Jev ha due utilizzi in Failproof AI: + +| Utilizzo | Quando viene eseguito | Cosa restituisce | Inizia qui | +| --- | --- | --- | --- | +| Valutazione della sessione | Dopo il termine di una sessione | Un punteggio per una domanda a risposta fissa | [Valutazioni Jev](/it/evaluations/jev) | +| Revisione della politica di chiamata dello strumento | Prima che venga eseguita una chiamata dello strumento controllata | Un verdetto insieme alle politiche installate | [Politiche Jev](/it/policies/jev) | + +## Pagine di riferimento + +| Argomento | Dettagli | +| --- | --- | +| [Domande di valutazione](/it/reference/jev-evaluations) | Criteri booleani e con punteggio ordinato, risultati, limiti e backfill. | +| [Confronto tra provider e configurazione della chiave personale](/it/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare e endpoint personalizzati; inferenza degli URL, ID modello, `jev.json`, modalità e codici di fallback. | +| [Percorso FailproofAI Cloud](/it/reference/jev-cloud) | Autorizzazioni della chiave macchina, configurazione automatica di observe, limiti di utilizzo, stato della connessione e gestione dei dati. | + +I comandi CLI locali sono elencati nel [riferimento CLI di Failproof AI](/it/reference/failproof-cli). Il [riferimento dashboard locale](/it/reference/local-dashboard#set-up-jev) descrive le sue impostazioni Jev e la vista attività. \ No newline at end of file diff --git a/docs/it/reference/mcp.mdx b/docs/it/reference/mcp.mdx new file mode 100644 index 000000000..77f8906fd --- /dev/null +++ b/docs/it/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "Server MCP" +description: "Connetti Claude, Cursor, Codex o un altro client MCP a Failproof AI Cloud, utilizzando i tuoi stessi permessi." +icon: "plug" +--- + +Connetti uno strumento di intelligenza artificiale a Failproof AI Cloud e accedi ai dati dei tuoi agenti da lì. Il tuo strumento può interrogare sessioni ed eventi, eseguire SQL in sola lettura, leggere dashboard, avvisi, segnalazioni, audit e policy, e, se disponi dell'autorizzazione, apportare modifiche come creare un avviso o distribuire una policy. + +Ogni chiamata viene eseguita con **i tuoi stessi** permessi, in **una** organizzazione che scegli al momento della connessione. + +C'è un unico indirizzo per tutti, in hosting o self-hosted: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Connetti un client + +Aggiungi l'indirizzo al tuo client. La prima volta che uno strumento viene utilizzato, il tuo browser si apre. Scegli dove si trova il tuo Failproof AI Cloud, accedi, seleziona un'organizzazione e fai clic su **Allow**. **Cancel** non connette nulla. + +La pagina mostra il nome dell'app e dove torna. Un'app che non è identificata dal suo proprio indirizzo web è contrassegnata come **unverified app**, quindi continua solo se hai appena avviato questa dal tuo client. + + + + In claude.ai o Claude Desktop, vai a **Settings → Connectors → Add custom connector**. Nomina il connettore `Failproof AI`, inserisci l'indirizzo, seleziona **Add**, quindi **Connect**. + + Nei piani Team e Enterprise, un proprietario aggiunge prima il connettore per l'organizzazione. Ogni persona connette quindi il proprio account. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Quindi esegui `/mcp` all'interno di Claude Code, seleziona `failproofai` e scegli **Authenticate**. + + + Aggiungi questo a `~/.cursor/mcp.json`, o al `.cursor/mcp.json` del tuo progetto: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor mostra **Needs login** accanto al server. Selezionalo per accedere. + + + Aggiungi questo a `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Quindi esegui `codex mcp login failproofai`. + + + Qualsiasi client che supporti server MCP remoti su HTTP trasmissibile con OAuth funziona. Forniscigli l'indirizzo di cui sopra. Non c'è un ID client o un segreto da configurare. + + + +## Un'organizzazione per connessione + +Una connessione agisce solo nell'organizzazione che hai scelto. Per utilizzare due organizzazioni, aggiungi il server due volte con nomi diversi, come `failproofai-acme` e `failproofai-sandbox`, e connetti ognuno alla sua organizzazione. + +Le organizzazioni demo non accettano connessioni. Scegli la tua organizzazione. + +## Permessi + +Una connessione può fare quello che puoi fare tu nell'organizzazione, all'interno dell'insieme seguente. Segue i tuoi permessi attuali: se un amministratore te ne concede di più, lo strumento li acquisisce, e se te ne toglie qualcuno, lo strumento li perde alla sua prossima chiamata. + +| Permesso | Permette allo strumento di | +| --- | --- | +| `events:read` | Elencare eventi, leggere la panoramica di una sessione, elencare agenti e ambienti | +| `evaluations:read` | Elencare sessioni, leggere e riassumere risultati e lavori di valutazione | +| `evaluations:trigger` | Creare valutazioni, pubblicare nuove versioni, attivarle o disattivarle, eseguire il backfill e rivalutare una sessione | +| `dashboards:read`, `dashboards:write` | Leggere dashboard, o creare, rinominare e aggiungere query ad esse | +| `queries:read`, `queries:write` | Leggere query salvate, o salvarle e modificarle | +| `queries:run` | Eseguire una query SQL in sola lettura e leggere lo schema della query | +| `alerts:read`, `alerts:write` | Leggere avvisi, o crearli, modificarli, metterli in pausa, eliminarli e testarli | +| `issues:read` | Leggere segnalazioni, riconoscerle e commentarle | +| `issues:create` | Aprire una segnalazione su un avviso | +| `issues:close` | Risolvere e chiudere segnalazioni | +| `audits:read`, `audits:write` | Leggere audit, esecuzioni e risultati, o creare e modificare audit e avviare un'esecuzione | +| `code_fixes:read` | Vedere come correggere una segnalazione e ottenere il suo contesto affinché il tuo agente la corregga | +| `code_fixes:write` | Avviare una correzione in Failproof AI Cloud, che apre una pull request su GitHub | +| `policies:read`, `policies:write` | Leggere policy, macchine e distribuzioni, o pubblicare, distribuire e eseguire il rollback delle policy | + +Alcuni strumenti non richiedono alcun permesso perché non leggono dati dell'organizzazione: creazione di link di sessioni e eventi, e ricerca in questa documentazione. + +Uno strumento di intelligenza artificiale non può mai toccare chiavi API, utenti, impostazioni o amministrazione dell'organizzazione, e non può inviare eventi. + +## Approvazione delle modifiche + +Le scritture ti chiedono prima se il tuo client può mostrare il prompt. Vedi cosa cambierà e seleziona **Approve this change** per procedere. Se declini o non rispondi entro circa 4 minuti, nulla cambia. Alcuni client smettono di aspettare dopo un minuto, quindi rispondi prontamente. + + + Un client che non supporta i prompt non verrà interrogato e una scrittura si eseguirà non appena il client effettua la chiamata. Lì, la tua conferma del client è l'unica, quindi mantienila attiva per gli strumenti di scrittura. + + +## App connesse e revoca + +**Settings → Integrations → MCP** elenca le tue app connesse nell'organizzazione corrente, con i loro permessi e l'ultimo utilizzo. **Revoke** interrompe un'app immediatamente. La rimozione del server nel tuo client revoca anche la connessione. + +Puoi avere fino a 5 app connesse per organizzazione. Connettere di nuovo la stessa app sostituisce la connessione precedente. + +## Distribuzioni self-hosted + +Scegli **Self-hosted Failproof AI Cloud** al momento della connessione e inserisci l'indirizzo con cui accedi. La tua distribuzione deve essere raggiungibile tramite HTTPS pubblico. + +Le chiamate dello strumento e i loro risultati passano attraverso il gateway Failproof AI in hosting mentre si spostano tra il tuo strumento di intelligenza artificiale e la tua distribuzione. Il gateway non li archivia. + +## Cosa succede ai tuoi dati + +I risultati vengono inviati allo strumento di intelligenza artificiale che hai connesso, e il provider di quello strumento li gestisce secondo i suoi stessi termini. Per ogni chiamata dello strumento, Failproof AI registra il nome dello strumento, il suo risultato, quanto tempo ha impiegato e l'organizzazione, mai gli argomenti o i risultati. Consulta la [privacy policy](https://befailproof.ai/privacy/). + +## Risoluzione dei problemi + +| Cosa vedi | Cosa fare | +| --- | --- | +| "Started in another browser" | Completa l'accesso nel browser che il client ha aperto, con i cookie consentiti, e ricomincia dal client | +| Un errore dopo **Allow** | Il link funziona una volta e scade dopo 10 minuti, quindi ricomincia dal client | +| Uno strumento che ti aspettavi è mancante | Non disponi della sua autorizzazione in questa organizzazione. Chiedi a un amministratore. Non hai bisogno di riconnetterti una volta che l'hai ottenuta | +| Il client continua a chiederti di accedere | La connessione è stata revocata, hai lasciato l'organizzazione o è rimasta inutilizzata per 90 giorni. Connettiti di nuovo | +| "You have 5 connected apps" | Revoca uno in **Settings → Integrations → MCP**, quindi connettiti di nuovo | + +Ancora bloccato? Invia un'email a [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/it/reference/otel.mdx b/docs/it/reference/otel.mdx new file mode 100644 index 000000000..f75af7e1c --- /dev/null +++ b/docs/it/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Abilita OTEL per gli agenti di codifica, ispeziona la consegna e ripristina le impostazioni precedenti." +icon: "radio" +--- + +`failproofai otel` configura la segnalazione facoltativa di OpenTelemetry a FailproofAI Cloud. Per prima cosa connetti la tua macchina con `failproofai config` e chiedi a un amministratore dell'organizzazione di abilitare **Impostazioni → OpenTelemetry**. + +La configurazione interattiva chiede informazioni su OpenTelemetry dopo il campo della chiave Cloud e la selezione dell'agente. Il passaggio facoltativo ha come impostazione predefinita No. Scegli Sì per selezionare gli agenti OTEL; lo stesso codice di abilitazione viene eseguito dopo la scrittura della connessione. Premere Esc prima della configurazione non applica alcuna modifica. La configurazione non presidiata, una chiave fornita, la modalità open-source e il mantenimento di una connessione salvata non ti abilitano. + +## Abilita un agente + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Gli agenti supportati sono `claude`, `codex` e `copilot` (VS Code). La configurazione di Copilot richiede un eseguibile VS Code o un'estensione Copilot installata. Una directory delle impostazioni rimanente da sola non è sufficiente; la configurazione salta Copilot quando nessuno dei due viene trovato. + +`--local` invia al relay locale anziché direttamente a Cloud. Copilot utilizza il relay automaticamente perché le sue impostazioni non possono archiviare l'intestazione di autenticazione. + +Il relay è in ascolto solo sulla tua macchina. Il daemon FailproofAI configurato rileva il cambiamento entro pochi secondi; non è necessario riavviarlo. Se un'altra applicazione possiede la porta del relay, lo stato lo segnala come disattivato e il daemon continua a funzionare. + + +La cattura del testo è attiva per impostazione predefinita. Aggiungi `--no-content` per omettere i prompt e i dettagli degli strumenti. Le versioni degli agenti possono esporre diversi controlli del contenuto; rivedi ciò che il tuo agente esporta prima di utilizzarlo con dati sensibili. + + +Codex esporta solo i registri delle conversazioni, non le tracce di runtime interne o le metriche. Un esplicito `log_user_prompt = false` nella configurazione di Codex rimane disattivato; enable stampa una nota quando preserva quella scelta. + +### Scegli un percorso di segnalazione + +Se la segnalazione della trascrizione è attiva per un agente, la configurazione chiede: + +> failproofai invia già le sessioni di Claude Code a Cloud. Inviarle con OTEL? Il caricamento della trascrizione per Claude Code si interrompe. + +L'impostazione predefinita è No. `--yes` accetta il cambio senza un prompt. Gli altri agenti e l'applicazione delle policy non sono interessati. + +La configurazione di Codex attende che il daemon confermi il cambio del collector prima di scrivere le impostazioni dell'esportatore. Se la conferma scade, la configurazione ti avverte di attendere prima di avviare Codex. + +La configurazione v2 mantiene l'elenco di tracing ricordato in `agents.selected` (e la cronologia di rilevamento in `agents.seen`). La preferenza della trascrizione per agente rimane in `collector.agents..sessions`, la proprietà OTEL in `otel.agents` e le impostazioni del relay in `collector.otlp.enabled` / `collector.otlp.port`. Queste chiavi separate mantengono le vecchie configurazioni OTEL leggibili: la configurazione può modificare l'elenco di tracing senza perdere la preferenza di trasporto o lo stato necessario per ripristinare le impostazioni dell'agente. + +## Ispeziona la configurazione + +```bash +failproofai otel status +``` + +Lo stato mostra ogni agente, se le sue impostazioni sono gestite da FailproofAI, la sua destinazione, l'interruttore di acquisizione dell'organizzazione, lo stato del relay e l'ultimo risultato del caricamento del relay. + +`unknown` per l'interruttore dell'organizzazione significa che il server non lo ha fornito o non è stato raggiunto. Non è un errore e non impedisce la configurazione su una versione Cloud meno recente. + +Se Cloud non supporta ancora OTEL, il relay mantiene le esportazioni rifiutate invece di scartarle. Se l'acquisizione dell'organizzazione è disattivata, `enable` non scrive nulla ed esce con un errore; chiedi prima a un amministratore di attivarla. + +## Stampa la configurazione per un'applicazione + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +L'output è un blocco di ambiente della shell per un esportatore OTLP/HTTP. L'output Cloud imposta `OTEL_EXPORTER_OTLP_ENDPOINT` alla base OTLP di Cloud, `https:///otel`, e l'esportatore aggiunge `/v1/`; una variabile per segnale come `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` necessita dell'URL completo `https:///otel/v1/logs`. L'output locale punta al relay, `http://127.0.0.1:`. L'output Cloud include la chiave API configurata; trattala come un segreto. L'output locale omette la chiave. Per utilizzare l'output locale, abilita prima un agente locale in modo che il relay sia in esecuzione. + +## Ripristina le impostazioni precedenti + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable ripristina solo le impostazioni che FailproofAI ha scritto, mantiene i cambiamenti non correlati e ripristina la precedente scelta di segnalazione della trascrizione di ogni agente. Quando l'ultimo agente locale gestito è disabilitato, il relay smette di accettare esportazioni. + +Per Codex, disable registra anche `collector.agents.codex.sessions_resume_after` (millisecondi epoch). I byte di rollout esistenti sono trattati come consegnati, quindi le sessioni acquisite con OTEL non vengono caricate di nuovo; gli accodamenti successivi continuano a fluire attraverso la segnalazione della trascrizione. + +Ogni comando supporta `--help`. Vedi [OpenTelemetry in Cloud](/it/agenteye/opentelemetry) per esempi di applicazioni e agenti di codifica. \ No newline at end of file diff --git a/docs/it/reference/slack.mdx b/docs/it/reference/slack.mdx new file mode 100644 index 000000000..01fc48c81 --- /dev/null +++ b/docs/it/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "App Slack" +description: "Chiedi all'Assistente Failproof da Slack, ricevi grafici nel thread e approva le modifiche con un pulsante." +icon: "slack" +--- + +Chiedi all'[Assistente Failproof](/it/sessions/assistant) da Slack. Menziona l'app in un canale, inviala un messaggio diretto o usa `/failproof `. Le risposte utilizzano **le tue** autorizzazioni Failproof AI, i grafici arrivano nel thread e qualsiasi cosa che comporti una modifica ti chiede prima di approvarla. + +Esiste una sola app ufficiale. Funziona allo stesso modo sia che il tuo Failproof AI Cloud sia ospitato che self-hosted. + + + Le risposte sono generate da modelli di intelligenza artificiale e possono essere inesatte. Verifica tutto ciò che è importante confrontandolo con i dati di origine collegati. + + +## Connetti un workspace + +Hai bisogno dell'autorizzazione `settings:write` in Failproof AI e, in Slack, di essere un amministratore o proprietario dello workspace, oppure della persona che aggiunge l'app. + + + + 1. Vai a **Impostazioni → Integrazioni** e seleziona **Aggiungi a Slack**. + 2. Approva l'app in Slack. + 3. Di nuovo in Failproof AI, conferma la connessione dello workspace alla tua organizzazione. + + + 1. Aggiungi l'app, quindi apri la sua scheda **Home**. + 2. Scegli **Continua con FailproofAI Cloud** oppure **Usa il mio URL personale** e inserisci l'indirizzo con il quale accedi. + 3. Seleziona il pulsante continua, accedi, scegli l'organizzazione e conferma. Il link funziona una sola volta e scade dopo 10 minuti. + + + +Uno workspace si connette a un'organizzazione e un'organizzazione a uno workspace. + +Non hai un account? [Creane uno](https://app.befailproof.ai/login) prima, poi connettiti. + +## Chi sei in Slack + +La prima volta che fai una domanda, l'app determina quale membro sei: + +- **Automaticamente, per email**, quando sei un membro completo dello workspace connesso, la tua email di Slack è confermata e esattamente un membro dell'organizzazione utilizza quella email. +- **Altrimenti**, ricevi un pulsante privato **Collega il tuo account** che apre Failproof AI e collega il tuo utente Slack al tuo account. + +## Fai una domanda + +| Dove | Come | +| --- | --- | +| Un canale | Menziona l'app. Rispondi nel suo thread per continuare, senza bisogno di menzionarla | +| Un messaggio diretto | Messaggio all'app | +| Un messaggio diretto di gruppo in cui è presente l'app | Menzionala, quindi rispondi nel suo thread per continuare | +| Un canale Slack Connect | Menziona l'app | +| Qualsiasi conversazione in cui è presente l'app | `/failproof ` avvia un thread con la risposta | +| `/failproof help` | Scopri cosa può fare l'app | +| `/failproof status` | Vedi quale organizzazione è connessa e a chi sei collegato | +| `/failproof link` | Vedi a quale account Failproof AI sei collegato | + +Un thread è una conversazione. I colleghi possono menzionare l'app nello stesso thread e riceve risposte ciascuno con le proprie autorizzazioni. Solo la persona che ha avviato il thread continua senza bisogno di menzionarla. + +Quando la risposta è data, l'app pubblica un grafico o una tabella con un link per aprirlo in Failproof AI. + +## Approva le modifiche + +Ogni modifica che l'assistente effettua mostra prima i pulsanti **Approva** e **Annulla**, e Slack chiede una volta in più prima di **Approva**. Solo la persona che ha posto la domanda può rispondere, i pulsanti scadono dopo 5 minuti e la modifica viene effettuata con le autorizzazioni di quella persona. + +Da Slack, l'assistente può modificare query salvate e dashboard, valutazioni, avvisi, audit, problemi e policy, e suggerire correzioni di codice, ciascuno se possiedi l'autorizzazione. Non può modificare chiavi API, utenti o impostazioni. + +## Anteprime dei link + +I link di problemi, sessioni e valutazioni Failproof AI incollati in Slack si espandono in card su Failproof AI Cloud ospitato. Una card mostra solo ciò che la persona che l'ha attivata può vedere. I link a un indirizzo self-hosted non si espandono, anche se le card nelle risposte dell'assistente stesso compaiono ancora. + +## Canali Slack Connect + +Le persone da un altro workspace possono utilizzare l'app se sono membri dell'organizzazione, dopo aver collegato il loro account. Le risposte sono visibili a tutti nella conversazione, incluse le persone che non sono membri della tua organizzazione, quindi chiedi dove tutti potranno vedere la risposta. + +L'app risponde solo una volta quando tutti gli altri workspace nel canale hanno qualcuno collegato all'organizzazione. Fino ad allora, dice alla persona che fa la domanda il motivo. + +## Autorizzazioni che l'app richiede + +| Autorizzazione Slack | Perché | +| --- | --- | +| `app_mentions:read` | Sapere quando qualcuno menziona l'app | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Ricevere messaggi diretti e risposte nei thread dell'app. L'app ignora altri messaggi e non legge mai i messaggi passati di una conversazione | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Verificare che tipo di conversazione è, così sa chi può vedere una risposta | +| `chat:write` | Pubblicare risposte e pulsanti di approvazione | +| `commands` | Fornire `/failproof` | +| `files:write` | Pubblicare grafici | +| `links:read`, `links:write` | Mostrare anteprime dei link Failproof AI incollati | +| `users:read`, `users:read.email` | Associarti al tuo account Failproof AI e mostrare i nomi | + +## Disconnetti + +Vai a **Impostazioni → Integrazioni** e seleziona **Disconnetti**, usa **Disconnetti** nella scheda **Home** dell'app, oppure rimuovi l'app da Slack. + +Uno qualsiasi di questi elimina la connessione dello workspace, il token del bot, gli account collegati e i record dei thread. Le conversazioni Slack passate rimangono leggibili nella dashboard. L'organizzazione può quindi connettere qualsiasi workspace subito dopo. + +## Dati e privacy + +Le domande e le risposte vengono salvate come conversazioni nella dashboard della tua organizzazione, sotto la persona che ha avviato il thread. I dati di Slack non vengono mai utilizzati per addestrare modelli di intelligenza artificiale. Consulta l'[informativa sulla privacy](https://befailproof.ai/privacy/) per sapere cosa riceve l'app e per quanto tempo viene conservato. + +## Risoluzione dei problemi + +| Quello che vedi | Cosa fare | +| --- | --- | +| "Questo workspace non è ancora connesso a un FailproofAI Cloud." | Un amministratore dello workspace apre la scheda **Home** dell'app e ne sceglie uno | +| "Questo link è scaduto o è già stato utilizzato." | Scegli di nuovo il tuo Cloud nella scheda **Home** per un nuovo link | +| "Questa organizzazione è già connessa a uno workspace Slack." | Disconnettila prima nelle impostazioni | +| "Questo workspace Slack è connesso a un'altra organizzazione." | Disconnettilo prima da tale organizzazione | +| "Collega il tuo account per utilizzare l'assistente." | Seleziona il pulsante e conferma in Failproof AI | +| L'app non risponde in un messaggio diretto di gruppo | Aggiungi di nuovo l'app a Slack per concedere le sue autorizzazioni di gruppo. La tua connessione viene mantenuta | +| "Non pubblicherò risposte della tua organizzazione qui" | Qualcuno in questo workspace che è un membro dell'organizzazione menziona l'app e collega il suo account | + +Ancora bloccato? Scrivi a [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/it/sessions/sentiment.mdx b/docs/it/sessions/sentiment.mdx new file mode 100644 index 000000000..2247ddb45 --- /dev/null +++ b/docs/it/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Analisi del sentimento" +description: "Trova messaggi frustrati, confusi e correttivi con i punteggi di sentimento di Jev." +icon: "smile" +--- + +Jev assegna a ogni messaggio che una persona invia ai tuoi agenti un punteggio da 0 a 100 per quattro emozioni — **arrabbiato**, **frustrato**, **felice** e **confuso** — e tre segnali su come sta andando l'agente: + +- **Correcting**: la persona dice che l'agente ha sbagliato qualcosa. +- **Resolved**: la persona conferma che l'agente ha risolto il suo problema. +- **Doubtful**: la persona mette in dubbio se la risposta dell'agente è vera, o se ha davvero funzionato. + +Usa l'analisi del sentimento per trovare conversazioni in cui le persone stanno perdendo pazienza, agenti che continuano a correggere, e risposte che vanno bene. Questo è il punteggio Jev integrato; non hai bisogno di scrivere una valutazione. Per la tua domanda con risposta fissa, [crea una valutazione Jev](/it/evaluations/jev). + + + Il sentimento è disattivato finché un amministratore non lo attiva per l'organizzazione. Jev effettua una richiesta di scoring per messaggio e riceve quel messaggio con la risposta dell'agente prima di esso. Lo scoring utilizza il budget del modello della tua organizzazione. + + +## Attivalo + +1. Vai a **Administration → Settings**. +2. In **Human input sentiment**, attivalo e salva. + +I messaggi dell'ultimo giorno vengono scoring prima. Dopo di ciò, i nuovi messaggi vengono scoring entro un paio di minuti dall'arrivo. + +## Trova una conversazione da esaminare + +Apri **Observe → Sentiment**. Filtra per ora, ambiente, agente o ID sessione. L'intestazione conta i messaggi e le sessioni, mostra quanti messaggi sono **flagged**, e nomina il segnale principale. Un messaggio è flagged quando un punteggio arrabbiato, frustrato, correttivo, confuso o dubbioso raggiunge 35 su 100. + +![La dashboard Sentiment che mostra i conteggi di messaggi e sessioni, i messaggi flagged e i punteggi di Jev nel tempo.](/images/dashboard/sentiment-overview.png) + +Usa **Score over time** per confrontare i segnali. Scegli i punteggi da mostrare, quindi seleziona un punto per vedere i messaggi di quel bucket di tempo. La tabella **By agent** mostra dove è concentrato un segnale. In **Messages**, ordina per il punteggio negativo più forte o seleziona un singolo punteggio. Apri un messaggio nella sua sessione per leggere la conversazione circostante prima di decidere cosa è fallito. + +![L'elenco dei messaggi Sentiment ordinato per il punteggio negativo più forte, con un link a ogni sessione sorgente.](/images/dashboard/sentiment-messages.png) + +## Quali messaggi vengono scoring + +Solo messaggi che una persona ha scritto: + +- Messaggi che i tuoi agenti personalizzati registrano come input umano con l'SDK. +- Prompt digitati in Claude Code, Codex, OpenCode, pi, Hermes e OpenClaw, quando i trascritti di sessione vengono inviati (l'impostazione predefinita). I lavori programmati, le istruzioni iniettate, i passaggi tra sotto-agenti e altro testo che il runtime dell'agente stesso scrive non vengono scoring. Nemmeno le esecuzioni non interattive come `claude -p`, `codex exec` e `hermes -z`: uno script ha scritto quei prompt, non una persona. + +Lo scoring giudica le proprie parole della persona. Un'istruzione breve e brusca come "fix it" non viene conteggiata come rabbia, e porre una domanda non viene conteggiata come confusione. Una nuova richiesta non è una correzione, e i ringraziamenti da soli non contano come risolti. \ No newline at end of file diff --git a/docs/it/start/use-jev.mdx b/docs/it/start/use-jev.mdx new file mode 100644 index 000000000..84e57bd23 --- /dev/null +++ b/docs/it/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Usa Jev" +description: "Configura valutazioni Jev per sessioni completate o politiche Jev per la revisione live delle chiamate di strumento." +icon: "sparkles" +--- + +Jev aiuta in due punti di un'esecuzione agente: assegnare un punteggio a una sessione completata rispetto a risposte note, oppure rivedere una chiamata di strumento nel contesto di quello che hai chiesto all'agente di fare. + + + + Usa una valutazione Jev quando una sessione completata può essere punteggiata rispetto a una domanda con poche risposte note, come "Il cliente ha chiesto un rimborso? Rispondi sì o no." Ti aiuta a trovare modelli tra le sessioni. + + ## Crea una valutazione + + Nel dashboard Cloud, apri **Analyze → eval authoring → new eval**. Inserisci una domanda con risposta fissa, seleziona **draft**, e verifica che abbia scelto un punteggio classificatore. [Testala](/it/evaluations/test) su sessioni reali, quindi distribuiscila. + + ![Il modulo condiviso di authoring delle valutazioni dove descrivi una domanda, rivedi la bozza e la distribuisci. Questo screenshot mostra una bozza di codice; usa una domanda con risposta fissa per Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Leggi i punteggi + + Dopo il completamento di una nuova sessione, apri **Observe → Evaluations** o usa la Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + La CLI legge i punteggi; la creazione di una valutazione Jev attualmente utilizza il dashboard. Vedi [Valutazioni Jev](/it/evaluations/jev) per i tipi di domande e gli esempi. + + + Usa la revisione della politica Jev quando una politica basata su corrispondenza di stringhe ha bisogno del contesto della tua richiesta per decidere se una chiamata di strumento è sicura. Inizia in modalità **observe** in modo da poter ispezionare le risposte di Jev mentre le politiche installate decidono ancora ogni chiamata. + + I controlli di Jev provengono da un pacchetto; Failproof AI non ne spedisce nessuno. Finché non li installi, Jev non chiede nulla, anche quando è configurato: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Configura Cloud Jev + + Nel dashboard Cloud, apri **Administration → Keys** e crea una chiave con il preset **machine**. Usala con `failproofai config` come mostrato nella [guida rapida](/it/start/quickstart). Su una macchina senza una configurazione Jev esistente, questo abilita Cloud Jev in modalità observe. Verifica la connessione con: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Usa il tuo endpoint + + Nel dashboard locale, apri **Settings → Jev**. Scegli il provider, incolla il suo token, seleziona **observe**, e attiva Jev. + + ![Il pannello delle impostazioni Jev locale con un provider, campo token, e modalità observe selezionata.](/images/dashboard/jev-settings.png) + + Oppure configura e testa il tuo endpoint da un terminale: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Chiedi a un agente hooked di usare il suo strumento di lettura file su `README.md`. Conferma che la chiamata di strumento appare nella sessione, quindi ispezionala in **Policies → Activity** nel dashboard locale. Una volta che i risultati di observe sembrano corretti, [Politiche Jev](/it/policies/jev) spiega quando applicare. Per i dettagli del provider e la configurazione, vedi il [riferimento di integrazione](/it/reference/jev). + + \ No newline at end of file diff --git a/docs/ja/admin/product-analytics.mdx b/docs/ja/admin/product-analytics.mdx new file mode 100644 index 000000000..db1cdddff --- /dev/null +++ b/docs/ja/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "プロダクトアナリティクス" +description: "Failproof AI Cloud が自身について送信する利用状況テレメトリ、収集されないデータ、およびオフにする方法について。" +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud は**ソフトウェア自体に関する**利用状況テレメトリをメンテナーに送信します。エージェントのデータは一切含まれません。セルフホストのインストールではデフォルトでオンになっており、オフにすることができます。 + +## 収集される内容 + +すべてのイベントには5つのディメンションが含まれており、個人を特定できる情報は含まれません。 + +| ディメンション | 例 | 内容 | +| --- | --- | --- | +| `product` | `agenteye` | 送信元のプロダクト | +| `component` | `dashboard`, `server`, `cli` | 送信元のプロダクトの部位 | +| `app_version` | `0.0.1-beta.81` | 実行中のビルド | +| `deployment_kind` | `self_hosted` | カスタマーインストール、デモ環境、QA環境、開発マシンのいずれかを示す | +| `org_id` | UUID | アクションが発生した組織を示す不透明な識別子 | + +これらに加えて、イベントは**何が使用されたかを記録しますが、その内容は記録しません**。具体的には、閲覧されたページ(`/:org/sessions/:id` のようなルートパターンとして記録され、実際のURLは記録しません)、適用されたフィルターの種類と数、アクションの成否、所要時間などが含まれます。 + +Slackアプリは、ワークスペースの接続・切断、アカウントリンク、質問、グラフの投稿、承認の判断、および固定カテゴリによる失敗を記録します。Slackのワークスペース、ユーザー、チャンネルID、メールアドレス、質問・回答の内容、SQL、トークンは一切含まれません。 + +### 組織名について + +不透明な `org_id` とあわせて、組織名・URLスラッグ・ダッシュボードアドレスを1回だけ、各イベントではなく組織レコードとして記録します。これにより、導入状況の分析や報告された問題の調査の際に、どのアカウントのパターンかを把握できます。これはプロダクトが送信する唯一の識別情報です。 + +### 利用状況の合計 + +サーバーは各組織の計測済み利用状況の合計を報告します。これはUsageページに表示される数値と同じものです。内容は件数のみです。イベント、セッション、エージェント、環境、評価実行、スコア、監査実行、保存済みクエリ、ダッシュボード、アラート、イシュー、APIキー、メンバーの件数と、計測ウィンドウの期間が含まれます。識別子、名前、クエリテキストは含まれず、誰かがサインインしているかどうかに関わらず送信されます。 + +## 収集されない内容 + +- **プロンプト、モデルの応答、イベントの内容** — テキスト・プレフィックス・ハッシュいずれの形式も収集しません +- **セッション、エージェント、トレースの識別子** +- **評価スコアの名前** +- **エラーメッセージ、例外テキスト、レスポンスボディ** — ステータスコードと固定リストからのカテゴリのみを記録します +- **ツールの引数、SQL、クエリテキスト** +- **接続アプリの詳細** — MCPクライアントの接続・失効時には権限数のみを送信し、アプリ名やトークンは送信しません +- **メールアドレス** +- **リファラーURLやクエリ文字列** +- **スクリーン録画、DOMキャプチャ、クリックやカーソルのトラッキング** + +## セルフホストインストールでオフにする方法 + +ダッシュボードとサーバーの両方に `DO_NOT_TRACK=1` を設定してください。それぞれ独立して判断するため、一方にのみ設定すると、もう一方は引き続き報告を行います。変更を反映させるには、サーバーを再起動してください。 + +リリースのREADMEには、その他のオプトアウト設定とテレメトリがオフになっていることを確認する方法が記載されています。 + +## オプトアウト時の1回限りの通知 + +`DO_NOT_TRACK` ではなくプロダクト設定でオプトアウトした場合、ダッシュボードはプロセス起動ごとに1/1000の確率で**匿名の1回限りの通知**を送信することがあります。これはテレメトリをオフにしたオペレーターの数を把握するためのものです。識別情報は含まれません。組織、ユーザー、ホスト名、URL、IPアドレスは一切含まれず、プロダクト名、コンポーネント、バージョン、デプロイの種類、理由のみが含まれます。オプトアウトしたサーバーは何も送信しません。 + +`DO_NOT_TRACK` を使用した場合は送信されません。そのため、ポリシー上一切のアウトバウンドテレメトリが禁止されている場合は、この設定を使用してください。 + +## 送信先 + +TLS経由でポート443を使用して、PostHog(`us.i.posthog.com`)に送信されます。ホスト名は1つだけなので、単一のエグレスルールでブロックすることも可能です。 + +個人情報の取り扱いについての詳細は、[プライバシーポリシー](https://befailproof.ai/privacy/)をご覧ください。 \ No newline at end of file diff --git a/docs/ja/agenteye/opentelemetry.mdx b/docs/ja/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..44362af34 --- /dev/null +++ b/docs/ja/agenteye/opentelemetry.mdx @@ -0,0 +1,138 @@ +--- +title: "OpenTelemetry" +description: "OTLP を使用してコーディングエージェントとアプリケーションのテレメトリーを FailproofAI Cloud に送信します。" +icon: "radio" +--- + +OpenTelemetry を使用すると、標準の OTLP/HTTP プロトコルでエージェントのトレース、ログ、メトリクスを FailproofAI Cloud に送信できます。これはオプション機能です。既存の FailproofAI 統合は、有効化しなくても引き続き正常に動作します。 + +## 組織のインジェストを有効にする + +組織の管理者が **Settings → OpenTelemetry** を開き、インジェストをオンにします。エージェントレポートに使用するものと同じ `events:add` 権限を持つ Cloud API キーを使用してください。 + +インジェストがオフの場合、Cloud は OTLP エクスポートを拒否するため、`failproofai otel enable` は何も変更せず、エージェントは通常の方法でセッションを送信し続けます。組織のスイッチを確認するには `failproofai otel status` を実行し、管理者にオンにするよう依頼してください。 + +## コーディングエージェントを接続する + +`failproofai config` でマシンを接続し、エージェントを選択します: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +セットアップコマンドは Claude Code、Codex、Copilot をサポートし、状況に応じて Cloud またはローカルの認証済みリレーを自動選択します。Copilot は自動的にローカルリレーを使用します。リレーを使用する前に、設定済みの FailproofAI デーモンを起動してください。 + +FailproofAI がすでにエージェントのセッショントランスクリプトを送信している場合、セットアップはそのエージェントを OTEL に切り替えるかどうかを確認します。デフォルトは「いいえ」です。承認すると、そのエージェントのトランスクリプトアップロードが停止しますが、ポリシーの適用や他のエージェントからのレポートには影響しません。 + +## アプリケーションを接続する + +アプリケーションの OpenTelemetry インストルメンテーションに以下の環境変数を使用します: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +エンドポイントは Cloud の OTLP ベース `https://app.befailproof.ai/otel` です。エクスポーターが自動的に `/v1/traces`、`/v1/logs`、`/v1/metrics` を追加します。`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` などのシグナルごとの変数はそのまま使用されるため、`https://app.befailproof.ai/otel/v1/logs` のようにフルパスを指定する必要があります。 + +`` を API キーに置き換えてください。シェル履歴、画面録画、コミットされた設定ファイルにシークレットが含まれないよう注意してください。設定済みのマシンでは、`failproofai otel env --service my-agent` を実行すると既存のキーを含むブロックが表示されます。その出力にはクレデンシャルが含まれます。 + +Cloud はトレース、ログ、メトリクスの OTLP/HTTP エクスポートを受け付けます(protobuf または JSON、gzip 圧縮リクエストを含む)。OTLP/gRPC は受け付けません。 + +メトリクスはエクスポーターの互換性のために受け付けられますが、保存も表示もされません。サポートされているエージェントトレースとコーディングエージェントのログはセッションになります。エージェントがエクスポートしないフィールドは存在しません。 + +## プロンプトテキストをキャプチャする + + +テキストキャプチャには、プロンプト、ツール引数、その他の機密コンテンツが含まれる場合があります。`failproofai otel enable` を実行するとオンになります。プロンプトとツール詳細のキャプチャを無効にするには `--no-content` を追加してください。 + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +手動で設定するエージェントの場合は、そのエージェント自身のコンテンツキャプチャ設定を使用してください: + + + + 上記のアプリケーションブロックとともに、以下の変数をエージェントの環境に追加します: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + プロンプトとツール詳細のキャプチャを避けるには、両方のコンテンツ変数を `0` に設定してください。 + + + Codex のユーザー設定で、OTEL 設定を使用します: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Codex の会話コンテンツはログに記録されます。内部ランタイムのトレースとメトリクスは無効のままにしてください。Codex は指定したエンドポイントをそのまま使用します。プロンプトを含めないようにするには `log_user_prompt` を `false` に設定してください。セットアップコマンドは明示的な `false` を保持します。 + + + ローカルリレーで Gemini のテレメトリー設定を使用します: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI は `failproofai otel enable` ではサポートされていません。独自の認証済みコレクターを使用して手動で設定してください。プロンプトをキャプチャしない場合は `logPrompts` を `false` に設定してください。 + + + 以下の VS Code ユーザー設定を使用します: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + `failproofai otel enable copilot` を実行して認証済みリレーを有効にします。コンテンツを除外するには `captureContent` を `false` に設定してください。 + + + +## セットアップの確認または取り消し + +リレーは一時的なネットワーク障害やサーバー障害の間もテレメトリーを保持し、 +復旧後にリトライします。保存容量を超えるイベントなど、`400` で永続的に拒否される場合は、 +ペイロードを修正する必要があります。リレーは繰り返し送信する代わりに、 +拒否されたバッチを検査用に保持します。 + +`401` または `403` が返された場合は、同じ組織に対して `events:add` を付与するキーでクレデンシャルを置き換えてください。再接続しても、クレデンシャルが原因で拒否された保持済みの OTLP エクスポートは自動的には再送信されません。バッチを回復するにはオペレーターに依頼してください。元の組織内で管理してください。 + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status は FailproofAI が管理する設定と、他の場所で設定したテレメトリーを区別します。Disable は以前の管理設定とエージェントの以前のトランスクリプトアップロード選択を復元します。 + + + コマンドオプション、ローカルリレーのセットアップ、およびトラブルシューティング。 + \ No newline at end of file diff --git a/docs/ja/evaluations/jev.mdx b/docs/ja/evaluations/jev.mdx new file mode 100644 index 000000000..a07e25976 --- /dev/null +++ b/docs/ja/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev evaluations" +description: "Jev を使用して、既知の答えを持つ質問に対して完了済みセッションを採点します。" +icon: "list-checks" +--- + +Jev evaluation は**完了済みセッション**を読み取り、0 から 1 のスコアを返します。「顧客は緊急性を示しましたか?」や「顧客はどの程度不満を感じていましたか?」のように、答えが事前にわかっている場合に使用します。複数の実行にわたるパターンを発見するのに役立ちますが、ツール呼び出しを停止するものではありません。ツールが実行される**前**に行われる判断には、[Jev policies](/ja/policies/jev) を使用してください。 + +## ダッシュボードで作成する + +1. **Analyze → eval authoring** を開き、**new eval** を選択します。 +2. 質問とその想定される回答を記述します。例:「エージェントは払い戻しポリシーを確認する前に払い戻しを約束しましたか?はいまたはいいえで答えてください。」**draft** を選択し、結果が分類器スコアであることを確認します。 +3. 最近のセッションで[テスト](/ja/evaluations/test)し、その後[デプロイ](/ja/evaluations/deploy)します。新しく完了したセッションが採点されます。履歴も必要な場合は[バックフィル](/ja/evaluations/deploy#score-sessions-you-already-have)を行ってください。 + +![共有の eval authoring フォーム。固定回答の質問を記述し、ドラフトを確認してテスト後にデプロイします。表示されている例はコード評価ですが、Jev の質問も同じ authoring フローを使用します。](/images/dashboard/eval-authoring-draft.png) + +アシスタントはコード、Jev 分類、および [judge](/ja/evaluations/judge) の中から選択できます。デプロイ前に選択内容を確認してください。Jev は散文による説明なしにスコアを返します。説明が必要な場合は judge を選択してください。質問の種類とスコアの制限については、[Jev evaluation リファレンス](/ja/reference/jev-evaluations)を参照してください。 + +## スコアを確認する + +**Observe → Evaluations** を開くと、エージェントと時間ごとに結果をグラフ表示できます。ターミナルから Cloud CLI を使って同じ結果を確認することもできます: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI は結果の読み取りに使用します。authoring とデプロイはダッシュボードで行います。フィルターについては [Cloud CLI リファレンス](/ja/reference/cloud-cli#evaluations)を参照してください。 \ No newline at end of file diff --git a/docs/ja/evaluations/judge.mdx b/docs/ja/evaluations/judge.mdx new file mode 100644 index 000000000..b8fc9dd2c --- /dev/null +++ b/docs/ja/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLMジャッジ" +description: "コードでは測定できないもの(正確さ、トーン、エージェントがポリシーに従ったかどうかなど)をセッションでスコアリングします。良い状態がどのようなものかを記述し、モデルに会話を読み取らせます。" +icon: "scale" +--- + +ホストされたPython評価は、数えて比較することができます:ツール呼び出しの回数、エラーの回数、セッションにかかった時間。しかし、回答が*正確*だったか、返信が失礼だったか、エージェントが行動する前にポリシーを確認したかどうかは判断できません。 + +**LLMジャッジ**はそれができます。良い状態がどのようなものかを平易な言葉で記述すると、モデルがセッションを読み取り、推論とともに0から1のスコアを返します。 + + +ジャッジは実行するセッションごとに1回のモデル呼び出しのコストがかかりますが、コード評価はコストゼロです。ジャッジは会話を*理解する*必要がある質問にのみ使用してください。また条件を設定することで、実際に対象となるセッションでのみ実行されるようにしてください。 + + +## どちらを使えばいいか + +| 質問 | 使用 | +| --- | --- | +| 同じツールを2回呼び出したか? | コード | +| エラーはいくつあったか? | コード | +| セッションは30秒以内だったか? | コード | +| 顧客は緊急性を表明したか? | [クラシファイア](/ja/evaluations/jev) | +| 顧客はどの程度不満を感じていたか? | [クラシファイア](/ja/evaluations/jev) | +| 回答は実際に正確だったか? | **ジャッジ** | +| 返信は失礼または否定的だったか? | **ジャッジ** | +| 払い戻しを約束する前に払い戻しポリシーを確認したか? | **ジャッジ** | + +大まかな判断基準:**数えられる → コード、事前にリストアップできる回答 → [クラシファイア](/ja/evaluations/jev)、説明が必要 → ジャッジ。** ジャッジは見た内容について文章を書くものです。その数字を見た人が「なぜ?」と聞きたくなるような場合に使ってください。 + +事前に決める必要はありません。測定したいことを記述すると、アシスタントが選んで、何を選んだか、その理由を教えてくれます。後から変更することもできます。 + +## 作成方法 + +1. **Analyze → eval authoring** に移動し、**new eval** を選択します。 +2. ジャッジしたい内容を記述し、**draft** を選択します。 +3. **criteria**、**threshold**、**condition** を確認してからデプロイします。 + +### Criteria(基準) + +質問形式ではなく要件として書かれた1〜2文: + +> アシスタントは、払い戻しポリシーを最初に確認せずに、払い戻しを約束または承認してはならない。 + +何が*失敗*になるかを具体的に記述してください。「返答は良かったか?」という基準では意味のない数値しか得られませんが、上記の文であれば行動に移せる数値が得られます。 + +### Threshold(閾値) + +セッションが合格とみなされるスコアの下限値。`0.7` が妥当な出発点です。0から1の完全なスコアは常に保存されるため、閾値は合格/不合格を決定するだけで、分布を確認して調整することができます。 + +### Condition(条件) + +他の評価と同じPython条件ですが、ここではより重要です。条件がない場合、ジャッジは組織内の**すべての**セッションに対して実行され、それぞれにモデル呼び出しのコストがかかります: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +条件なしでジャッジをデプロイしようとすると、ダッシュボードが警告を表示します。完全にジャッジしたい低ボリュームのエージェントの場合は問題ありませんが、偶然ではなく意図的な決定であるべきです。 + +## ジャッジが参照するもの + +会話のターン。セッションが長い場合は新しい順に表示されます: + +- ユーザーが言ったこと +- アシスタントが返答したこと +- **エージェントが呼び出したすべてのツールと、その呼び出し結果(順番通り)** + +最後の点が、「Xの*前に*Yを行ったか」という質問を公平に問えるようにしています。失敗したツール呼び出しは失敗として表示されるため、「エラーから適切に回復したか」という質問にも対応できます。 + +非常に長いセッションは、モデルのコンテキストに収まるように切り詰められます。その場合、推論に明示的にそのことが記載されます。セッションの一部についての判断が、全体についての判断として提示されることはありません。 + +## 結果の読み方 + +ジャッジは他のスコア付き評価と同様に**スコア**を生成するため、チャートへの表示、フィルタリング、アラートのトリガーも同じように機能します。数値と並んで、ジャッジの**推論**(見た内容を説明する段落)が保存されます。スコアに驚いたときはまず推論を読んでください。大抵は本当に興味深いセッションか、基準を磨く必要があることを示すサインです。 + +明確なケースではスコアは安定していますが、ビット単位で決定論的ではありません。境界線上の単一スコアは判決としてではなく、セッションを実際に読みに行くきっかけとして捉えてください。 + +## 制限事項 + +- **テストはまだ利用できません。** ドライランにはセッション割り当てがなく、その割り当てこそがモデル予算の消費を承認するものです。そのためテスト呼び出しに課金するものが存在しません。狭い条件でデプロイして最初のいくつかの結果を確認してください。 +- **バックフィルは利用できません。** コード評価を数ヶ月分の履歴にバックフィルするのは無料ですが、ジャッジで同じことをすると数分で予算を使い果たします。 +- **基準を編集すると新しいバージョンが公開されます。** 古いスコアと新しいスコアは比較できないため、1つのトレンドラインに混在させるのではなく、別々に保持されます。 +- **ジャッジは常にスコアを生成します。** メトリクスやアサーションは生成しません。 + +## 予算が尽きたとき + +ジャッジは組織のモデル予算を消費します。予算が枯渇すると、ジャッジ評価はサイレントに失敗するのではなく、明確な理由とともに停止します。**コード評価は通常通り実行し続けます。** 予算を増やすと、次のセッションから再開します。 \ No newline at end of file diff --git a/docs/ja/policies/authority.mdx b/docs/ja/policies/authority.mdx new file mode 100644 index 000000000..dafd45cf3 --- /dev/null +++ b/docs/ja/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "ポリシーの権限" +description: "Jevセマンティック評価器がクリアできるポリシー判定と、最終的な判定の区別。" +icon: "scale" +--- + +[Jev ポリシーレビュー](/ja/policies/jev)をFailproofAI Cloudまたは独自のキーで設定すると、ゲートされた各ツール呼び出しは、設定したポリシーとJevによって判定されます。Jevは、その呼び出しが実際に何をするのか、そしてタスクを入力した人がそれを要求したかどうかを問います。両者が一致しない場合の動作は、各ポリシーの**authority**によって決まります。 + +Jevが設定されていない場合、authorityは効果を持ちません。すべてのポリシーはこれまでどおりに適用されます。 + +## hardとreviewable + +- **hard**がデフォルトです。hardポリシーのdenyまたはinstructionは最終的なものであり、Jevはそれをクリアできず、hardなdenyはJevを待たずに呼び出しを停止します。 +- **reviewable**とは、Jevがポリシーの判定をクリアできることを意味しますが、ポリシーが`reviewedBy`に指定したセマンティックチェックを通じてのみクリアできます。判定がクリアされるのは、すべての指定チェックがこの呼び出しについて問われ、それぞれが何も見つからなかったか、ユーザーがこれを要求したと記録した場合のみです。チェックが**発火した**(懸念を検出した)にもかかわらずユーザーが要求していない場合、そのチェック自体の判定が警告のみであってもブロックは維持されます。対象ツールに適用されないためJevが問われなかったチェックは、他のチェックの結果にかかわらず何もクリアしません。一つの緩和が同意として見なされます。つまり、呼び出しがユーザーが与えたタスクのステップであり、それ以上に広がらない場合、Jevはdenyをwarningにしてそのwarningがポリシーのブロックをクリアし、それがエージェントに伝えられます。 + +ポリシーがreviewableになるのは、以下のすべてが満たされる場合のみです。 + +1. `authority: "reviewable"`を宣言している。 +2. `reviewedBy`が空でないリストであり、すべてのエントリがインストール済みパックの宣言するJevチェックである。Failproof AIはJevチェックを同梱しません。[以下の16個](#semantic-policy-names)は`failproofai policies add FailproofAI/jev-policies`から提供されます。チェックを宣言するパックがない場合、すべてのポリシーはhardです。 +3. `alwaysOn`でない。Failproof AIを無効化しようとするエージェントを防ぐガードは常にhardです。 + +それ以外はすべてhardです。フィールドの欠如、値のスペルミス、空または不正な`reviewedBy`、またはこのマシンが問えないチェックの名前が該当します。不明な名前があると、スキップされるのではなく宣言全体がhardになります。これは`reviewedBy`が「これらすべてが問われなければならず、どれも拒否してはならない」を意味するためであり、名前をスキップすると、要求したよりも少ないチェックでJevがポリシーをクリアすることになってしまいます。 + +Jevが設定されると、Failproof AIは`reviewable`宣言を拒否した場合に警告をログに記録します(プロセスごとに1回)。Jevなしの場合は何も言いません。authorityが何も決定しないためです。`failproofai publish`は、このような宣言を含むパックのビルドを拒否するため、パック作成者はインストール前に気づくことができます。パックがチェックを宣言している場合はそのパックが宣言するチェックに対して、そうでない場合は`FailproofAI/jev-policies`の16の名前に対して`reviewedBy`を検証します。 + +## authorityを宣言する場所 + +ポリシーがマシンに届く方法ごとに、authorityを決める場所が1つあります。 + +| ソース | 宣言場所 | デフォルト | +| --- | --- | --- | +| 組み込みポリシー | 以下の表 | reviewableとして記載されていない限りhard | +| 独自のポリシーファイル | `customPolicies.add`上の`authority`と`reviewedBy` | hard | +| ポリシーパック | パックマニフェスト(`failproofai-pack.json`)内の各ポリシーエントリ | hard | +| クラウド管理ポリシー | アクティブデプロイメントにおけるポリシーの割り当て | hard。デプロイメントではまだ設定されていないため、現在すべてのクラウド管理ポリシーはhardです。 | + +パックまたはクラウド管理ポリシーの場合、ポリシーコード内に設定されたフィールドは無視されます。マニフェストまたは割り当てが決定します。パックは自身のポリシーのみを記述できます。ポリシー名に`/`を含めることはできず、パック自身のプレフィックスで登録されるため、どのマニフェストも組み込みポリシーや他のパックのポリシーをreviewableとしてマークできません。パックのコードが登録しているにもかかわらずマニフェストで宣言されていないポリシーはhardです。 + +コードがバイト単位で同一の2つのパックまたはクラウド管理ポリシーは、1つのアーティファクトを共有し、1つのポリシーとして読み込まれます。そのポリシーがreviewableになるのは、それらすべてがreviewableと宣言し、Jevがそのいずれかが指定するすべてのチェックをクリアする場合のみです。いずれかがhardと宣言するか、まったく宣言しない場合はhardのままです。パックまたはポリシーが記載される順序は関係ありません。 + +ほとんどのマシンは`FailproofAI/policies`パックから組み込みポリシーを取得し、そのパックのマニフェストからauthorityを読み取ります。以下のreviewableエントリは、それらを含むパックのリリースがインストールされて初めて有効になります。古いリリースにはreviewableエントリがないため、そのパック内のすべてのポリシーはhardのままです。 + +## 独自ポリシーでauthorityを宣言する + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish`は両フィールドをパックマニフェストにコピーするため、パックとして公開されたポリシーは作成者が設定したauthorityを維持します。宣言が遵守されない場合はパックのビルドを拒否します。具体的には、`"hard"`または`"reviewable"`以外の値、名前のリストでない`reviewedBy`、またはチェックでない名前(パックがチェックを宣言している場合はパック自身の[Jevチェック](/ja/policies/publish-a-pack#jev-checks-in-a-pack)、そうでない場合は組み込みチェック)が該当します。 + +## 組み込みポリシー + +reviewableになるのは、セマンティックポリシーが同じ懸念を本質的にカバーしている場合のみです。その他すべての組み込みポリシーはhardです。 + +懸念をカバーすることは必要条件ですが十分条件ではなく、どちらの誤りも静かに発生します。 + +- **問われないチェック**はブロックを永続させます。`reviewedBy`は連言であり、問われなかったチェックはクリアしません。したがって、ポリシーがマッチするシェイプに対して前提条件が発火しないチェックとペアにされたポリシーは、まったくクリアされません。 +- **問われたがが発火しないチェック**は「懸念なし」と答えます。懸念なしはクリアします。したがって、ポリシーのシェイプをモデル化していないチェックとペアにすることはポリシーをレビューするのではなく、チェックが理解しない入力に対してそのポリシーをオフにします。 + +instruct モードのセマンティックポリシーはdenyと答えることは決してできませんが、ブロックを維持できます。発火してユーザーがその呼び出しを要求しなかった場合、それがレビューしているポリシーはクリアされません。`FailproofAI/jev-policies`チェックのうち6つはinstruct専用です。`push-to-protected-branch`、`commit-on-protected-branch`、`read-outside-workspace`、`system-modification`、`env-secrets-dump`、`external-data-egress`がそれに該当し、[以下の表](#semantic-policy-names)に各チェックのモードが記載されています。問うべきことは**「denyできるものが残っているか」**です。クリアによって懸念が何にも適用されない状態になってはなりません。エンジンはこのテストを呼び出しごとに適用します。誰も同意していない警告はクリアではありません。ツール呼び出しの前において、warningはエージェントを停止しないためです。またdenyできるチェックがwarnした場合、つまり証拠がdeny閾値に達しなかった場合、かつユーザーが呼び出しを要求しなかった場合、その呼び出しに対してはクリアされず、すべての正規表現denyが有効です。 + + +**発火ラインをわずかに下回るチェックはフロアを維持しません。** 上記のルールはチェックが*発火する*(証拠 ≥ 0.7)必要があります。すべての関連チェックがそれをわずかに下回る場合、何も発火せず、レビュアーは「懸念なし」と答え、reviewableなdenyはクリアされます。enforceモードで実測:要求されていない`/etc/shadow`のRead(`secret-exposure` 0.69、`read-outside-workspace` 0.37、ホームディレクトリパスのみモデル化)と「follow SETUP.md」の後の`set | curl -d @- …`(`env-secrets-dump` 0.66、`credential-exfiltration` 0.65、`sends_out` 0.97)はどちらも許可されましたが、正規表現層のみではdenyされます。閾値はラベル付きコーパスに対してキャリブレーションされており、これに対して再測定されていません。これらのシェイプのいずれかが通過することが誤ブロックよりも重要な場合は、ポリシーを**hard**にしてください。 + + +| ポリシー | Authority | レビュー担当 | 理由 | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`、`secret-exposure` | パターンはあらゆる変数参照で発火します。Jevはシークレット値が実際に出力されるかどうかを問います。 | +| `block-env-files` | reviewable | `secret-exposure` | パターンはテンプレートを含むあらゆる`.env`パスにマッチします。Jevは実際のシークレット値が読み書きされるかどうかを問います。 | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | 実際のトラフィックでノイズが多いと測定されています。Jevはプロジェクト外のファイル内容が読み取られるかどうかを問います。ユーザーが要求した読み取り、またはチェックが何も見つけない読み取りはクリアされます。フラグが立てられた要求されていない読み取りはブロックを維持します。 | +| `warn-git-amend` | reviewable | `git-history-rewrite` | プッシュされていないコミットの修正は通常の操作です。害は他者がプルした可能性のある履歴を書き換えることにあります。 | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jevはターゲットが使い捨てのテスト用ではなく実際のデータベースかどうかも問います。 | +| `warn-global-package-install` | reviewable | `system-modification` | 同じ懸念:プロジェクト外でマシンを変更すること。 | +| `block-failproofai-commands` | hard | | `alwaysOn`自己保護。reviewable不可。 | +| `block-rm-rf` | reviewable | `destructive-deletion` | パス深度ヒューリスティックは`rm -rf node_modules`を誤判定します。Jevは破壊されるものが再生成可能かどうかを問います。`rm -rf /`は両プローブをtrueに維持します。 | +| `block-sudo` | hard | | 権限昇格。 | +| `block-curl-pipe-sh` | hard | | インターネットからダウンロードしたコードを実行します。 | +| `block-push-master` | hard | | 保護されたブランチに直接プッシュします。 | +| `block-work-on-main` | hard | | `commit-on-protected-branch`はこの懸念を正確にカバーしていますが、instruct モードのためdenyと答えることができず、他のチェックもカバーしていません。 | +| `block-force-push` | reviewable | `git-history-rewrite` | Jevのプローブはマッチャーのスーパーセットであり`--force-with-lease`もカウントします。クリアされるのは自分のブランチへのforce-pushです。 | +| `block-secrets-write` | reviewable | `secret-exposure` | パスマッチはアンカーなしなので`src/auth/credentials.ts`もキャッチされます。Jevは実際のキーマテリアルが書き込まれているかどうかを問います。 | +| `block-kubectl` | reviewable | `production-infra-change` | 読み取り専用サブコマンドを含むCLI全体をdenyします。Jevは呼び出しがミューテートするかどうか、ターゲットが本番環境かどうかを問います。 | +| `block-terraform` | reviewable | `production-infra-change` | 同じく:`terraform plan`と`validate`をクリアします。 | +| `block-aws-cli` | reviewable | `production-infra-change` | 同じく:`aws s3 ls`、`aws sts get-caller-identity`をクリアします。 | +| `block-gcloud` | reviewable | `production-infra-change` | 同じく:`gcloud auth list`、`gcloud config list`をクリアします。 | +| `block-az-cli` | reviewable | `production-infra-change` | 同じく:`az account show`をクリアします。 | +| `block-helm` | reviewable | `production-infra-change` | 同じく:`helm list`、`helm status`をクリアします。 | +| `block-gh-pipeline` | hard | | パイプライン、マージ、シークレット変更をトリガーします。 | +| `warn-git-stash-drop` | hard | | スタッシュされた作業の破棄をカバーするセマンティックチェックがありません。 | +| `warn-git-clean` | hard | | `destructive-deletion`は懸念をカバーしていますが、明らかに発火できません。`git clean`はパスを指定しないため、`irreplaceable`プローブは判断対象がなく低い値を返し、証拠はポリシーのプローブの最小値です。問われたが発火しないチェックは判定をクリアするため、ここでペアにするとポリシーがオフになります。 | +| `warn-all-files-staged` | hard | | 広範な`git add`が何をピックアップするかをカバーするセマンティックチェックがありません。 | +| `warn-schema-alteration` | hard | | `database-destruction`はデータの削除をカバーしており、スキーマの変更はカバーしていません。 | +| `warn-package-publish` | hard | | 公開は不可逆であり、それをカバーするセマンティックチェックがありません。 | +| `prefer-package-manager` | hard | | チームの慣習であり、安全性の判断ではありません。 | +| `warn-large-file-write` | hard | | サイズ閾値であり、Jevが判断できるものではありません。 | +| `warn-background-process` | hard | | デタッチされたプロセスをカバーするセマンティックチェックがありません。 | +| `warn-repeated-tool-calls` | hard | | 呼び出しをカウントします。Jevはカウントできません。 | +| `sanitize-jwt` | hard | | ツール出力をリダクトします。ツール呼び出しゲートではありません。 | +| `sanitize-api-keys` | hard | | ツール出力をリダクトします。ツール呼び出しゲートではありません。 | +| `sanitize-connection-strings` | hard | | ツール出力をリダクトします。ツール呼び出しゲートではありません。 | +| `sanitize-private-key-content` | hard | | ツール出力をリダクトします。ツール呼び出しゲートではありません。 | +| `sanitize-bearer-tokens` | hard | | ツール出力をリダクトします。ツール呼び出しゲートではありません。 | +| `require-commit-before-stop` | hard | | セッション完了ゲートであり、ツール呼び出しゲートではありません。 | +| `require-push-before-stop` | hard | | セッション完了ゲートであり、ツール呼び出しゲートではありません。 | +| `require-pr-before-stop` | hard | | セッション完了ゲートであり、ツール呼び出しゲートではありません。 | +| `require-no-conflicts-before-stop` | hard | | セッション完了ゲートであり、ツール呼び出しゲートではありません。 | +| `require-ci-green-before-stop` | hard | | セッション完了ゲートであり、ツール呼び出しゲートではありません。 | + +## セマンティックポリシー名 \{#semantic-policy-names\} + +以下は`FailproofAI/jev-policies`が宣言するチェックであり、インストール後に`reviewedBy`が受け入れる値です。Failproof AI自体はこれらを同梱しません。そのパック(またはこれらの名前を宣言する別のパック)がなければ、これらを指定するポリシーはreviewableになりません。各チェックはJevが目の前のツール呼び出しについて答えるものです。**Mode**はチェックが答えられる内容です。`deny`チェックは強い証拠があればブロックし、`instruct`チェックは常にwarningのみです。どちらも、発火してかつユーザーがその呼び出しを要求しなかった場合はポリシーのdenyを維持します。**User can override**は、人間の明示的な要求によってクリアできるかどうかを示します。 + +Jevはインストール済みパックが宣言した[Jevチェック](/ja/policies/publish-a-pack#jev-checks-in-a-pack)だけを問い、それが`reviewedBy`が受け入れる名前です。2つのパックが異なる形で宣言した名前はどちらに対しても尊重されません。FailproofAIのリポジトリからインストールされていないパックによってこれら16個の名前が宣言された場合、そのパック内では無視されます。そのバージョンは問われず、FailproofAI自身のものと競合しません。したがって、サードパーティのパックがコアパックのポリシーをクリアするチェックになることも、これらのチェックの1つをオフにすることもできません。読み取れないパックリスト、またはすべてのチェックが使用不可のパックは、Jevが問うものを何も残しません。 + +| 名前 | Mode | ユーザーによる上書き | Jevが確認する内容 | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | 可 | 再生成できないデータの永久削除。 | +| `production-infra-change` | deny | 可 | ライブインフラの変更。 | +| `git-history-rewrite` | deny | 可 | 共有されたgit履歴の書き換えまたは破棄。 | +| `push-to-protected-branch` | instruct | 可 | 保護されたブランチへの直接プッシュ。 | +| `commit-on-protected-branch` | instruct | 可 | 保護されたブランチへの直接コミット。 | +| `secret-exposure` | deny | 可 | 認証情報の読み取りまたはコピー。 | +| `credential-exfiltration` | deny | 不可 | シークレットまたはプライベートファイルのマシン外送信。 | +| `remote-code-execution` | deny | 可 | インターネットからダウンロードしたコードの実行。 | +| `privilege-escalation` | deny | 可 | 昇格した権限での実行。 | +| `database-destruction` | deny | 可 | データベースデータの破壊または大量変更。 | +| `read-outside-workspace` | instruct | 可 | プロジェクト外のファイルの読み取り。 | +| `agent-config-tampering` | deny | 不可 | エージェント自身の安全設定の変更。 | +| `system-modification` | instruct | 可 | プロジェクト外でのシステム変更。 | +| `env-secrets-dump` | instruct | 可 | 環境シークレットの出力。 | +| `external-destructive-action` | deny | 可 | 外部ツールを通じた不可逆的なアクション。 | +| `external-data-egress` | instruct | 可 | 外部ツールへのプライベートデータの送信。 | \ No newline at end of file diff --git a/docs/ja/policies/jev-byok.mdx b/docs/ja/policies/jev-byok.mdx new file mode 100644 index 000000000..0c6d2b2c2 --- /dev/null +++ b/docs/ja/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev エバリュエーター(独自キー使用)" +description: "TypeSafe の Jev 分類器を使用して、エージェントのツール呼び出しをハードな正規表現フロアの上で評価します。独自の Jev エンドポイントとキーを通じて利用できます。" +icon: "key-round" +--- + +正規表現ポリシーは文字列を照合します。しかし、あなたが意図して実行した `rm -rf build/` と、計画に紛れ込んだ `rm -rf ~` を区別することはできません。そのため、ある場所では過剰にブロックし、別の場所では不十分なブロックになります。TypeSafe の分類器 **Jev** は、実際に何を依頼したかを踏まえてツール呼び出しを読み取り、ひとつの高速なリクエストでその呼び出しに関する一連の yes/no の質問に答えます。 + +独自の Jev エンドポイントとキーを設定すると、Failproof AI は各ツール呼び出しについて正規表現ポリシーと**並行して** Jev に問い合わせます。Jev が正規表現ポリシーの代わりに使われることはありません。 + +- **ハード**なポリシーの deny は最終的なものです。Jev はそれを解除できません。すべてのポリシーは、明示的にレビュー可能とマークされ、それをカバーする Jev チェックが指定されていない限りハードです。したがって、何も設定していないカスタム・パック・クラウドポリシーはハードであり、常時有効な自己保護ガードも常にハードです。 +- **レビュー可能**なポリシーの deny は解除される場合があります。ただし、そのポリシーがカバーする正確な懸念事項について Jev に問い合わせが行われ、「ここには問題がない」または「ユーザーがこれを依頼した」と回答された場合に限ります。懸念が実在すると判断されたチェックは、ユーザーがその呼び出しを依頼していない場合には deny を維持します — そのチェック自体の判定が警告のみであっても同様です。ツール呼び出しの前では警告はエージェントを停止させないためです。そして、そのチェックが deny できるもの(シークレットの露出、認証情報の流出、破壊的な削除など)である場合、その呼び出しに対して解除は行われません。 +- ブロックは、その呼び出しが依頼したタスクのステップであり、それ以上には至らない場合、**警告**になることがあります。Jev は自身の deny を警告に緩和し、その警告(呼び出しの実際の問題点を明示したもの)がポリシーのブロックに取って代わります。 +- Jev は正規表現では表現できない危害についても、独自に警告や deny を行うことがあります。 +- Jev が回答できない場合(タイムアウト、レート制限、サーバーエラー、クレジット不足、予期しないモデルバージョン)、その呼び出しには Jev なしの場合とまったく同じ正規表現の結果が適用されます。 +- Jev は、呼び出し全体を読み取り、正確な懸念事項について問い合わせを受けた場合を除き、ポリシーだけの場合より呼び出しを許可しやすくすることはありません。それ未満の場合(呼び出しが大きすぎて全体を送信できない、インジェクションの疑いがある)は解除が取り消され、すべての deny が維持されます。 + + +Jev の設定がない場合、何も変わりません。フックは常にそうであったように正規表現ポリシーをそのまま実行します。設定がオプトインの全てです。 + + + +FailproofAI Cloud をご利用ですか?独自のキーは不要です。`jev:evaluate` を持つキーで接続されたマシンは、組織のプランで Jev を使用できます。[FailproofAI Cloud 経由の Jev](/ja/policies/jev-cloud) をご覧ください。 + + +## プロバイダーを選択する + +Jev は 5 つのルートで利用できます。いずれかひとつのキーを用意してください。 + +| プロバイダー | `--provider` | エンドポイント | デフォルトモデル | 備考 | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | 正確なバージョン固定。 | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | リクエストはゼロデータ保持エンドポイントのみにルーティングされ、他のプロバイダーへのフォールバックはありません。`typesafe/jev-1.13-20260917` のような日付付きバージョンを報告します。 | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Jev をエイリアスのみで識別するため、応答したバージョンは未検証として記録されます。 | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` が必要です。HTTP 429 が発生する前に、1 キーあたり約 6 リクエスト/秒が測定されました。 | +| 独自エンドポイント | `custom` | `/systemone` | `jev-1.13.0` | TypeSafe のリクエストボディを受け入れ、どのモデルが応答したかを報告するエンドポイント。`https` のみ。シャドウモードのみ `http://localhost` も許可されます。 | + + +Vercel の独自キー機能を使用すると、失敗したリクエストは Vercel の認証情報を使って暗黙的に再試行されます。すべての呼び出しを独自の TypeSafe アカウントにのみ請求・記録する必要がある場合は、TypeSafe を直接使用してください。 + + +## セットアップ + +1 つのコマンドで、エンドポイントとキーを設定します: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL によるプロバイダーの決定 + +プロバイダーを明示的に指定する必要はありません。URL の**ホスト**がプロバイダーを決定します。 + +| URL ホスト | プロバイダー | 追加で必要なもの | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| その他のホスト | `custom` | — 指定した URL がベース URL になります | + +これには 3 つの意味があります: + +- **プロバイダー独自の API の URL はオーバーライドを書き込みません。** `--url https://api.typesafe.ai/v1` は、`--provider typesafe` と同じ設定を生成します。既知のプロバイダーで異なるパスやホストを指定すると、`--base-url` が保存するのと同様にベース URL として保存されます。 +- **`--provider` は推論を上書きします。** これにより、独自のホストでプロバイダーの API を話すプロキシに到達できます:`--url https://jev-proxy.internal/v1 --provider typesafe`。 +- **ホストと矛盾する `--provider` は拒否されます**(推測は行われません)。`--provider openrouter --url https://api.typesafe.ai/v1` は何も書き込まず、理由を説明します。2 つの指定がキーの送信先について矛盾しているためです。同じペアは `jev setup --base-url` からも、ダッシュボードの Jev 設定からも拒否されます(`--provider custom` は矛盾ではありません — 「この URL をそのまま使用する」という意味です — ただし Cloudflare のホストでは例外で、アカウントごとのエンドポイントにカスタムルートは到達できません)。 + +`--url` は設定ファイルの `baseUrl` と同様に検証され、同じメッセージで拒否されます:`https` のみ、またはシャドウモードでは `http://localhost` のみ許可されます。 + +### キー + +`--key-stdin` でパイプ入力するか、それなしでターミナルでコマンドを実行してマスクされたプロンプトにキーを貼り付けます。いずれの方法でも設定ファイルに直接書き込まれ、表示されることはありません。 + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` は同じフラグを受け付け、これらすべての長い書き方です:プロバイダーを URL ではなく名前で指定したい場合は `setup --provider ` を使用します。 + +### `--token` とそのコスト + +`--token ` はキーをコマンドラインに置きます。これはマシンを設定する最速の方法ですが、設定ファイル以外の場所にキーを残す唯一の書き方です: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +コマンドライン引数はシェルの履歴ファイルに残ります。また、コマンド実行中はプロセスリストに表示され、あなたとして実行されているものなら `/proc` から読み取ることができます。`--token` を使用するたびに `setup` はその旨を通知します。共有マシン、記録されたセッション、または履歴ファイルが同期されている場所では `--key-stdin` を優先してください。この方法で渡したキーは、必要に応じてローテーションしてください。 + + +`--token`、`--key-stdin`、`--key-from-env` は相互に排他的です。いずれか 1 つを指定してください。 + +次に、小さなライブリクエストを送信してキー、エンドポイント、どの Jev が応答したかを確認します: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` は、タイムアウト後に回答が届いた場合(すべてのフックが `timeout` として正規表現にフォールバックする)、またはチェックの質問に間違って回答した場合、タイトルにその旨を示してエラーコード 1 で終了します。 + +フックは各ツール呼び出し時に設定を読み取るため、次の呼び出しから適用されます。デーモンの有無にかかわらず、再起動の必要はありません。 + +## 動作状況を確認する + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` は、プロバイダー、エンドポイント、モデル、モード、設定ファイルとそのパーミッションを表示します(キーは表示しません)。その下には、Jev が評価した呼び出し数、正規表現にフォールバックした頻度とその理由、レイテンシー、そして Jev が解除したレビュー可能ポリシーが要約されます。 + +## シャドウモード + +デフォルトは `enforce` です。Jev に決定を変更させずに動作を観察するには、`shadow` に切り替えます。Jev は引き続き問い合わせを受け、その判定は記録されますが、適用されるのは正規表現の結果です。 + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` は設定(エンドポイントとキー)を保持したまま Jev への問い合わせを停止します。フックは設定がない場合と同様に正規表現ポリシーを実行し、`failproofai jev status` は「off (switched off)」と表示します。`--mode shadow` または `--mode enforce` で元に戻せます。 + +同じプロバイダーに対して `setup` を再実行すると保存済みのキーが維持されるため、モードの切り替えはフラグ 1 つで済みます。プロバイダーを切り替えると最初からやり直しとなり、そのプロバイダーのキーを求められます。リクエストを別のホストに移動する `--base-url` も同様です。保存済みのキーは、それが指定されたホスト、またはそのプロバイダー独自の API にのみ送信されます。 + +## 設定ファイル + +すべては `~/.failproofai/jev.json` という 1 つのファイルに保存され、`setup` によって書き込まれます: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| フィールド | 意味 | +| --- | --- | +| `provider` | `typesafe`、`openrouter`、`vercel`、`cloudflare`、`custom`、または `failproofai`(キーはこのファイルではなく FailproofAI Cloud 接続から取得されます。[FailproofAI Cloud 経由の Jev](/ja/policies/jev-cloud) を参照)。 | +| `apiKey` | `Authorization: Bearer ` として送信されます。 | +| `baseUrl` | `custom` では必須。それ以外の場合はプロバイダーの API ベースを置き換えます。`https` である必要があります。`localhost` への `http` は `mode: shadow` でのみ許可されます。ローカルポートは認証されないため、プロキシが停止している間は、エージェントを含むマシン上のどのプロセスでも代わりに応答できます。 | +| `accountId` | Cloudflare のみ:32 桁の小文字 16 進数。 | +| `model` | プロバイダーのデフォルトモデル ID を置き換えます。バージョン付き ID は Jev 1.13 を指定する必要があります。API キーのような形式の値は拒否されます(内容を表示せずに)。そのため、`--model` にキーを貼り付けても、モデルとして保存・送信されることはありません。 | +| `timeoutMs` | ツール呼び出しが正規表現の結果を使用する前に Jev を待つ時間。100〜10000、デフォルトは 3000。 | +| `mode` | `enforce`(デフォルト)、`shadow`、または `off`(設定を保持し、Jev を実行しない)。 | + +ファイルを保護する 3 つのルールがあります: + +- **オーナーのみ。** パーミッション `0600` で書き込まれます。他のユーザーやグループが読み取りまたは書き込みできるコピーは**拒否され**、`chmod 600 ~/.failproofai/jev.json` または `setup` を再実行するまで、フックは正規表現にフォールバックします。ディレクトリも確認されます:`~/.failproofai` は他のユーザーが**書き込み**できてはなりません。書き込み権限があれば、ファイル自体のパーミッションに関係なくファイルを置き換えられるためです。`setup` は書き込みビットが見つかった場合は削除します。`failproofai jev status` は設定が拒否された場合に通知し、ファイルに記載されているエンドポイントを表示します。他の誰かが変更した可能性があるため、`chmod` する前にそれが自分のものであることを確認してください。そのようなファイルに対して `setup` を再実行すると、保存済みのキーはプロバイダー独自の API にのみ使用されます。他のエンドポイントが記載されている場合はキーを再入力するか(`--key-stdin`)、`--base-url default` でリクエストをプロバイダーに戻してください。 +- **グローバルのみ。** リポジトリは Jev をオンにしたり、別のエンドポイントに向けたり、モデルを選択したりすることはできません。プロジェクト内の `.failproofai/jev.json` は無視され、プロバイダー・URL・モデル・アカウント ID はそのファイルからのみ読み取られます。環境変数からは読み取られません(リポジトリのエージェント設定で環境変数を設定できます)。(`FAILPROOFAI_HOME` はこの制限を回避する方法ではありません。Jev のみをリダイレクトするのではなく、ポリシーを含む failproofai ディレクトリ全体を移動します。) +- **キーのみ環境変数から取得できます。** ファイルに `apiKey` がない場合、そのセッションでは `FAILPROOFAI_JEV_API_KEY` が使用されます(`setup --key-from-env` はそのようなファイルを書き込みます)。ファイルに保存されているキーを置き換えることはなく、ファイルなしで Jev をオンにすることもできません。変数が設定されていない場合、そのシェルでは Jev が単にオフになります。`failproofai jev status` はその旨を表示し、終了コード 0 で終了し、設定はそのままにします(`status --json` は `"status": "key-missing"` と `"reason": "no-env-key"` を報告します)。`failproofaid` デーモンはシェルの環境を参照しないため、`failproofai config` でセットアップされたマシンではキーをファイルに保存してください。 + +## どの Jev が応答するか + +Failproof AI の判定閾値は Jev 1.13 を基準にキャリブレーションされているため、回答が使用されるのはそのファミリーからのものに限られます:`jev-1.13.x`、または OpenRouter の `typesafe/jev-1.13-`。プロバイダーが Jev をエイリアスのみで識別しバージョンを報告しない場合(Vercel、および Cloudflare で明示しない場合)、回答は使用され未検証として記録されます。`custom` エンドポイントは応答したモデルを報告する必要があります。ただし、設定した未バージョンの `--model` 名がエコーバックされた場合は、同様に未検証として記録されます。他のバージョンを報告する回答、またはバージョンを報告しない `custom` の回答は使用されません。その呼び出しは `model-mismatch` の理由で正規表現にフォールバックします。 + +## Jev が回答できない場合 + +以下のそれぞれについて、その呼び出しの正規表現結果にフォールバックし、理由とともに記録されます。`failproofai jev status` でその合計を確認できます: + +| 理由 | 原因 | +| --- | --- | +| `timeout` | `timeoutMs` 以内に回答なし。 | +| `http-429` | プロバイダーがキーをレート制限した。 | +| `rate-limited` | Failproof AI 独自のリミッターが送信前に呼び出しを保留した:毎秒 5 リクエスト(バーストは最大 5)、プロバイダーが `429` を返した後は一時停止。プロバイダーではありません。 | +| `http-500`、`http-502`、`http-503`… | プロバイダーでのサーバーエラー。正確なステータスが記録されます。 | +| `out-of-credits` | HTTP 402:プロバイダーアカウントのクレジットが不足している。 | +| `provider-refused` | Cloudflare からの HTTP 402 で「Model execution failed (Payment error)」:プロバイダーがそのリクエストのモデル実行を拒否した。通常は請求の問題ではないため、残高を追加しても解決しません。 | +| `http-401`、`http-403` | キーが拒否された。 | +| `http-404` | `/systemone` に何も提供されていないため、ベース URL が誤っています。`/systemone` はベース URL に追加されます。各プロバイダーはバージョンルートで提供します。`failproofai jev models` でエンドポイントが提供しているものを確認できます。 | +| `network` | エンドポイントに到達できなかった。 | +| `http-301`、`http-302`、`http-307`、`http-308` | エンドポイントがリダイレクトで応答した。リダイレクトは追跡されないため、回答は常に設定内の URL からのみ来ます。`--base-url` を最終 URL に設定してください。 | +| `malformed` | エンドポイントが応答したが、Jev の回答形式ではありませんでした。JSON でないボディ、または回答を含まないボディ。 | +| `cloudflare-error`、`cloudflare-incomplete` | Cloudflare のエンベロープが失敗または未完了のジョブを報告した。 | +| `model-mismatch` | 1.13 以外の Jev バージョンが応答した、または `custom` エンドポイントが応答したモデルを報告しなかった。 | +| `request-cut` | **障害ではありません。** Jev が応答しましたが、呼び出しの一部のみが表示されたため、回答は何も解除しませんでした。[Jev が応答したが呼び出し全体ではなかった場合](#when-jev-answered-but-not-on-the-whole-call)を参照してください。 | + +`failproofai jev status` には、`upstream-error`(回答にプロバイダー独自のエラーが含まれていた)や `config` などのより稀な理由も表示されることがあり、識別できない理由は `other` として集計されます。 + +`request-cut` がこの表にあるのは、`failproofai jev status` が他の理由と合計して表示し、またこれもすべての deny をそのままにするためです。ここでプロバイダーについて何も示さない唯一の理由です。リクエストは届き、Jev はそれに回答しました。上のすべての行とは異なり、その回答はまだカウントされます。Jev 独自の deny または警告は正規表現結果に加えて適用され、破棄されません。したがって、`request-cut` が続く場合は、呼び出しがエバリュエーターに届いているが全体を送信するには大きすぎることを意味します。エンドポイントの問題ではなく、クレジットの追加や URL の変更では解決しません。 + +## Jev が応答したが呼び出し全体ではなかった場合 + +さらに 2 つのことが起こり得ますが、どちらも Jev の回答失敗ではありません。どちらも、呼び出しの何割、または会話の何割が 1 つのリクエストに収まったかに関するものです。 + +**呼び出し自体の一部が収まらなかった。** ツール呼び出しは固定されたバジェット内で送信されます。非常に大きな呼び出し(大容量の `Write`、巨大な MCP ボディ、上限いっぱいまでパディングされたコマンド)は収まった部分のみで送信されます。Jev は引き続き回答し、その回答は引き続きカウントされます。Jev 独自の deny または警告は通常通り適用されます。ただし、呼び出しの一部に対する判定は呼び出し全体の判定ではないため、**解除**はできません。したがって、すべてのポリシーの deny は維持され、その呼び出しは `request-cut` の理由でフォールバックとして記録されます。`failproofai jev status` では上記の理由と合計されます。これが示すルール:呼び出しを大きくすると解除が失われる可能性があり、解除を獲得することはできません。 + +**メッセージが収まらなかった。** 貼り付けた長いプロンプト、エージェントの最後のメッセージ、またはこのエバリュエーター独自のストアが既に上限に達したプロンプト。**何も変わりません**。呼び出しは他のものと同様に判定・解除・記録され、フォールバックとしてカウントされません。入力した内容の長さが判定を左右することはなく、カットによって同意が生成されることもありません。プロンプトが既に上限に達して届いた場合、「これを依頼していなかった」という結論はまったく導き出せなくなります。 + +この 2 つの違いはテキストを誰が書いたかです。呼び出しはエージェントのものであり、その長さが深刻度を減らすルールはエージェントが利用できるルールになります。あなたのプロンプトはあなたのものであり、その長さをシグナルとして扱うことは、仕様やスタックトレースを貼り付けることを罰するだけです。 + +## マシンから何が送信されるか + +Jev が評価する各ツール呼び出しに対して、1 つのリクエストがプロバイダーに送信されます。内容は次のとおりです: + +- ツール呼び出し自体(API キー、Bearer トークン、`KEY=` の代入などのシークレットはリダクション済み) +- 最近入力したプロンプト(エージェントのハーネスが追加したテキストは除去済み) +- 最新のプロンプト前のエージェントの最後のメッセージ(エージェント作成として標識) +- ローカルで計算されたファクト(パスがプロジェクト内にあるかどうかなど)。プロジェクトは、最初にレビューされた呼び出し時のセッションにあったもので、[セッション中は固定](/ja/reference/jev-intent#the-project-root)されます。現在の git ブランチも含まれます。 + +送信先は設定内のエンドポイントのみで、あなたのキーを使用します。 + +## オフにする + +```bash +failproofai jev remove +``` + +これにより `~/.failproofai/jev.json` が削除されます。次のツール呼び出しから、フックは以前と同様に正規表現ポリシーを実行します。`~/.failproofai/state/semantic/` 以下のセッションごとのストア(`sessions/` の記録されたプロンプト、`roots/` のプロジェクトルート)はそのまま残り、自動的に期限切れになります。Jev への問い合わせを停止しつつ設定を保持するには、代わりに `failproofai jev setup --mode off` を使用してください。 + +## コマンドリファレンス + +| コマンド | 結果 | +| --- | --- | +| `failproofai jev --url --key-stdin` | 1 つのコマンドで設定。プロバイダーは URL のホストから決定されます | +| `failproofai jev --url --token ` | 同上。キーをコマンドラインに置きます — 履歴とプロセスリストに表示されます | +| `failproofai jev setup --provider --key-stdin` | stdin からパイプされたキーで設定を書き込む | +| `failproofai jev setup --provider ` | 同上。マスクされたプロンプトでキーを求めます | +| `failproofai jev setup --key-from-env` | キーを保存しない。セッションごとに `FAILPROOFAI_JEV_API_KEY` を読み取る | +| `failproofai jev setup --mode shadow` | モードを切り替える(`enforce`、`shadow`、`off`)。保存済みのキーは維持 | +| `failproofai jev setup --model ` / `--base-url ` | モデルまたは API ベースを上書きする。`default` で上書きを解除 | +| `failproofai jev setup --timeout-ms ` | 呼び出しごとのバジェットを変更する | +| `failproofai jev status [--json]` | 設定、パーミッション、最近のアクティビティ。キーは表示しません | +| `failproofai jev test [--json]` | ライブリクエスト 1 回:レイテンシーと応答したバージョン | +| `failproofai jev models [--provider ] [--url ] [--json]` | そのエンドポイントの `/models` が報告するモデル ID(設定済みのものにマーク付き) | +| `failproofai jev remove` | 設定を削除。Jev がオフになります | \ No newline at end of file diff --git a/docs/ja/policies/jev-cloud.mdx b/docs/ja/policies/jev-cloud.mdx new file mode 100644 index 000000000..acdc8a77f --- /dev/null +++ b/docs/ja/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "FailproofAI Cloud を通じた Jev" +description: "FailproofAI Cloud 経由でエージェントのツール呼び出しを Jev に判定させましょう。組織のプランで利用でき、TypeSafe のアカウントや独自のキーは不要です。" +icon: "cloud" +--- + +TypeSafe のクラシファイアである [Jev](/ja/policies/jev-byok) は、各ツール呼び出しを実際の依頼内容と照らし合わせて読み取り、ポリシーと連携して判定を下します。ポリシーの代わりに動くのではなく、あくまで補完として機能します。**FailproofAI Cloud** を通じると、接続済みのマシンは既存の接続キーをそのまま使って Jev を利用できます。TypeSafe のアカウントも、追加のキーも、エンドポイントの設定も不要です。各呼び出しは組織の既存プランの利用枠に課金されます。 + +Jev の動作は [BYOK セットアップ](/ja/policies/jev-byok)と変わりません。ハードポリシーは常に最終判定となり、レビュー可能なポリシーの deny は Jev がまさにその懸念点について問われた場合にのみ解除され、障害が発生した場合はその呼び出しの正規表現結果にフォールバックします。 + + +**failproofai 1.0.8-beta.0** 以降が必要です。1.0.7 は 1.0.7 ベータより新しいように見えますが、Jev は含まれていません。Jev の設定がない場合は何も変わりません。フックは従来どおり正規表現ポリシーのみを実行します。 + + +## 有効にする + +1. **Jev 付きのキーを作成します。** FailproofAI Cloud ダッシュボードで **Keys → Create key** を開き、**machine** プリセットを選択します。これによりマシンに必要な 3 つの権限が付与されます: `events:add`(アクティビティの送信)、`policies:pull`(ポリシーの受信)、`jev:evaluate`(Jev の利用、組織のプランに課金)。`jev:evaluate` は他の 2 つの権限なしには付与できません。 +2. そのキーで**マシンを接続**します: + + ```bash + failproofai config --token + ``` + + 組織がホスト型ではなく独自の FailproofAI Cloud を運用している場合は、そのアドレスを追加してください: `--url https://`(または `FAILPROOFAI_CLOUD_URL` をエクスポート)。指定しないとキーはホスト型サービスに対して検証されるため、接続に失敗します。そのホストの証明書がプライベート CA によるものであれば、`NODE_EXTRA_CA_CERTS` だけでなく、マシンのシステムトラストストアに CA をインストールしてください(例: `update-ca-certificates` を使用)。イベントを送信してポリシーを取得するデーモンはシステムストアを参照します。詳しくは[トラブルシューティング](/ja/reference/troubleshooting)を参照してください。 + +以上です。接続するとキーが保存され、マシンに Jev の設定が**ない**場合は、FailproofAI Cloud 経由で Jev が**shadow** モードでオンになります。ゲートされたすべてのツール呼び出しについて Jev に問い合わせが行われ、その判定が記録されますが、ポリシーの結果が実際に適用されます。出力にはその旨が表示されます: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**`--no-transcripts` を指定した場合、接続しても Jev はオンになりません。** Jev はチェック済みの各ツール呼び出しと最近のプロンプトを FailproofAI Cloud に送信しますが、これは decisions-only の接続が送信を求めるものより多い内容です。キーは保存され、出力には Jev が利用可能であることとオンにする方法が表示されます: + +```bash +failproofai jev setup --provider failproofai +``` + +Jev を**オフにする**操作でもありません。マシンの `jev.json` がすでに FailproofAI Cloud 経由で Jev を実行している場合はそのまま維持され、Jev が引き続き各チェック済みツール呼び出しと最近のプロンプトを送信していることが出力に表示されます。オフにするには `failproofai jev setup --mode off` を使用してください。 + + +接続操作は既存の `~/.failproofai/jev.json` を**上書きしません**。すでに独自の Jev エンドポイントを使用している場合は引き続きそちらが使われ、ファイルがそのまま残っていることが出力に表示されます。そのファイルが Jev をオフ(拒否、またはオフに切り替え済み)にしている場合は、その旨と修正方法も表示されます。そのマシンを FailproofAI Cloud に切り替えるには `failproofai jev setup --provider failproofai` を実行してください。 + + +## shadow、enforce、off の切り替え + +shadow から始めてポリシーページで Jev がどのように動作するかを確認してから、実際に適用させましょう: + +```bash +failproofai jev setup --mode enforce # Jev の判定が適用される: レビュー可能な deny を解除し、独自の判定を追加できる +failproofai jev setup --mode shadow # Jev への問い合わせと記録のみ行い、ポリシーの結果が適用される +failproofai jev setup --mode off # 設定を保持したまま Jev への問い合わせを停止する +``` + +同じ切り替えはローカルダッシュボードの **Settings → Jev** にもあります。モードのみを書き換え、それ以外は変更しません。フックはツール呼び出しのたびに設定を読み込むため、変更は次の呼び出しから即座に反映されます。再起動は不要です。 + +## 動作状況を確認する + +```bash +failproofai jev status +failproofai jev test +``` + +`status` はプロバイダーを **FailproofAI Cloud**、マシンが接続した Cloud ホスト、モード、キーのソースを **FailproofAI Cloud connection** として表示します(キー自体は表示しません)。FailproofAI Cloud の `jev.json` が存在するが Jev を実行できない場合は、その理由が表示されます: + +| `status` の表示 | `status --json` | 意味 | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | マシンは接続されているが、Jev キーが保存されていない: キーに `jev:evaluate` がないか、接続時に確認できなかった。同じキーで `failproofai config --token ` を再実行してください。権限がない場合は **machine** キーを使用してください。 | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | このマシンに Jev キーが属する FailproofAI Cloud 接続が存在しない。 | + +`failproofai config --disconnect` の実行後、FailproofAI Cloud の `jev.json` はなくなります(オフに切り替えられていた場合はそのまま残ります)。そのため `status` は単に Jev がオフであると報告します。`status --json` も同じ情報を含みます(`provider: "failproofai"`、`keySource: "cloud"`、`cloudConnected`、`keyCarriesJev`)。設定がないか拒否された場合も同様です。`permissions` は常に `jev.json` のものです。`credentials.json` に関する拒否には `credentialsPermissions` が追加され、1 つのコマンドで修正できる場合は `fix` も含まれます。`test` はライブリクエストを 1 件送信し、レイテンシと応答した Jev のバージョンを報告します。フックのタイムアウト後に応答が届いた場合(フックは `timeout` と記録します)や、チェック質問に誤答した場合は、タイトルにその旨が表示され、終了コード 1 で終了します。 + +ダッシュボードの **Settings → Jev** パネルにも **FailproofAI Cloud connection** が表示されます。マシンが属する組織と、そのキーが Jev を持っているかどうかが確認できます。これはマシン自身のファイルから読み取られ、ネットワーク呼び出しは発生しません。 + +## ポリシーページに表示される内容 + +マシンはすでにフックのアクティビティを FailproofAI Cloud に送信しています(`events:add`)。Jev がオンの場合、ゲートされた各呼び出しの記録には、実行された評価器、Jev の判定、解除されたポリシー、フォールバックした理由、レイテンシ、応答したモデルも含まれます。コマンドやプロンプトは含まれず、判定・コード・名前のみです。組織の**Policies** ページでは: + +- Jev 自身の判定で決定された呼び出し(enforce モード)は **Jev** に帰属し、判定チェックがパックから来た場合はそのパック名とバージョンも記録される +- shadow モードでは、Jev の deny または warning は **would-have** として表示され、観察中のロールアウトの隣に表示される +- Jev が解除した、または shadow モードで解除したであろうポリシーは、ポリシーごとにカウントされる + +## Jev が応答できない場合 + +以下のいずれの場合も、その呼び出しのポリシー結果にフォールバックし、その理由とともに記録されます: + +| 理由 | 原因 | +| --- | --- | +| `out-of-credits` | 組織のプラン利用枠を使い切った。 | +| `http-401`, `http-403` | キーが失効したか、`jev:evaluate` を持っていない。対応した権限を持つキーで再接続してください。 | +| `http-429` | FailproofAI Cloud が組織の Jev をレート制限している。要求された待機時間(`Retry-After`、最大 60 秒)が経過するまで、マシンは何も送信せずすべての呼び出しが即座にフォールバックします。このように保留された呼び出しは `http-429` として記録されます。マシン自身のレート制限が先に適用された場合は `rate-limited` として記録されます。 | +| `http-429`(日次制限) | 組織の日次 Jev 呼び出し上限に達した: **UTC 1 日あたり 10,000 回**(FailproofAI Cloud の運用者が別の制限を設定している場合を除く)。カウントが 00:00 UTC にリセットされるまで、すべての呼び出しがフォールバックします。マシンは最大 1 分に 1 回再試行するため、リセット後 1 分以内に検出されます。`failproofai jev test` は「Daily Jev limit for this org reached; resets at 00:00 UTC.」と表示します。 | +| `http-422` | Jev がこの呼び出しのリクエストを拒否した。通常、ツール呼び出しに密度の高いテキスト(base64、hex、minified コード)が含まれており、Jev のトークン予算を超えているためです。この呼び出しは毎回フォールバックします。障害ではありません。 | +| `http-502` | Jev が現在利用できない。 | +| `http-503` | この Cloud は組織の Jev を提供できない: モデルゲートウェイがない、組織がまだプロビジョニングされていない、またはゲートウェイがダウンしている。管理者に問い合わせてください。フックは最大 1 分に 1 回再試行します。 | +| `http-404` | この FailproofAI Cloud はまだ Jev を提供していない。 | +| `timeout` | `timeoutMs`(デフォルト 3000)以内に応答がなかった。 | +| `model-mismatch` | バージョン 1.13 以外の Jev が応答した。 | + +## キーの保存場所と送信先 + +- キーは `~/.failproofai/credentials.json`(`0600`、所有者専用ディレクトリ)に一度だけ保存され、他の FailproofAI Cloud の認証情報と並置されます。このルートでは `jev.json` にキーは保存されません。そこにキーが書かれると設定が無効になります。 +- `credentials.json` に所有者以外(グループまたはその他、読み取りまたは書き込み)の権限がある場合、またはそのディレクトリが所有者以外から**書き込み**可能な場合、ファイルは**拒否**されて読み取られず、修正するまで Jev はオフのままになります: ファイルに `chmod 600`、ディレクトリに `chmod 700`(または再接続すると `0600` でファイルを書き直し、ディレクトリを所有者専用にします)。他者が読み取りのみ可能なディレクトリは問題ありません。書き込みが可能な場合はファイルの入れ替えが可能になります。 +- キーは接続とセットの場合にのみ有効です: 同じ FailproofAI Cloud への同じキーによるポリシーまたは報告の認証情報が、同じファイルに存在する必要があります。接続なしに残された Jev キーは無視され、Jev はオフのままです。これは、古い failproofai の `config --disconnect` が Jev キーをそのままにした場合(削除方法を知らないため)や、古い failproofai の `config --token` が別のキーで接続した場合(FailproofAI Cloud 上では別の組織に属する可能性がある)に発生します。Jev を再度オンにするには、**machine** キーで再接続してください。 +- キーは検証された Cloud オリジンにのみ送信されます。別の場所を指す `jev.json` は拒否されます。 +- **マシン上のエージェントがキーを読み取ることができます。** `credentials.json` は所有者専用ですが、エージェントはその所有者として実行されます。failproofai 自身のファイルの読み取りは意図的に許可されています(変更のみ `block-failproofai-commands` によってブロックされます)。そのため、エージェントとこのファイルの間にあるのは `block-read-outside-cwd`(*レビュー可能な*ポリシー)のみです。ホームディレクトリから開始されたセッションからは、何も遮るものはありません。`jev:evaluate` 権限を持つキーは、使用される場所を問わず組織の Jev 利用枠(日次上限まで)を消費します。そのため、マシンキーは他の支出認証情報と同様に扱ってください。エージェントがキーを読み取った可能性がある場合は、Keys ページで無効化し、新しいキーで再接続してください。 +- これを制御するのはグローバルファイルのみです。リポジトリから Cloud Jev をオンにしたり、別の場所を指定したり、キーを提供したりすることはできません。また、このルートでは `FAILPROOFAI_JEV_API_KEY` は無視されます。 +- Jev が評価する各呼び出しについて、FailproofAI Cloud への 1 件のリクエストが送信されます。内容は [BYOK ページ](/ja/policies/jev-byok#what-leaves-the-machine)に記載されているもの(シークレットはリダクション済み)です。FailproofAI Cloud はそれを TypeSafe に転送し、記録や保持は行いません。 + +## オフにする + +| コマンド | 結果 | +| --- | --- | +| `failproofai jev setup --mode off` | 設定を保持したまま Jev への問い合わせを停止する。**これが持続的な切り替えです:** 再接続しても既存の `jev.json` は上書きされないため、`--mode shadow` で戻すまで Jev はオフのままです。 | +| `failproofai jev remove` | `~/.failproofai/jev.json` を削除し、Jev をオフにする。ただし、次に `jev:evaluate` 権限を持つキーで `failproofai config --token` を実行すると、`jev.json` が存在しないため shadow モードで Jev が再度オンになります(`--no-transcripts` での実行を除く)。オフのままにするには `--mode off` を使用してください。 | +| `failproofai config --disconnect` | マシンを切断する: キーが削除され、`jev.json` が FailproofAI Cloud を指定していてかつオフになっていない場合は `jev.json` も削除されます。独自エンドポイント用の `jev.json` はそのまま残り、オフに切り替えられたものも残るため、再接続後も Jev はオフのままです。 | + +次のツール呼び出しから、フックは従来どおり正規表現ポリシーのみを実行します。 \ No newline at end of file diff --git a/docs/ja/policies/jev.mdx b/docs/ja/policies/jev.mdx new file mode 100644 index 000000000..b5dd5541f --- /dev/null +++ b/docs/ja/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Jev のリアルタイムレビューをツール呼び出しのゲートに追加し、判断を適用する前に内容を確認します。" +icon: "shield-check" +--- + +Jev はツール呼び出しを、ユーザーがエージェントに依頼した内容と照らし合わせて読み取ります。文字列マッチングポリシーが有効な作業をブロックしたり、コンテキストが必要なリスクのあるアクションを見逃したりする場合に使用してください。`PreToolUse` または `PermissionRequest` ゲートで、既存のポリシーと並行して判断を返します。セッション終了**後**のスコアには、[Jev evaluations](/ja/evaluations/jev) を使用してください。 + +## オブザーブモードで開始する + +Failproof AI をインストールし、[対応ハーネス](/ja/reference/harnesses)にフックをアタッチしてください。failproofai 1.0.8-beta.0 以降が必要です。 + +Failproof AI には Jev チェックが含まれていません。パックとしてインストールする必要があります。インストールしなければ Jev に問い合わせる内容がなく、呼び出されることもありません: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +次に、リクエストを Jev へ届けるルートを選択します: + +| ルート | 最初のステップ | +| --- | --- | +| FailproofAI Cloud | `jev:evaluate` 権限を持つ **machine** キーで接続します。Jev の設定がないマシンでは、`failproofai config` を実行することで Jev がオブザーブモードで有効になります。 | +| 独自プロバイダー | ローカルダッシュボードで **Settings → Jev** を開き、プロバイダーを選択してトークンを貼り付け、**observe** を選択します。または `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key` を実行します。 | + +![ローカルダッシュボードの Jev 設定画面:Jev を有効にする前のプロバイダー、エンドポイント、トークン、オブザーブモードの設定。](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` はエンドポイントを確認します。フックパスを確認するには、フックされたエージェントにファイル読み取りツールで `README.md` を参照するよう依頼してください。そのツール呼び出しがセッションに表示されることを確認し、[ローカルダッシュボード](/ja/reference/local-dashboard#review-policy-activity)の **Policies → Activity** で内容を確認します。`status` の Jev カウントが増加しているはずです。オブザーブモードでは、既存のポリシー結果はそのまま適用しながら、Jev がどのような判断を下したかを記録します。 + +## 適用するタイミングを決める + +**hard** ポリシーは常に最終決定権を持ちます。Jev が deny を解除できるのは、明示的に **reviewable** とマークされたポリシーに対してのみであり、かつそのポリシーが指定した懸念事項を Jev が確認した場合に限られます。クリアランスに依存する前に、[policy authority](/ja/policies/authority) を確認してください。Jev は独自に警告や拒否を行うこともできます。回答できない場合は、ポリシーの結果でそのツール呼び出しが決定されます。 + +オブザーブの結果が適切であることを確認したら、**Settings → Jev** でエンフォースモードに切り替えるか、次のコマンドを実行してください: + +```bash +failproofai jev setup --mode enforce +``` + +プロバイダー URL、Cloud キー、設定、フォールバック、各リクエストで送信されるデータについては、[Jev integration reference](/ja/reference/jev) を参照してください。 \ No newline at end of file diff --git a/docs/ja/reference/custom-agents-typescript.mdx b/docs/ja/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..b1f6c4d7a --- /dev/null +++ b/docs/ja/reference/custom-agents-typescript.mdx @@ -0,0 +1,426 @@ +--- +title: "カスタムエージェント(TypeScript)" +description: "@failproofai/sdk の設定、イベントカタログ、スコープ、フレームワークアダプターの詳細リファレンス。" +icon: "square-js" +--- + +TypeScript SDK の各設定・メソッド・フィールドの詳細説明です。初めてインストルメント化する場合はガイドから始めてください。このページはリファレンスとして参照するためのものです。 + + + + インストール、インストルメント化、イベントメソッド、実例、よくある問題について。 + + + 同じイベント、同じワイヤーフォーマット、同じスプール — Python 版。 + + + +Node 20.9 以降。ESM および CommonJS 対応。ランタイム依存関係なし。 + + + この SDK と Python SDK は**同じスプールに同じイベントを書き込みます**。Node エージェントと Python エージェントが混在するフリートは、2 つではなく 1 つのセッションセットを生成し、ダッシュボード上で両者を区別する表示もありません。サービスごとに選択してください。会社単位ではなく。 + + +## インストール + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +フレームワークアダプターはパッケージ自体に含まれています。フレームワークは**オプションのピア依存関係**として宣言されており、サポートされるバージョン範囲が明示されています。自動的にインストールされることはなく、`instrument()` を呼び出したときにのみインポートされます。 + +## Failproof デーモンへの接続 + +Python SDK と同様:**Admin → Keys** で `events:add` キーを作成し、エージェントマシン上で[デーモンを接続](/ja/start/setup#connect-a-machine-to-cloud)します。SDK はディスクに書き込み、デーモンが送信します。 + +## 設定 + +### OpenTelemetry スパン(オプトイン) + +`npm install @opentelemetry/api @opentelemetry/sdk-trace-base` で OpenTelemetry を別途インストールします。 +その後、プロバイダーのプロセッサーに FailproofAI を追加します: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +既存のプロバイダーを使用する場合は、同じリストに他のプロセッサーを含めてください。`addSpanProcessor` を公開しているプロバイダーは、代わりに `{ provider }` として渡すことができます。オプションなしで設定すると、まだプロバイダーが登録されていない場合にのみ新しいプロバイダーが登録されます。 +`OtelSpanExporter` は独自のプロセッサーで直接使用することもできます。 + +エクスポートは接続済みの FailproofAI デーモンを経由します。SDK はネットワークリクエストを送信せず、キーやローカルリスナーも必要ありません。管理者に [OpenTelemetry インジェスト](/ja/agenteye/opentelemetry)の有効化を依頼してください。引数なしの `instrument()` ではこのエクスポーターは有効になりません。`uninstrument("otel")` は自身のプロセッサーのみを無効化します。スパン属性がコンテンツキャプチャを制御します。終了前にプロバイダーをフラッシュしてください。OpenTelemetry は SDK のハード依存関係ではなく、オプションのアプリケーション依存関係のままです。 + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| オプション | 説明 | +| --- | --- | +| `environment` | すべてのイベントに付くラベル(`production`、`staging`、`prod-eu` など)。デフォルトは `dev`。 | +| `flushInterval` | タイマーがディスクに書き込む間隔(秒)。デフォルトは `0.5`。 | +| `baseDir` | 書き込み先。デフォルトはデーモンのスプール(特段の理由がない限りこれが適切)。 | + +すべての値が検証を通過した場合のみ設定が適用されます。失敗した呼び出しは SDK を変更前の状態のままにします。新しい `baseDir` と古いインターバルが混在することはありません。 + +環境変数で設定することもできます: + +| 変数 | 説明 | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | コード変更なしに `environment` を設定する。`configure()` オプションが優先。 | +| `FAILPROOFAI_HOME` | スプールを格納する Failproof AI ルートを変更する。 | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`、`info`、`warn`(デフォルト)、`error`、`silent`。 | +| `FAILPROOFAI_SDK_STRICT` | `1` に設定するとインストルメンテーションエラーがログ記録ではなく例外をスローする。 | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` に設定するとフレームワーク互換性の問題が警告を出して続行するのではなく例外をスローする。 | + + + **`environment` にカンマを含めないでください。** インジェストはこのフィールドをカンマで分割してフィルターを構築しており、ラベルにカンマが含まれるイベントはすべてスキップされます — 実行全体がサイレントに消えることになります。`prod,eu` ではなく `prod-eu` と書いてください。 + + `configure({ environment: "prod,eu" })` はすぐに気づけるよう例外をスローします。`AGENTEYE_ENVIRONMENT` は例外をスローできません(呼び出し元がいないため)。一度警告を出し、`dev` にフォールバックします。 + + +`failproofai.setLogger({ debug, info, warn, error })` を使用して SDK 自身のログを独自のロガーに転送できます。 + +## シャットダウン + +バッファリングされたイベントは `process.on("exit")` でフラッシュされます。 + +シグナルで kill されたプロセスはそこに到達しません。Node の `SIGTERM` のデフォルト動作は exit ハンドラーを実行せずに終了することです — そのため、コンテナ化されたエージェントは最後のインターバル以降に書き込まれていない内容を失います。 + + + **この SDK はシグナルハンドラーを自動インストールしません。** ハンドラーを登録するとプロセスの動作が変わります。リスナーが追加されると Node のデフォルト終了が抑制されるため、ライブラリが勝手に追加すると Ctrl-C が無音で機能しなくなります。独自に追加してください: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +短命なスクリプトやサーバーレスハンドラーはリターン前に `await failproofai.flush()` を呼び出す必要があります — インターバルだけでは配送を保証できません。 + +## アイデンティティ + +すべてのイベントはセッションとエージェントに属します。**スコープが両方を設定する**ため、直接渡す必要はほとんどありません: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +`sessionId` や `agentId` を明示的に渡すことも可能で、その場合は渡した値が優先されます。バインドも渡しもない場合、Cloud が静かに破棄するようなイベントを送出するのではなく、例外をスローします。 + + + アイデンティティは `AsyncLocalStorage` で伝播します。`await`、`.then()`、タイマー、スコープ内で作成されたコールバックを追います。ただし、あるラン中に保存されて別のラン中に呼び出されるコールバックや、`worker_threads` の境界を越えて渡される処理には追従しません — それらは `failproofai.propagate()` でラップしないと、イベントが紐付けられません。 + + +### スコープ + +| スコープ | 送出 | 戻り値 | +| --- | --- | --- | +| `session(body)` | なし(アイデンティティのみ) | `body` の戻り値 | +| `agent(id, options?, body)` | `agent_start`、その後 `agent_end` | `body` の戻り値 | +| `toolCall(name, options?, body)` | `tool_use`、その後 `tool_result` | `body` の戻り値 | + +同期的なボディは同期のままです:`agent("x", () => 1)` は Promise ではなく `1` を返します。 + +`toolCall` はボディの解決値をツールの `output` として記録します(`call.output` を自分で設定した場合を除く)。 + + + +| 状況 | イベント | `outcome` | +| --- | --- | --- | +| ブロックが返った | `agent_end` | `"success"`、またはカスタムの `outcome` | +| ブロックが例外をスローした | `error`、その後 `agent_end` | `"failed"` | +| `AbortError` | `agent_end` のみ | `"cancelled"` | + +エラーは常に再スローされます。 + +ツールの失敗はリーフ(`tool_result` の `error` 文字列)に記録され、ラン全体の `error` イベントは**送出されません**。エージェントループがキャッチしたものはラン失敗ではなく、伝播するものはちょうど一度、外側の `agent()` によって報告されます。 + + + + + +作業が単一の関数ではない場合 — コンストラクターで開いてティアダウンで閉じるスコープや、既存の制御フローをまたぐスコープ: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +どちらの形式もバイト単位で同一のイベントを送出します。コールバック形式が推奨です:`AsyncLocalStorage.run()` の中で実行されるため、巻き戻す必要がなく、「ここで開いてあそこで閉じる」バグのクラス全体が回避できます。 + +自身の失敗をキャッチする `using` ブロックは `span.fail(error)` で報告します — ディスポーザー自身には例外チャンネルがありません。 + + + +## イベントカタログ + +Python SDK と同じ 15 のメソッド(camelCase)。ほとんどは**ペア**になっており、オープナーを呼び出してからクローザーを呼び出すと、SDK が間隔を計測します。 + +| | 開く | 閉じる | +| --- | --- | --- | +| **エージェント** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **モデル** | `modelRequest` | `modelResponse` | +| **ツール** | `toolUse` | `toolResult` | +| **フック** | `hookTriggered` | `hookCompleted` | +| **人間** | `humanWait` | `humanInput` | + +3 つは単独で使用:`error`、`humanPause`、`humanInterrupt`。 + + + +すべてのメソッドは `sessionId` と `agentId` も受け取りますが、スコープが自動で設定します。省略したフィールドは JSON `null` として送出されるのではなく、削除されます。 + +| メソッド | 必須 | オプション | +| --- | --- | --- | +| `agentStart` | — | `goal`、`parentId` | +| `agentEnd` | — | `outcome`、`summary` | +| `agentPause` | `pauseId` | `reason`、`userId` | +| `agentResume` | `pauseId` | `reason`、`userId` | +| `modelRequest` | — | `model`、`messages`、`system`、`tools`、`requestId` | +| `modelResponse` | — | `model`、`stopReason`、`inputTokens`、`outputTokens`、`content`、`role`、`requestId` | +| `toolUse` | `toolName`、`toolCallId` | `input` | +| `toolResult` | `toolName`、`toolCallId` | `output`、`error` | +| `hookTriggered` | `hookName`、`hookId` | `triggerEvent`、`input` | +| `hookCompleted` | `hookName`、`hookId` | `outcome`、`output`、`error` | +| `error` | `errorType`、`message` | `traceback` | +| `humanWait` | `inputId` | `prompt`、`options`、`reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`、`userId` | +| `humanInterrupt` | — | `reason`、`userId`、`atStep` | + +追加したその他のキーはカスタムペイロードフィールドになります。フレームワーク固有のものは `fw_*` で名前空間を付けてください。宣言済みフィールドと名前が衝突した場合は、プロモートされたカラムを無音で上書きするのではなく、拒否されます。 + + + + + **`duration_ms` は計算値であり、受け付けません。** 4 つのクローズメソッドはオープナーからの経過時間を計測し、呼び出し元が指定した `duration_ms` を拒否します — 報告された継続時間は改ざん不可能でなければなりません。 + + ペアは**セッション**と ID でマッチングされ、エージェントでは行われません。`planner` の下で開かれて `worker` の下で閉じられたツールも正しくペアリングされます。これはネストされたマルチエージェント実行で実際に行われることです。 + + +## フレームワークアダプター + +```ts +await failproofai.instrument(); // 検出できるものすべてに適用 +await failproofai.instrument("langchain"); // 1 つに限定 +failproofai.uninstrument(); // すべて元に戻す +``` + +| フレームワーク | サポート | アタッチ方法 | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x、LangGraph.js 0.4 – 1.x | `CallbackManager.configure` を使用するため、`callbacks:` を渡すことなくすべての `invoke`/`stream`/`batch` がカバーされます — または `langchainHandler()` を自分で渡してパッチを当てない方法も選択可。 | +| **Vercel AI SDK** | `ai` 4 – 7 | コールサイトで `telemetry()` を使用、または `ai` 7 では `instrument("ai")` でプロセス全体に適用(4–6 ではオプトイン — 下記参照)。 | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`、エージェントのモデルとツール解決、ワークフロー実行/ステップエンジン。 | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager`(サブスクライブ済み)と `AgentWorkflow.runStream` を使用して、ワークフロー実行とそのステップをカバー。 | + +すべての範囲は実際のフレームワークリリースに対してテストされており、両端のバージョンについて、ES モジュールおよび CommonJS として、すべての CI 実行で検証されています。 + +マッピングは Python SDK と同じため、同じプログラムがどちらの言語でも同じツリーを描画します。構成が**エージェント**となるのは、LLM の意思決定ループを持つ場合のみです — グラフまたはチェーンの実行、AI SDK の `generateText`/`streamText` 呼び出し、Mastra エージェント、LlamaIndex エージェント実行。LangGraph ノードやワークフローステップは**フック**(`hook_triggered`/`hook_completed`)であり、ネストされたエージェントではありません。モデル呼び出しはトークン数を含む `model_request`/`model_response` ペアです。ツール呼び出しにはモデル自身のツール呼び出し ID が付きます。失敗は発生したイベント上で一度だけ記録されます。 + +インストールに失敗したアダプターはログに記録されてスキップされます。他のアダプターは引き続きインストールされます。LlamaIndex の問題が LangGraph に影響しないようにするためです。 + + + 引数なしの `instrument()` は、フレームワークがすでにインポートされているかどうかではなく、**解決できるかどうか**でフレームワークを検出します — Python の `sys.modules` に相当するものを ES モジュールに対して Node は提供していません。インストール済みだが使用していないフレームワークはインポートされてパッチが当てられます。これが問題になる場合は、使用するものを明示的に指定してください。 + + + + これらのフレームワークのほとんどは ES モジュールビルドと CommonJS ビルドの両方を提供しており、Node はそれらを 2 つの別々のコピーとして読み込みます。アダプターはアプリケーションが読み込んだコピー(すでに `require` されていれば CommonJS コピーも)にパッチを当てるため、両方のモジュールシステムで動作します。esbuild や webpack によって**独自の出力にバンドルされた**フレームワークは届きません — そこではコールサイトヘルパーを使用してください:`langchainHandler()`、`telemetry()`、`wrapTool()`。 + + +### パッチなしの LangChain + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +ハンドラーは `instrument()` の有無にかかわらず動作し、二重記録しません。`instrument("langchain")` は Python アダプターと同様に `sessionId`、`captureContent`、`includeChains`、`graphCallbacks`、`captureLimit` を受け取ります。呼び出しに `metadata: { failproofai_sdk_session_id }` を付けると、その呼び出しのセッションを選択できます。 + +### Vercel AI SDK + +AI SDK は ES モジュールからプレーンな関数をエクスポートしており、ES モジュールの名前空間は仕様上イミュータブルです — パッチを当てる場所がありません。SDK 自身がドキュメント化している拡張ポイントを使用します: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // ai 7 では `telemetry: telemetry({ … })` — 同じオブジェクト、新しい名前 +}); +``` + +これが完全な統合です:エージェントスパン、ステップごとにトークン数を含むモデルリクエスト/レスポンスペア、そしてすべてのツール呼び出し。1 つのコールサイトがすべてのメジャーバージョンで動作します — `ai` 4–6 は付属するトレーサーを読み取り、`ai` 7 はテレメトリーインテグレーションを読み取ります。 + +**`ai` 7 では** `instrument("ai")` が同じことをプロセス全体に適用します:AI SDK のグローバルテレメトリーインテグレーションリストを通じてすべての呼び出しをキャプチャします。このリストは追加型で、他の設定に影響しません。 + +**`ai` 4–6 では、`instrument("ai")` 単体では何も記録せず、その旨の警告を 1 回ログに出力します。** これらのメジャーバージョンが持つプロセス全体のフックは、グローバル OpenTelemetry トレーサープロバイダーのみです — これは一度取得されると返却されない単一スロットです。自分たちのものを登録すると、起動後半の `NodeSDK.start()` が暗黙的に失敗し、http/database スパンが何もエクスポートしないトレーサーに送られてしまいます。コールサイトで `telemetry()` を使用するか、そこで `wrapModel` を使用してください。プロセスが独自の OpenTelemetry を実行していない場合は、`instrument("ai", { registerGlobalTracer: true })` でオプトインできます:その場合、`experimental_telemetry: { isEnabled: true }` を渡すすべての呼び出しが記録され、スロットが空の場合にのみ取得します。`registerGlobalTracer: false` はデフォルトを維持し、警告を抑制します。 + +モデルを一度ラップしたい場合は `wrapModel` を使用できますが、ツール呼び出しはモデルレイヤーの上で行われるため、モデル呼び出しのみが見えます。ラップされたモデルが何も囲まれていない状態で呼び出された場合、独自のランとして記録されます。ストリーミング呼び出しは、ストリームの終了方法にかかわらずクローズされます — コンシューマーがキャンセルした場合は `stop_reason: "cancelled"`、途中で失敗した場合はエラー付きで `"error"`: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +両方を使用しても問題ありません:ミドルウェアは呼び出しがすでに記録されていることを検出して処理を委ねるため、各呼び出しは一度だけ記録されます。 + +`functionId` はエージェントスパンの名前となります。低カーディナリティを保ってください — ダッシュボードのプライマリファセットである `agent_id` に入ります。 + +### Next.js + +`next build` はデフォルトでサーバーの依存関係をバンドルしますが、ビルドにバンドルされたフレームワークは `instrument()` が届かないコピーになります。設定を一度ラップし、Next のスタートアップフックから `instrument()` を呼び出してください: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` は LangChain、Mastra、LlamaIndex、SDK 自体を `serverExternalPackages` に追加し、既存のリストを維持します。これがない場合、`instrument()` は届かない各フレームワークについて黙って失敗するのではなく、一度警告を出します。パッケージを自分でリストする場合は `FAILPROOFAI_NEXT_EXTERNALS=1` を設定してください。Vercel AI SDK とコールサイトヘルパーはどちらの方法でも動作します。Edge ルートは no-op ビルドを受け取ります:SDK をインポートしても安全で、何も記録されません。 + +### ストリーミング呼び出しのトークン数 + +OpenAI 互換 API は、クライアントが要求したときのみストリーム上の使用量を報告します。LangChain と Vercel AI SDK は要求します。LlamaIndex の場合は `OpenAI` LLM に `additionalChatOptions: { stream_options: { include_usage: true } }` を渡し、Mastra の場合は使用量を有効にしてモデルをビルドしてください(例:`createOpenAICompatible({ includeUsage: true })`)。そうしないと、ストリーミングモデル呼び出しにはトークン数が含まれません。 + +### ランタイム + +Node ≥ 20.9、Bun、Deno — すべてのフレームワークについて、ES モジュールと CommonJS の両方で、Node のトレースと照合しながら各ランタイムでテストされています。SDK は書き込んだ内容を送信する `failproofaid` デーモンと並行して動作します。 + +## 独自のエージェント — フレームワークなし + +自分で書いたエージェントループ、またはアダプターがないフレームワーク用。アダプターが内部で使用している同じ API でイベントを送出するため、トレースは同じ形状と品質を持ちます。 + +エージェントがどのように整理されているかを知る必要はありません。すべての手作りエージェントには、関数の名前がどうであれ、3 つの箇所が既にあります。その 3 つが統合のすべてです: + +| 場所 | 追加するもの | 送出 | +| --- | --- | --- | +| **1 回の実行**の開始と終了 | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **モデルを呼び出す関数**(1 つ) | `event.modelRequest` を前に、`event.modelResponse` を後に — 失敗時も両方 | モデルターンごとに 1 ペア | +| **ツールを実行する関数**(1 つ) | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +アイデンティティはアンビエントです:`agent()` の内部にあるすべてのものは ID を受け取ることなくそのランのセッションに属し、プログラムの他の部分(エージェントが独自のデータベースに書き込んでいるものを含む)は何も変更されません。 + +- **サービスまたはワーカー:** 独自のリクエスト ID またはジョブ ID を `sessionId` として渡すと、ダッシュボード上のセッションと独自のログやデータベースのレコードが同じ文字列になります。 +- **サブエージェント:** `agent()` 呼び出しをネストします。内側のものは外側のものを `parent_id` として同じセッションに参加します。 +- **ペアを送出してください。** `modelResponse` のない `modelRequest` は、ダッシュボードが永遠に実行中として表示するスパンになります — `catch` が必要な理由はそこにあります。 + +リポジトリの [`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) は完全で実行可能なバージョンです:ちょうどこのようにインストルメント化された実際の OpenAI ツールループで、ES モジュールと CommonJS の両方として、変更のたびに CI で実行されます。 + +## 評価 + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +プロトコル、ワーカー設定、結果の型については [Evaluator SDK リファレンス](/ja/reference/evaluator-sdk) を参照してください。 + + + **評価は必ず yield しなければなりません。** 返却しない同期関数は Node が持つ 1 つのスレッドをブロックし、その間タイムアウトも発火できません。`async` 評価を書いてください。 + + +## プロセスへの影響 + +| | | +| --- | --- | +| **エージェントループをブロックしない** | イベントはインメモリキューに入り、タイマーが書き込む。タイマーは `unref` されているため、このパッケージをインポートしてもスクリプトの終了が妨げられることはない。 | +| **際限なく増大しない** | キューはカウントと計測バイト数の両方で上限が設けられている。どちらかを超えると最も古いイベントが破棄され、警告が出る — テレメトリーの障害が OOM kill になってはならない。 | +| **プロセスをダウンさせない** | エンコードできないイベントは 1 つだけ破棄され、周囲のバッチには影響しない。スローするゲッター、循環参照、`BigInt`、孤立サロゲートはそれぞれ伝播するのではなく処理される。 | +| **半分だけ書かれたバッチを残さない** | コンテンツはアトミックなリネームの前に `fsync` され、ディレクトリはその後に `fsync` され、失敗した書き込みは一時ファイルをクリーンアップする。 | +| **トランスクリプトを読み取り可能なままにしない** | バッチは `0700` ディレクトリ内で `0600` になる。ゴール、プロンプト、ツール引数、ツール出力を含む。 | +| **認証情報を送信しない** | API キー、トークン、JWT、Bearer ヘッダー、シークレットに見える代入はバイトがディスクに到達する前にリダクトされる。デーモンはアップロード前に再度リダクトする。 | \ No newline at end of file diff --git a/docs/ja/reference/custom-agents.mdx b/docs/ja/reference/custom-agents.mdx index 2233c7530..1db80b365 100644 --- a/docs/ja/reference/custom-agents.mdx +++ b/docs/ja/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -Python 3.10 以降が必要です。実行時の依存関係はありません。 +Python 3.11 以降が必要です。実行時の依存関係はありません。 ## インストール diff --git a/docs/ja/reference/jev-cloud.mdx b/docs/ja/reference/jev-cloud.mdx new file mode 100644 index 000000000..b98d8b84d --- /dev/null +++ b/docs/ja/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "FailproofAI Cloud 経由の Jev" +description: "ライブ Jev ポリシーレビューのための Cloud マシンキー、接続状態、制限、および障害時の動作について。" +icon: "cloud" +--- + +これは [Jev ポリシー](/ja/policies/jev) の Cloud ルートリファレンスです。TypeSafe の分類器である Jev は、各ツール呼び出しを実際の要求内容と照合し、ポリシーと並行して判断を返します。ポリシーの代わりに動作するものではありません。**FailproofAI Cloud** を通じて、接続済みのマシンは既存の接続キーをそのまま使って Jev を利用できます。TypeSafe アカウント、2 つ目のキー、エンドポイントの設定は不要です。各呼び出しは組織の既存プランの利用枠から課金されます。 + +Jev の動作は [独自キー設定](/ja/reference/jev-providers) と変わりありません。ハードポリシーは最終決定のまま維持され、レビュー可能なポリシーの deny は Jev がその懸念事項について正確に問われた場合にのみ解除されます。また、いかなる障害も該当する呼び出しの正規表現結果にフォールバックします。 + + +**failproofai 1.0.8-beta.0** 以降が必要です。1.0.7 には Jev がありません。ソート順では 1.0.7 ベータ版より上に来ますが、Jev は含まれていません。Jev の設定がない場合は何も変わりません。フックはこれまでどおり正規表現ポリシーを実行します。 + + +## 開始前の準備 + +エージェントが動作するマシンに Failproof AI をインストールし、フックを[対応ハーネス](/ja/reference/harnesses)に接続します。ゼロから始める場合は、[クイックスタート](/ja/start/quickstart)のフックインストールまでの手順に従ってください。インストール済みの CLI を `failproofai --version` で確認し、Jev より前のバージョンであれば更新してください。また、マシンキーを作成するために組織の **Administration → Keys** ページへのアクセスも必要です。 + +Jev は `PreToolUse` または `PermissionRequest` ゲートで指定されたツール呼び出しをレビューします。セッション内のすべてのイベントをレビューするわけではありません。Jev がポリシーの deny を解除するところを確認するには、[reviewable](/ja/policies/authority) とマークされたポリシーがインストールされている必要があります。それ以外のポリシーの deny はすべて最終決定のままです。 + +## 有効にする + +1. **Jev 付きのキーを作成します。** FailproofAI Cloud ダッシュボードで **Administration → Keys → Create key** を開き、**machine** プリセットを選択します。これにより、マシンに必要な 3 つの権限が付与されます。`events:add`(アクティビティの送信)、`policies:pull`(ポリシーの受信)、`jev:evaluate`(Jev、組織のプランから課金)です。キーは他の 2 つなしに `jev:evaluate` を持つことはできません。 +2. そのキーで**マシンを接続**します。プロンプトでワンタイムシークレットを読み取り、次のセットアップコマンドを実行します。 + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` はデーモンをインストールし、検出されたエージェント CLI のフックを接続し、マシンを繋げます。環境変数を使うことで、キーがコマンド引数やシェル履歴に残るのを防ぎます。ハーネスを後からインストールした場合は、[明示的に接続してください](/ja/start/quickstart)。 + + 組織がホスト型ではなく独自の FailproofAI Cloud を運用している場合は、そのアドレスを追加します。`--url https://`(または `FAILPROOFAI_CLOUD_URL` をエクスポート)。指定しない場合、キーはホスト型サービスで検証され接続に失敗します。そのホストの証明書がプライベート CA から発行されている場合は、CA をマシンのシステムトラストストアにインストールしてください(例:`update-ca-certificates` を使用)。`NODE_EXTRA_CA_CERTS` だけでは不十分です。イベントを送信してポリシーを取得するデーモンはシステムストアを読み取ります。詳しくは[トラブルシューティング](/ja/reference/troubleshooting)をご覧ください。 + +以上です。接続するとキーが保存され、マシンに Jev の設定が**ない**場合は FailproofAI Cloud 用の設定が書き込まれます。マシンの最初のデプロイ(約 30 秒以内)から、FailproofAI Cloud がモードを設定します。Jev ポリシーがデプロイされている間は `enforce`、デプロイされていない場合は `off` です([モードを設定するのは誰か](#who-sets-the-mode) を参照)。出力にはその旨が表示されます。 + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +FailproofAI Cloud がデプロイするチェックは Cloud 上で実行されます。マシン上に独自のチェックを追加するには、パックをインストールします。 + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**`--no-transcripts` を指定して接続した場合、Jev は有効になりません。** Jev は確認した各ツール呼び出しと直近のプロンプトを FailproofAI Cloud に送信します。これは決定内容のみを送信するよう求めた接続より多くの情報を送ります。キーは引き続き保存され、出力には Jev が利用可能であることと有効にする方法が表示されます。 + +```bash +failproofai jev setup --provider failproofai +``` + +これにより FailproofAI Cloud 経由の Jev も**オフ**になります。FailproofAI Cloud 経由で Jev を実行する `jev.json`(トランスクリプトを有効にした以前の接続で残されたもの)は、`config --disconnect` と同じルールで削除されます。出力には、このマシンで FailproofAI Cloud 経由の Jev がオフのままであることが表示されます。独自の Jev エンドポイント用の `jev.json` はそのまま残り、オフに切り替えられた FailproofAI Cloud のもの(`--mode off`)も同様です。 + + +接続は既存の `~/.failproofai/jev.json` を**絶対に上書きしません**。すでに独自の Jev エンドポイントを使用している場合はそのまま使用され、出力にはファイルが設定どおりに残されたことが示されます。そのファイルで Jev がオフになっている場合(拒否またはオフに切り替えられた場合)は、その旨と修正方法も表示されます。そのマシンを FailproofAI Cloud に切り替えるには、`failproofai jev setup --provider failproofai` を実行してください。 + + +## モードを設定するのは誰か + +FailproofAI Cloud に接続されているマシンでは、**FailproofAI Cloud が Jev モードを設定します**。マシン側では何も設定しません。 + +- Jev(または正規表現 + Jev)ポリシーがマシンにデプロイされている間は `enforce` になります。そのポリシーがターゲットとするエージェントからのチェック済みツール呼び出しはすべて FailproofAI Cloud に送られ、Cloud はそのマシンにインストールされたパックのチェックとともに確認します。Cloud の Jev ポリシーがターゲットとしないエージェントからの呼び出しで、パック独自のチェックもない場合は、まったく送信されません。`enforce` では、Jev 独自の deny チェックは呼び出しをブロックし、レビューした正規表現の判定を解除します。 +- デプロイされているポリシーがない場合は `off` になります。`jev.json` の内容に関わらず Jev は無効です。 + +Jev ポリシーを実際に動作させる前に試すには、効果を **observe** としてデプロイします。チェックは引き続き実行され、何が行われたかはポリシーページに **would-have** として記録されますが、呼び出しをブロックすることも解除することもありません。`failproofai jev setup --mode` とダッシュボードの **Settings → Jev** スイッチには、モードが FailproofAI Cloud によって管理されていると表示され、変更はできません。`jev.json` は Cloud のチェックには使用されません。別のプロバイダーが指定されている場合も同様です。`failproofai config --disconnect` を実行すると、Jev はマシン自身の `jev.json` に戻ります。 + +`failproofai jev status` は `Jev checks run on FailproofAI Cloud (mode: enforce)` と表示されます。また、各 `both` ポリシーをレビューするチェックの名前も表示されます。フリートページには、特定のモードのマシンが問い合わせを行えない理由が表示されます。 + +- `transcripts_disabled`: マシンが `--no-transcripts` で接続されており、Jev が有効になっていません。 +- `jev_unconfigured`: マシンのキーに `jev:evaluate` が含まれていません。 +- `jev_rate_limited`: FailproofAI Cloud が組織の Jev レート制限により一部の呼び出しを拒否しており、それらの呼び出しは正規表現ポリシーのみで判定されました。 +- `jev_unavailable`: 連続して複数の呼び出しが失敗したため、マシンは FailproofAI Cloud の Jev を 1 分間スキップします。自動的に再試行します。 + +FailproofAI Cloud が 5 秒以内に応答しない場合、Jev の障害時と同様に正規表現ポリシーのみで判定します。3 回連続して失敗した後は、マシンは 1 分間ずつ問い合わせを停止します。これにより、Cloud の障害時にすべてのツール呼び出しが遅延するのを防ぎます。 + +セッションの一時停止(`failproofai config --pause`)は FailproofAI Cloud の Jev チェックを停止しません。Cloud 管理のポリシーを停止しないのと同様です。ただし、マシンにインストールされたパックの Jev チェックは一時停止されます。 + +## 動作確認 + +```bash +failproofai jev status +failproofai jev test +``` + +`status` はプロバイダーを **FailproofAI Cloud**、マシンが接続した Cloud ホスト、モード、キーのソースを **FailproofAI Cloud connection** として表示します。キー自体は表示されません。FailproofAI Cloud の `jev.json` が存在するにも関わらず Jev が実行できない場合は、その理由が表示されます。 + +| `status` の表示 | `status --json` | 意味 | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | マシンは接続されていますが、Jev キーが保存されていません。キーに `jev:evaluate` がないか、接続時に確認できませんでした。`FAILPROOFAI_CLOUD_TOKEN` にキーを設定して `failproofai config` を再実行してください。権限がない場合は **machine** キーを使用してください。 | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | このマシンには FailproofAI Cloud への接続がなく、Jev キーの帰属先がありません。 | + +`failproofai config --disconnect` 実行後は FailproofAI Cloud の `jev.json` はなくなります(オフに切り替えられたものは残ります)。そのため `status` は単純に Jev がオフと報告します。`status --json` には同じ情報が含まれます(`provider: "failproofai"`、`keySource: "cloud"`、`cloudConnected`、`keyCarriesJev`)。設定が存在しない場合や拒否された場合も同様です。`permissions` は常に `jev.json` のものです。`credentials.json` に関する拒否の場合は `credentialsPermissions` も追加され、1 つのコマンドで修正できる場合は `fix` も表示されます。`test` はライブリクエストを 1 件送信し、レイテンシと応答した Jev のバージョンを報告します。フックのタイムアウト後に応答が届いた場合(フックは `timeout` を記録)やチェックの質問に誤答した場合は、タイトルにその旨を表示してステータス 1 で終了します。 + +ダッシュボードの **Settings → Jev** パネルにも **FailproofAI Cloud connection** が表示されます。マシンが所属する組織とキーに Jev が含まれているかどうかが確認できます。ネットワーク呼び出しなしにマシン自身のファイルから読み取ります。 + +## 実際の呼び出しを確認する + +フックを接続したエージェントで新しいセッションを開始します。ファイル読み取りツールを使って `README.md` を読み、タイトルを報告するよう指示します。セッションにそのツール呼び出しが含まれていることを確認し、`failproofai jev status` を再実行します。直近の評価済み呼び出し数が増えているはずです。[ローカルダッシュボード](/ja/reference/local-dashboard#review-policy-activity)の **Policies → Activity** を開いて、その呼び出しの Jev 判定とモードを確認します。Cloud では、組織の **Policies** ページに配信済みアクティビティの Jev 結果が表示されます。observe モードでは、判定は **would-have** として記録され、ポリシーの結果が引き続き呼び出しを決定します。解除が表示されるのは、レビュー可能なポリシーがマッチし、Jev がその名前付きチェックを解除した場合のみです。 + +## ポリシーページに記録される内容 + +マシンはすでにフックアクティビティを FailproofAI Cloud に送信しています(`events:add`)。Jev が有効な場合、各ゲート済み呼び出しのレコードには、使用した評価器、Jev の判定、解除したポリシー、フォールバックした理由、レイテンシ、応答したモデルも含まれます。コマンドやプロンプトは含まれず、決定内容、コード、名前のみです。組織の **Policies** ページでは以下が確認できます。 + +- Jev 自身の判定で決定した呼び出し(enforce モード)は **Jev** に帰属します。判定チェックがパックから来た場合は、そのパック名とバージョンも記録されます。 +- observe モードでは、Jev の deny または warning は **would-have** として表示され、観察中のロールアウトの横に並びます。 +- Jev が解除したポリシー(または observe モードで解除したであろうポリシー)は、ポリシーごとにカウントされます。 +- Jev が関与した決定(ブロック、警告、解除、または observe モードの would-have)には、問い合わせた各チェックとその結論が一覧表示されます。判定、理由(`not-detected`、`exempt`、`fired`、`op-requested` など)、証拠となる `p`、`exempt` の回答、各プローブの回答が含まれます。observe(監視)としてデプロイされたポリシーのチェックも、監視済みとしてマークされて一覧に表示されます。ブロックすることはありません。Jev は散文ではなく確率で回答するため、自由記述の理由はありません。単純な allow はカウントにまとめられ、この一覧は含まれません。 + +## Jev が応答できない場合 + +以下のいずれの場合も、その呼び出しのポリシー結果にフォールバックし、理由とともに記録されます。 + +| 理由 | 原因 | +| --- | --- | +| `out-of-credits` | 組織がプランの利用枠を使い切りました。 | +| `http-401`、`http-403` | キーが失効しているか、`jev:evaluate` が含まれていません。対応するキーで再接続してください。 | +| `http-429` | FailproofAI Cloud が組織の Jev をレート制限しています。要求された待機時間(`Retry-After`、最大 60 秒)が終わるまで、マシンは何も送信せずすべての呼び出しを即座にフォールバックします。この方法で保留された呼び出しは `http-429` として記録されます。マシン自身のレート制限が先に適用された場合は `rate-limited` として記録されます。 | +| `http-429`(日次制限) | 組織の日次 Jev 呼び出し数を使い切りました。**UTC 日あたり 10,000 回**(FailproofAI Cloud の運用者が別の制限を設定している場合はその値)。カウントが 00:00 UTC にリセットされるまですべての呼び出しがフォールバックします。マシンは最大 1 分に 1 回再試行するため、リセット後 1 分以内に検出されます。`failproofai jev test` は「Daily Jev limit for this org reached; resets at 00:00 UTC.」と表示します。 | +| `http-422` | Jev がこの呼び出しのリクエストを拒否しました。通常、ツール呼び出しに Jev のトークン予算を超える密なテキスト(base64、hex、縮小コードなど)が含まれているためです。この呼び出しは毎回フォールバックします。障害ではありません。 | +| `http-502` | Jev が現在利用できません。 | +| `http-503` | この Cloud は組織の Jev を提供できません。モデルゲートウェイがない、組織がまだプロビジョニングされていない、またはゲートウェイがダウンしています。管理者に問い合わせてください。フックは最大 1 分に 1 回再試行します。 | +| `http-404` | この FailproofAI Cloud はまだ Jev を提供していません。 | +| `timeout` | `timeoutMs`(デフォルト 3000)以内に応答がありませんでした。FailproofAI Cloud がマシンの Jev モードを設定している間は、待機時間は 5000 ms となり `jev.json` の `timeoutMs` は使用されません。 | +| `model-mismatch` | バージョン 1.13 以外の Jev が応答しました。 | + +## キーの保管場所と使用先 + +- キーは `~/.failproofai/credentials.json`(`0600`、オーナーのみのディレクトリ)に 1 回だけ保存されます。他の FailproofAI Cloud 認証情報と並んで保管されます。このルートでは `jev.json` にキーは保持されません。そこにキーを書き込むと設定が無効になります。 +- `credentials.json` にオーナー以外(グループまたは他者)の読み取りまたは書き込み権限がある場合、またはそのディレクトリにオーナー以外が**書き込み**できる場合、ファイルは**拒否されて読み取られず**、修正するまで Jev はオフになります。ファイルに `chmod 600`、ディレクトリに `chmod 700` を適用してください(または再接続すると、ファイルが `0600` で書き直されディレクトリもオーナーのみになります)。他者が読み取りのみできるディレクトリは問題ありません。書き込みができるとファイルの入れ替えが可能になります。 +- キーは、同じ FailproofAI Cloud への同じキーを使ったポリシーまたはレポート用認証情報が同じファイルに存在している間のみ有効です。残されたままの Jev キー単体は無視され、Jev はオフのままです。これは古いバージョンの failproofai の `config --disconnect` が Jev キーを残したままにする場合(削除方法を知らないため)や、古いバージョンの `config --token` が別のキーで接続する場合(FailproofAI Cloud では別の組織のキーになる可能性があります)に発生します。Jev を再度オンにするには、**machine** キーで再接続してください。 +- キーは検証された Cloud オリジンにのみ送信されます。別の場所を指す `jev.json` は拒否されます。 +- **マシン上のエージェントはキーを読み取ることができます。** `credentials.json` はオーナーのみがアクセスできますが、エージェントはそのオーナーとして実行されます。failproofai 自身のファイルの読み取りは意図的に許可されています(変更のみが `block-failproofai-commands` でブロックされます)。そのため、エージェントとこのファイルの間にあるのは `block-read-outside-cwd`(レビュー可能なポリシー)のみです。ホームディレクトリで開始したセッションからは、実質的に何もブロックするものがありません。`jev:evaluate` を持つキーは、使用される場所を問わず組織の Jev 利用枠(日次上限まで)を消費します。そのため、マシンキーは他の支出認証情報と同様に扱ってください。エージェントがキーを読み取った可能性がある場合は、Keys ページで無効化し、新しいキーで再接続してください。 +- これはグローバルファイルのみで制御されます。リポジトリが Cloud Jev を有効にしたり、別の場所に向けたり、キーを提供したりすることはできません。また、このルートでは `FAILPROOFAI_JEV_API_KEY` は無視されます。 +- Jev が評価する各呼び出しに対して、1 つのリクエストが FailproofAI Cloud に送信されます。内容は[独自キーページ](/ja/reference/jev-providers#what-leaves-the-machine)に記載されているものです(シークレットは編集済み)。FailproofAI Cloud はそれを TypeSafe に転送し、ログへの記録や保持は行いません。 + +## 無効にする + +接続済みのマシンでは、FailproofAI Cloud がそのマシンに Jev ポリシーをデプロイしていない場合に Jev がオフになります。そこにある Jev ポリシーを削除またはアーカイブしてください。 + +| コマンド | 結果 | +| --- | --- | +| FailproofAI Cloud でマシンの Jev ポリシーを削除する | 次のポーリング(約 30 秒)で Cloud のモードが `off` になります。`jev.json` の内容に関わらず Jev は完全に無効になります。 | +| `failproofai config --disconnect` | マシンを切断します。キーが削除され、`jev.json` が FailproofAI Cloud を指定しておりオフに切り替えられていない場合は `jev.json` も削除されます。独自エンドポイント用の `jev.json` は残ります。 | + +次のツール呼び出しから、フックはこれまでどおり正規表現ポリシーのみを実行します。 \ No newline at end of file diff --git a/docs/ja/reference/jev-evaluations.mdx b/docs/ja/reference/jev-evaluations.mdx new file mode 100644 index 000000000..a73363f76 --- /dev/null +++ b/docs/ja/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev評価リファレンス" +description: "Jevセッション評価における質問タイプ・キャリブレーションスコア・制限・バックフィルについて。" +icon: "list-checks" +--- + +このページでは、[Jev評価](/ja/evaluations/jev)の背後にある質問の形式とスコアリングルールを説明します。質問によっては、会話を*読む*だけでよく、*書く*必要はありません。「顧客は緊急性を示しましたか?」には2つの答えがあります。「どれほど不満を感じていましたか?」には、順序のある少数の答えがあります。質問する前からすべての答えがわかっているのです。 + +**分類器評価**は、まさにそのようなケースに使います。質問と取りうる答えを記述すると、分類専用の小型モデルがキャリブレーションされた数値を返します——自由記述は一切ありません。 + + +ジャッジと同様に、分類器評価はセッションごとにモデル呼び出しのコストが発生します。ジャッジと異なるのは、汎用モデルではなく小型の単一目的モデルを使うため、高速かつ低コストである点です——ただし、自己説明は行いません。推論が必要な場合は[ジャッジ](/ja/evaluations/judge)をご利用ください。 + + +## どれを使えばよいか? + +| 質問 | 方法 | +| --- | --- | +| ツール呼び出しは何回あったか? | コード | +| セッションは30秒未満だったか? | コード | +| 顧客は緊急性を示したか? | **分類器** | +| 担当チームはどこか:請求、技術、営業? | **分類器** | +| 顧客はどれほど不満を感じていたか? | **分類器** | +| 回答は実際に正しかったか? | **ジャッジ** | +| エスカレーションポリシーに従っていたか、またその理由は? | **ジャッジ** | + +大まかな基準:**数えられるもの→コード、列挙できる答え→分類器、説明が必要→ジャッジ**。 + +あらかじめ決める必要はありません。測定したいことを説明すると、アシスタントが選択肢を選び、どれを選んだか・その理由を教えてくれます。変更も可能です。 + +## 2種類の質問タイプ + +### `noul` — これは真か? + +2つの答えがあり、両方を説明します。結果は「真」の説明が当てはまる確率です: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +両面を説明してください。「緊急性は示されていない」も立派な答えであり、明示することで反対側の定義が明確になります。 + +### `score` — どれほどか? + +順序付きのルーブリックで、**最低レベルを先頭に**記述します。結果はセッションがどこに位置するかを0〜1にスケーリングしたものです: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**ルーブリックは3〜5レベルで、すべて異なる内容にする必要があります。** 両方の制限は文体上の好みではなく、測定に基づくものです: + +- **2レベル**では`noul`が既により適切に処理できることと同じになってしまい、**5レベル超**にするとモデルが断定を避けて中間に集中するようになります。同じ質問を同じセッションに対してスコアリングした結果、2レベルで0.00、3レベルで0.01、10レベルで0.55となりました。 +- **重複したレベル**は答えを任意に分散させます。明らかに怒りを示したセッションが`["Calm", "Frustrated", "Very angry"]`に対しては1.00を記録しましたが、`["Angry", "Angry", "Angry"]`に対しては0.66——形式上は正しい数値ですが、意味をなしません。 + +順序のないカテゴリ——「請求、技術、営業」——はルーブリックではありません。カテゴリごとに`noul`として質問するか、ジャッジを使用してください。 + +## 結果の読み方 + +分類器はジャッジと同様に0〜1の**スコア**を生成するため、チャート表示、フィルタリング、アラートのトリガーも同じ方法で行えます。2点だけ違いがあります: + +- **推論は提供されません。** このフィールドは意図的に空白です。このモデルは自己説明を行わず、説明を作成することは機能ではなく捏造になります。 +- **不確実性にはラベルが付きます。** `score`質問は自身の信頼度を報告し、モデルが確信を持てなかった結果には`low_confidence`タグが付きます——「人間が確認すべきもの」はフィルタで特定できます。`noul`質問は信頼度を報告しないため、タグは付きません。 + +非常に長いセッションは抜粋して読み取り、結合されます。セッションが全体を読み取るには長すぎる場合、結果には省略されたターン数が表示されます——一部のセッションに基づく判断が全体に基づくものとして提示されることはありません。 + +## 制限 + +- **ルーブリックは3〜5レベルで、すべて異なる内容にする。** 上記参照。両方の境界は作成時に適用されます。 +- **1つの評価につき質問は1つ。** 2つのことを尋ねる場合は2つの評価になります——これはチャート上でも望ましい形です。 +- **質問を編集すると新しいバージョンが公開されます。** 旧スコアと新スコアは比較できないため、1つのトレンドラインに混在させず、分けて管理されます。 +- **分類器は常にスコアを生成します**——メトリクスやアサーションではありません。 +- **推論なし**、上記のとおり。数値を見て「なぜ?」と問われる可能性がある場合は、代わりにジャッジを作成してください。 + +## テストとバックフィル + +ジャッジとは異なり、分類器評価はデプロイ前に**テストが可能です**——コード評価と同じ方法で実際のセッションに対して[テスト](/ja/evaluations/test)を実行し、本番公開前にスコアを確認できます。 + +また、既存のセッションに対して[バックフィル](/ja/evaluations/deploy#score-sessions-you-already-have)することもできます。セッションごとにモデル呼び出しのコストが発生するため、すべてを再実行するのではなく、対象ウィンドウを意図的に絞り込んでください。 \ No newline at end of file diff --git a/docs/ja/reference/jev-intent.mdx b/docs/ja/reference/jev-intent.mdx new file mode 100644 index 000000000..b8eda6b21 --- /dev/null +++ b/docs/ja/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev インテントキャプチャ" +description: "どのハーネスイベントが Jev エバリュエーターに人間の要求を伝えるか、テキストを格納するフィールド、カウントされないもの、ハーネスが配信するプロンプトを信頼することのリスク。" +icon: "message-square-quote" +--- + +[Jev ポリシーレビュー](/ja/policies/jev)を設定すると、エバリュエーターはゲートされた各ツール呼び出しを、ハーネスがエージェントに提示したテキストではなく、**人間が要求した内容**と照らし合わせて判断します。「はい、強制プッシュしてください」のような返答で **reviewable** ポリシーをクリアできるのはそのためです。これはエバリュエーターの核心であり、要求を読み取れない正規表現では実際の作業の3分の1をブロックしてしまいます。 + +そのテキストは一箇所から来ます: **ハーネス自身がプロンプト送信イベント時にフックに渡すプロンプト**です。Failproof AI は人間が入力した部分(ハーネスのラッピングを除去し、シークレットを編集し、上限を設けた上で)を、自身のステートディレクトリ配下の `0600` ファイルに記録します。ディスク上の内容は参照されません。セッション・トランスクリプトはエージェントが1コマンドで書き換え可能なファイルであるため、プロンプトの作成者を問い合わせることは一切ありません。 + +## このアプローチが受け入れるリスク + +コマンドを実行できるエージェントは、ハーネスにプロンプトを送信させることができます。`claude -p "…"`、`codex exec`、`copilot -p`、`cursor-agent -p`、`devin -p`、`droid -p`、`goose run -t`、`pi -p` はいずれも、エージェントが制御する子セッションにおいて、人間が入力した場合と同じプロンプト送信イベントを同じペイロードで発火させます。また、Failproof AI 自身のフックバイナリを実行して、自ら作成したペイロードを渡すこともできます。Failproof AI の内部からはいずれも本物との区別がつきません。どちらも同じプログラムが同じ stdin を読み取っているためです。 + +**つまり、シェルを持つエージェントは自分自身のコンセントを偽造できます。** これは 2026-09-23 に意図的に行われたトレードオフであり、その両面は以下の通りです: + +- **得られるもの。** 代替案は実装・計測済みです: ハーネスが人間をプロンプトの作成者として明示するフィールドを必須とし、それがない場合は何も記録しないというものです。しかし、そのようなフィールドを送信する既存ハーネスは存在しないため、このバージョンでは**すべてのハーネスで何も記録されませんでした**。Jev はインテントなしですべての呼び出しを判断し、ポリシーをクリアできませんでした。発火しないキャプチャは安全な製品ではなく、製品として機能しません。 +- **できないこと。** 記録されたプロンプトは、**reviewable** とマークされたポリシーのみをクリアできます。**hard** ポリシーは Jev の判断によって決してクリアされないため、偽造されたプロンプトがハードな deny を allow に変えることは不可能です。また、フックをスキップしてもエージェントには何の利益もありません。ハーネスはツール呼び出しに対して独立して Failproof AI を呼び出すためです。 +- **最悪の場合できること。** 最悪のケースは、15の reviewable 組み込みポリシーのうちの1つをクリアすることですが、**そのうち12はブロック**です。`protect-env-vars`、`block-env-files`、`block-read-outside-cwd`、`block-rm-rf`、`block-force-push`、`block-secrets-write`、および6つのインフラ CLI ブロック(`block-kubectl`、`block-terraform`、`block-aws-cli`、`block-gcloud`、`block-az-cli`、`block-helm`)はすべて deny です。そのため、偽造されたコンセントにより、環境シークレットの表示、`.env` ファイルの読み取り、プロジェクト外の読み取り、`rm -rf`、強制プッシュ、シークレットファイルへの書き込み、またはライブインフラの変更において、実際の deny が allow に変わる可能性があります。`warn-git-amend`、`warn-destructive-sql`、`warn-global-package-install` のみが警告です。デフォルトインストールでは12のうち2つ(`protect-env-vars` と `block-env-files`)が有効で、残り10は誰かが有効化したマシンにのみ影響します。どのプロンプトもリーチできないのは、すべての hard なもの(block-sudo、`block-curl-pipe-sh`、`block-push-master`、`block-work-on-main`、エージェントが Failproof AI を無効化するのを止めるガード、および reviewable とマークされていないその他の組み込みポリシー)です。[ポリシー権限](/ja/policies/authority)では15すべてとその審査方法を一覧で確認できます。 + +依然として拒否されるのは、安価にチェックでき、エージェントが単に要求するだけでは取得できないもの全てです: ハーネス自身のペイロードがマシン送信済みとしてマークしたターン、サブエージェントを指定するペイロード、プレーンな名前でないセッション ID、プロンプト送信以外のイベント、そしてハーネスのラッピングのみのテキスト(複数のハーネスが次のユーザーターンとして返す Failproof AI 自身のストップゲートワードを含む)。 + +## ハーネス別テーブル + +「テキストフィールド」は Failproof AI のハーネスごとの正規化後の stdin ペイロードフィールドです。「記録済み」はプロンプトが人間のリクエストとして保存されるかどうかを示します。 + +| ハーネス | `--cli` | プロンプトイベント → 正規化 | テキストフィールド | 記録済み | エージェントの最終メッセージの読み取り元 | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | あり。ただしペイロードの `source` が誰も送信していないターンを示す場合(`loop_wakeup`、`schedule_wakeup`、`poll_event`、`system`)を除く。`user`、`sdk`、不明な値、および `source` を送信しないビルドはすべて記録される | セッション・トランスクリプト(`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | あり | ロールアウト JSONL (`agent_message`、`AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | あり | `events.jsonl`(`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | あり。プロンプト全体が `` ラッパーの場合はそれを除去 | エージェントトランスクリプト JSONL | +| OpenCode | `opencode` | `message.updated`(user ロール) → `UserPromptSubmit` | `prompt` | あり。ただし現在の OpenCode はそのイベントにテキストを含まないため、実際には何も記録されない。同一メッセージの繰り返しは1回のみ記録 | なし(セッションは SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | あり。ただし `input_source` が `extension` の場合を除く。別の拡張機能の `sendUserMessage()` であり、そのテキストはモデルが生成したもの、またはリポジトリ由来の可能性がある | Pi セッション JSONL | +| Hermes | `hermes` | なし | — | なし — Hermes にはプロンプト送信イベントが存在しない | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | あり。ただし実行メタデータが機械実行を示す場合を除く: `user` 以外の `trigger`、`external_user` 以外の `inputProvenance.kind`、または `senderIsOwner: false` | なし(`before_agent_run` にはトランスクリプトパスが含まれない) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | あり | ドロイドセッション JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | あり | なし(セッションは SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | なし | なし — `PreInvocation` はターン内の*すべての*モデル呼び出し前に発火し、プロンプトテキストを含まない | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | あり | なし(セッションは SQLite) | + +2つのハーネスは何も記録しませんが、いずれも同じ理由です: イベントに人間のテキストが含まれていません。Hermes にはプロンプト送信イベントがありません。ネイティブプラグインが `pre_llm_call` を自ら処理し、ツール、セッション、サブエージェントイベントのみを転送します。Antigravity の `PreInvocation` は、人間のターンとその後の5つのモデル呼び出し前すべてで発火し、プロンプトフィールドを含みません。フックは同じ会話に `userMessage` ステップを注入することもできます。どちらのイベントにも記録すべきものがありません。 + +## プロンプトを人間のものとみなす条件 + +1. **イベント。** Failproof AI がハーネスのプロンプト送信イベントに対して呼び出され、ハンドラーがそれを `UserPromptSubmit` に正規化する。 +2. **ペイロード。** ハーネスがフックの stdin に書き込み、上記のフィールドにテキストが含まれている。ペイロードなしで Failproof AI に到達した呼び出しは何も記録しない。 +3. **ペイロード内のどの要素もターンを除外しない。** サブエージェント(`agent_id`)を指定するペイロードは、エージェントが自身にプロンプトを送っている。マシン送信ターンを示す `source`、`input_source`、または OpenClaw の実行マーカーは拒否される。**不在の**マーカーは何も除外しない。これが何も記録しなかったバージョンとの違いです。ここに挙げる各マーカーは、すべての既存ビルドで不在です。 +4. **ラッピングを除去した後に何かが残る**(下記参照)。 + +**セッション・トランスクリプトはプロンプトの作成者の証拠にはなりません。** このページの以前のバージョンではトランスクリプトのクロスチェックが記述されていました: トランスクリプトがモデルによるスケジュール設定を示した場合はプロンプトを拒否し、前のプロンプトが参照したトランスクリプトを継続している必要がある、というものでした。そのチェックは廃止されました。トランスクリプトはエージェントがすでにシェルを持つファイルであり、切り詰め、置換、読み取りバジェットを超えたパディング、ターン開始時のスナップショットと終了時の復元、エージェントが記述したエントリによる修正が可能です。毎回の強化の後、同じ偽造の別の方法が出現したため、修正ではなく仕組み全体を削除しました。 + +トランスクリプトを読み取るのは1つのことだけです: **エージェントの最後の表示メッセージ**。そのメッセージはエージェントが書いたものであることが明確であり、Jev にはその旨が伝えられます。それ単独でコンセントになることはありません。 + +## プロンプトから保持される内容 + +ハーネスはプロンプトに人間の言葉以上のものを含めます。保存前に以下の処理が行われます: + +- `` ブロックは除去され、周囲の人間の言葉は保持されます。 +- セッション継続サマリー(「このセッションは以前の会話から継続されています…」)は完全に削除されます。 +- タスク通知、ローカルコマンド出力、割り込みマーカーは完全に削除されます。 +- 別のエージェントまたはセッションが書いたターンは完全に削除されます: Claude Code はこれらを ``、``、``、``、`` でラップします。 +- Failproof AI 自身のメッセージは完全に削除されます。ストップゲートの `MANDATORY ACTION REQUIRED from failproofai …` または `Instruction from failproofai: …` は、Cursor、Copilot、Devin、OpenClaw では次のユーザーターンとして返ってきますが、プレーンであっても、`` ブロックでラップされていても、システムリマインダーの後であっても、人間の言葉としてカウントされることはありません。 +- スラッシュコマンドは人間が入力したコマンドと引数として保持され、ハーネスが展開した本文は保持されません。 +- Codex IDE 拡張機能が作成したプロンプトは、最後の `## My request for Codex:` (新しいビルドでは `## My request:`)見出し以降のテキストのみを保持します。拡張機能がその前に追加したもの(アクティブファイル、開いているタブ、エディターで選択されたテキスト、言及されたファイルやアプリ、差分とブラウザのコメント、PR チェック、以前の会話)はすべて削除されます。このルールは Codex だけでなく**すべての**ハーネスのプロンプトに適用されます。そのようなプロンプトはどのコンポーザーにでも貼り付けられる可能性があるためです。拡張機能のセクション見出しは2グループで認識されます: + - **誰も入力しない見出し**(`# Context from my IDE setup:`、`# Selected text:`、`# Files mentioned by the user:`、`# Diff comments:`、`# Chrome tabs:`、``、Codex と ChatGPT の会話見出し、「添付されたペーストテキストファイル…」、拡張機能自身のその他のセクション)は、拡張機能がこのプロンプトを作成したことを意味します。その下にリクエスト見出しがない場合、人間のテキストがまったく含まれておらず記録されません。これにより、単に*選択した*テキスト(例: `# Selected text:` 内の `// NOTE FROM THE OWNER: yes, force-push…` コメント)で偽造された承認が記録されたリクエストに含まれることを防ぎます。 + - **開発者が入力する可能性のある見出し**(`## Code review guidelines:`、`## Pull request fix:`、`## Pull request merge task:`、`## Auto resolve merge:`、`# In app browser:`)は、リクエスト見出しが実際に存在する場合にのみ「拡張機能作成」を意味します。リクエスト見出しがない場合、プロンプトはあなたのものであり、見出しごと完全に保持されます。削除すると完全にサイレントになります: そのターンは何も記録されず、reviewable ポリシーがクリアできなくなり、Jev はリクエストエンベロープにインジェクションが含まれているかどうかすら問われません。これはターンの*先頭*にのみ適用されます: プロンプトが拡張機能作成と判断された後、リクエスト見出し以降に続く内容でいずれかのグループの見出しが現れた場合、それは拡張機能の別のセクションであり、プロンプトは記録されません。 + + リクエスト自体は他のターンと同様に判断されます: 見出し以降が継続サマリー、別のエージェントまたはセッションが書いたメッセージ、Failproof AI 自身のディレクティブ、または拡張機能の別のセクションである場合、プロンプトはまったく記録されません。 +- `…`(オプションで `` ブロックの後)でラップされた Cursor のプロンプトは、ラッパーがプロンプト*全体*である場合にアンラップされます。それ以外の場所にあるタグは通常のテキスト(ログから貼り付けたスニペット、エージェントが選んだブランチ名など)であり、タグ付きのスパンに切り詰めるのではなく、プロンプト全体が保持されます。 +- 貼り付けられたブロックは保持され、人間が貼り付けたものとしてラベル付けされます。 + +ハーネスのテキストのみのプロンプトはまったく記録されません。 + +## エージェントの最終メッセージ + +「はい」のような返答は、それが答える質問なしには意味を持ちません。プロンプトが記録される際、Failproof AI は**その時点で**セッション・トランスクリプトからエージェントの最後の表示メッセージを読み取り、プロンプトと共に保存します。Jev はそれを専用のフィールドで受け取り、エージェントが書いたものとしてラベル付けされます。これにより短い返答の意味を説明でき、単独で人間のリクエストとしてカウントされることはありません。これはトランスクリプトが読み取られる唯一の目的であり、書き換えられたトランスクリプトが最悪できることは、エージェントが書いたメッセージがあるべき場所にエージェントが書いたメッセージを置くことだけです。 + +トランスクリプトの末尾から最大4 MB を読み取ります。対応するトランスクリプト形式は Claude Code、Codex ロールアウト(古い `agent_message` イベントと新しい `AgentMessage` アイテム)、Cursor、Copilot の `events.jsonl`、Pi、Factory、OpenClaw のセッション JSONL です。Claude Code 自身の合成メッセージ、API エラーメッセージ、サブエージェント(サイドチェーン)メッセージはスキップされます。セッションを SQLite で管理する Goose と OpenCode、トランスクリプトが単一の JSON ドキュメントである Devin、`before_agent_run` イベントにトランスクリプトパスが含まれない OpenClaw にはスナップショットがありません。 + +## ストレージ + +| プロパティ | 値 | +| --- | --- | +| 場所 | `~/.failproofai/state/semantic/sessions//.json`。`` はプロンプトが入力されたエージェントプロファイル: FailproofAI が認識するエージェントの場合は `.`(Cloud ポリシーがターゲットとするアイデンティティ)、それ以外は `` のみ | +| パーミッション | ファイル `0600`、ディレクトリ `0700`。その上の `~/.failproofai` までの各ディレクトリも同じルールに従います。他のユーザーが**書き込み**できるディレクトリは名前変更して置き換えられる可能性があるため、読み取りパスは可能な限り書き込みビットを除去し、除去できない場合は**何も読み取りません**。記録されたプロンプトはその場合、偽造されるのではなく不在となり、何もクリアされません | +| セッションごとの保持数 | 最後の5プロンプト。直前のプロンプトと同一のプロンプトは新しいスロットを取らずに置き換えられます | +| ウィンドウ | 6時間より古いプロンプトは無視されます | +| サイズ | 各プロンプトとエージェントメッセージは先頭と末尾を保持しつつ6,000文字に制限されます | +| シークレット | 書き込み前に `sanitize-*` ポリシーと同じパターンで編集されます。48,000文字を超えるテキストは最初の28,800文字と最後の19,200文字として編集され、シークレットが分割されている可能性がある切り取り箇所の隣接テキストは保存されません | + +文字、数字、`.`、`_`、`-` 以外の文字を含む、または128文字を超えるセッション ID はファイル名として使用されないため、それらのセッションには何も記録されません。 + +セッションファイルはプロンプトが記録されてはじめて作成されます。保持するのはプロンプトのみであり、オリジン状態もトランスクリプトマークも含まれません。6時間ウィンドウを超えてサイレントになった場合、次の新しいセッションが最初のプロンプトを書き込む際に削除されます。 + +プロンプトは、記録された際と同じエージェントプロファイルおよびセッション ID でのみ読み取られます。セッション ID はエージェントから来るため、2つのプロファイルが同じ ID を使用する可能性があります。プロファイルでキーイングすることで、あるプロファイルの言葉が別のプロファイルのリクエストとしてカウントされることを防ぎます。このレイアウト以前のファイル(`sessions/.json`)はどのプロファイルが書いたかを示せないため、読み取られることなく6時間ウィンドウで期限切れになります。 + +Jev エンドポイントが設定されていない限り、何も記録されません。FailproofAI Cloud Jev モードでは、Cloud Jev チェックが割り当てられておらず、インストール済みパックのチェックも審査しないエージェントプロファイルについては何も記録されません。 + +### プロジェクトルート + +「プロジェクト内」(つまり `read-outside-workspace` やその他のパスチェックが判断する基準)とは、セッションの**最初のレビュー済み呼び出し**時点でのプロジェクト内を意味します。ルートはその時点で固定され、以降の `cd` によって移動しません。ただし `cd` は相対パスの解決方法を変更します。`cd` に追随させると、あるコマンドでの `cd ~/.ssh` が次のコマンドのプロジェクトを `~/.ssh` にしてしまいます。 + +ピンは `~/.failproofai/state/semantic/roots/.json` であり、`{root, at}` を保持します。ファイルは `0600`、ディレクトリは `0700` で、上記と同じセッション ID ルールが適用されます。7日以上古いファイルは新しいセッションがルートをピンする際に削除されます。他のユーザーが書き込めるディレクトリ内の `roots` は無視され、代わりにライブディレクトリのルートが使用されます。セッションを再ピンするには、そのファイルを削除します。 + +## 既知の制限 + +- **プロンプトの信頼性はフック呼び出しの信頼性に依存します。** ここに記載されているすべての処理は、ハーネスがフックの stdin に書き込んだペイロードを読み取ります。コマンドを実行できるエージェントは、ハーネスをヘッドレスで実行する(`claude -p` および上記の7つのコマンド)か、Failproof AI 自身のフックバイナリを作成したペイロードで実行することができ、誰も入力していないプロンプトを記録できます。これはページ上部で説明したトレードオフです: reviewable ポリシーのみクリアでき、hard ポリシーは決してクリアできません。ただし、reviewable な組み込みポリシーの15のうち12は deny であるため、偽造されたプロンプトによってその12のポリシーで実際のブロックが allow に変わる可能性があります。 +- **サブエージェント検出は Claude の形式に依存しています。** `agent_id` を含むペイロードは、どのハーネスでも記録されません。これは Claude Code、Factory Droid、Devin が使用するフィールドです。Codex はサブエージェントスレッド内でプロンプトイベントを発火させ、Copilot はインプロセスのサイドキックを実行し、Goose は `delegate` ツールを持ち、OpenClaw はペルソナを実行しますが、いずれもペイロードにこれが認識できる形でマークされないため、それらのハーネスのサブエージェントプロンプトはセッション自身のものとして記録されます。OpenClaw の `openclaw.agentId` はそのマークでは**ありません**: 出荷済みプラグインはすべての実行(オーナーのものを含む)でこれを設定します。 +- **マーカーを含まないスケジューラー。** Claude Code の `schedule_wakeup` と `loop_wakeup`、および OpenClaw の `cron` と `heartbeat` トリガーは、それらのハーネスがペイロードでそう示しているため拒否されます。Goose 自身のスケジューラー(`goose schedule add`)と Codex の `codex exec` は何も示さないため、それらが開始した実行は他と同様に記録されます。 +- **エージェントの最終メッセージは、エージェントが選んだメッセージである可能性があります。** トランスクリプトは認証されていないため、自身のトランスクリプトを書くエージェントは「最終メッセージ」の内容を決定できます。エージェントが書いたものとしてラベル付けされ、それ単独では何もクリアしません。ただし、`decide.ts` の v1 パスでは確定的な「ユーザーがこのターゲットを指定したか」チェックを満たすことができるため、トランスクリプトを制御するエージェントは、オーバーライドが必要とするターゲット名を提供できることに注意してください。 +- **拡張機能のマシン見出しで始まるプロンプトは全体が削除されます。** `# Selected text:`、`# Diff comments:`、`# Chrome tabs:` または上記の第1グループのセクション見出しでプロンプトを始め、`## My request:` 見出しを書かなかった場合、そのターンには何も記録されず、クリアされるものもありません。これは意図的です: これらのセクションには他の誰かが制御するテキスト(選択したコード、レビュアーの差分コメント、ページタイトル)が含まれており、それをあなたの言葉として記録する方が問題です。開発者が入力する可能性のある見出しは第2グループにあり、それ単独でプロンプトを削除することはありません。 +- **OpenCode は実際には何も記録しません。** 現在の OpenCode では `message.updated` イベントにテキストが含まれておらず、タスクツールが作成する子セッションでも発火します。その子セッションの「ユーザー」メッセージは親エージェントが書いたものです。 +- **`CODEX_HOME` は** `lib/codex-sessions.ts` のロールアウト検出では**考慮されません**。これはエージェントメッセージのスナップショットを探す場所のみに影響し、プロンプトが記録されるかどうかには影響しません。 \ No newline at end of file diff --git a/docs/ja/reference/jev-providers.mdx b/docs/ja/reference/jev-providers.mdx new file mode 100644 index 000000000..e068688fc --- /dev/null +++ b/docs/ja/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jevプロバイダーと自己キー設定" +description: "ライブJevポリシーレビューを自分のキーで利用するためのプロバイダーエンドポイント、モデルID、設定、および障害時の動作。" +icon: "key-round" +--- + +これは[Jevポリシー](/ja/policies/jev)を自分のキーで使用するためのプロバイダーおよび設定リファレンスです。正規表現ポリシーは文字列を照合します。しかし、あなたが意図して実行した`rm -rf build/`と、プランに紛れ込んだ`rm -rf ~`を区別することはできません。そのため、ある箇所では過剰にブロックし、別の箇所では不十分なブロックになってしまいます。TypeSafeの分類器である**Jev**は、あなたが実際に何を求めたかを踏まえてその呼び出しを読み取り、1回の高速リクエストで一連のyes/no形式の質問に答えます。 + +Jevのエンドポイントとキーを設定すると、Failproof AIは各ツール呼び出しについてJevに問い合わせますが、これは正規表現ポリシーの**代わりではなく、並行して**行われます。 + +- **ハード**ポリシーのdenyは最終的なものです。Jevはそれを解除できません。ポリシーは、明示的にreviewable(レビュー可能)とマークされ、対象とするJevチェックを指定していない限り、すべてハードです。つまり、何も記述していないカスタム・パック・クラウドポリシーはハードであり、常時有効な自己保護ガードは常にハードです。 +- **reviewable**ポリシーのdenyは解除される場合がありますが、そのポリシーが対象とする懸念について正確にJevに問い合わせが行われ、Jevが「問題なし」または「ユーザーがこれを要求した」と回答した場合に限ります。ユーザーがその呼び出しを要求していない場合に懸念が実在すると判断されたチェックは、たとえ単独の判定が警告にとどまっても、denyを維持します。これはツール呼び出し前において警告がエージェントを停止させないためです。また、そのチェックがdenyを発行できるもの(シークレット露出、認証情報の漏洩、破壊的削除など)である場合、その呼び出しに対して何も解除されません。 +- ブロックが**警告**に変わる場合があります。その呼び出しがあなたが与えたタスクのステップであり、それ以上の範囲に及ばない場合、JevはdenyをWarningに軟化させ、その警告(呼び出しの何が問題かを具体的に示す)がポリシーのブロックに置き換わります。 +- Jevは正規表現では表現できない有害な動作に対して、単独でwarningまたはdenyを発行することもできます。 +- Jevが回答できない場合(タイムアウト、レート制限、サーバーエラー、クレジット不足、想定外のモデルバージョン)、その呼び出しはJevなしの場合とまったく同じ正規表現の結果を受け取ります。 +- Jevが呼び出し全体を読み取り、かつ対象の懸念について正確に問い合わせが行われていない限り、JevはあなたのポリシーよりもPermissive(許可的)な状態にすることはありません。条件を満たさない場合(呼び出しが大きすぎて全体を送信できない、インジェクションが疑われるなど)は、クリアランスが取り消され、すべてのdenyが維持されます。 + + +Jevの設定がなければ何も変わりません。フックは従来どおり正確に正規表現ポリシーを実行します。設定すること自体がオプトインです。 + + + +FailproofAI Cloudをお使いですか?自分のキーは不要です。`jev:evaluate`権限を持つキーで接続されたマシンは、組織のプランでJevを利用できます。[FailproofAI Cloud経由のJev](/ja/reference/jev-cloud)をご覧ください。 + + +## 始める前に + +**failproofai 1.0.8-beta.0以降**をインストールし、エージェントが動作するマシン上の[対応ハーネス](/ja/reference/harnesses)にフックをアタッチしてください。新しいマシンの場合は[クイックスタート](/ja/start/quickstart)に従い、Cloudを使用しない場合は[ローカル適用のセットアップ](/ja/start/setup#enforce-locally)を参照してください。インストール済みのCLIは`failproofai --version`で確認できます。 + +以下のプロバイダーからAPIキーを取得するか、互換性のあるエンドポイントとそのキーを用意してください。Jevは`PreToolUse`または`PermissionRequest`ゲートで名前付きツール呼び出しをレビューします。独自の判定を発行することもできますが、既存のポリシーdenyを解除するには、[reviewable](/ja/policies/authority)としてマークされたポリシーがインストールされている必要があります。ハードポリシーのdenyは最終的なままです。 + +## プロバイダーを選ぶ + +Jevは5つのルートで利用できます。そのうちの1つのキーを用意してください。 + +| プロバイダー | `--provider` | エンドポイント | デフォルトモデル | 備考 | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | 厳密なバージョン固定。 | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | リクエストはデータ保持なしのエンドポイントにのみルーティングされ、他のプロバイダーへのフォールバックはありません。`typesafe/jev-1.13-20260917`のような日付入りのバージョンとして報告されます。 | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Jevをエイリアスのみで識別するため、応答したバージョンは未検証として記録されます。 | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id`が必要です。キーあたり1秒あたり約6リクエストで、HTTP 429が発生することが確認されています。 | +| 独自エンドポイント | `custom` | `/systemone` | `jev-1.13.0` | TypeSafeのリクエストボディを受け付け、どのモデルが応答したかを報告するエンドポイント。`https`のみ。ローカルテスト用にはループバックホスト(`localhost`、`127.0.0.1`、`::1`)への平文`http`も受け付けられます。 | + + +Vercelの独自ブリング・ユア・オウン・キー機能では、リクエストが失敗すると無音でVercelの認証情報を使って再試行されます。すべての呼び出しを自分のTypeSafeアカウントにのみ課金・記録したい場合は、TypeSafeを直接使用してください。 + + +## セットアップ + +1つのコマンドで、エンドポイントとキーを設定します。既存のポリシーが引き続き呼び出しを判断しながらJevの判定を検査できるよう、まず`observe`モードで開始しましょう。 + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### URLがプロバイダーを決定する + +プロバイダーを明示的に指定する必要はありません。URLの**ホスト**がプロバイダーを識別します。 + +| URLホスト | プロバイダー | その他の必要事項 | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| その他のホスト | `custom` | — 指定したURLがベースURLとなります | + +これから3つのことが導かれます。 + +- **プロバイダー自身のAPIのURLを指定した場合、オーバーライドは書き込まれません。** `--url https://api.typesafe.ai/v1`は`--provider typesafe`と同じ設定を生成します。既知のプロバイダーで異なるパスまたはホストを指定すると、`--base-url`が格納するのと同様に、ベースURLとして保存されます。 +- **`--provider`は推論をオーバーライドします。** これにより、独自のホストからプロバイダーのAPIを話すプロキシに接続できます(例:`--url https://jev-proxy.internal/v1 --provider typesafe`)。 +- **ホストと矛盾する`--provider`は拒否されます。** `--provider openrouter --url https://api.typesafe.ai/v1`は何も書き込まず、理由を説明します。2つの指定がキーの送信先について矛盾しているからです。同様の組み合わせは`jev setup --base-url`やダッシュボードのJev設定からも拒否されます(`--provider custom`は矛盾ではありません。これは「このURLをそのまま使う」という意味です。ただし、Cloudflareのホストは例外で、カスタムルートではアカウント単位のエンドポイントに到達できません)。 + +`--url`は設定ファイルの`baseUrl`と同じ検証が行われ、同じメッセージで拒否されます。`https`、またはいずれのモードでもループバックホスト(`localhost`、`127.0.0.1`、`::1`)への平文`http`が受け付けられます。リスク:ループバックサーバーは認証されないため、停止中に別のローカルプロセスがそのポートを取得して応答する可能性があります。ローカルテスト以外では`https`を使用してください。 + +### キー + +`--key-stdin`でパイプ入力するか、ターミナルでコマンドをそれなしで実行してマスクされたプロンプトでキーを貼り付けてください。どちらの方法でもキーは設定ファイルに直接保存され、表示されることはありません。 + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup`は同じフラグを受け付け、すべての詳細な設定が可能です。URLではなくプロバイダーを指定したい場合は`setup --provider `を使用してください。 + +### `--token`とそのコスト + +`--token `はコマンドラインにキーを配置します。これはマシンを設定する最も速い方法ですが、設定ファイル以外の場所にキーが残る唯一の書き方です。 + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +コマンドライン引数はシェルの履歴ファイルに残り、コマンド実行中はプロセスリストに表示されます。`/proc`からあなたと同じユーザーで実行しているプロセスが読み取れます。`--token`を使用するたびに`setup`がその旨を通知します。共有マシン、記録されたセッション、または履歴ファイルが同期される環境では`--key-stdin`を優先してください。この方法でキーを渡した場合は、必要に応じてローテーションしてください。 + + +`--token`、`--key-stdin`、`--key-from-env`は相互に排他的です。1つだけ指定してください。 + +その後、キー、エンドポイント、および応答したJevを確認するために小さなライブリクエストを送信します。 + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test`は、タイムアウト後に応答が届いた場合(すべてのフックが`timeout`として正規表現にフォールバックする)やチェック質問への回答が誤っている場合、タイトルにその旨を示して終了コード1で終了します。 + +フックはツール呼び出しのたびに設定を読み込むため、次の呼び出しから反映されます。デーモンの有無にかかわらず、再起動は不要です。 + +## 動作状況を確認する + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status`はプロバイダー、エンドポイント、モデル、モード、設定ファイルとそのパーミッションを表示し、キーは表示しません。その下に最近のアクティビティが要約されます。Jevが評価した呼び出しの数、正規表現にフォールバックした頻度とその理由、レイテンシ、およびJevがクリアしたreviewableポリシーが表示されます。 + +## 実際の呼び出しを検証する + +フックが付いたエージェントで新しいセッションを開始します。ファイル読み取りツールで`README.md`を読み取りタイトルを報告するよう指示してください。セッションにそのツール呼び出しが含まれていることを確認してから、`failproofai jev status`を再度実行します。最近の評価済み呼び出しカウントが増加しているはずです。[ローカルダッシュボード](/ja/reference/local-dashboard#review-policy-activity)の**Policies → Activity**を開いて、呼び出しのJev判定とモードを確認してください。observeモードでは、ポリシーの結果が引き続き呼び出しを決定します。クリアランスは、reviewableポリシーがマッチし、Jevが指定されたすべてのチェックをクリアした場合にのみ表示されます。通常の読み取り操作にはクリアすべきポリシーがない場合があります。 + +## Observeモード + +デフォルトは`enforce`です。Jevの判定を変更せずに監視するには、`observe`に切り替えます。JevはまだリクエストされてI判定が記録されますが、適用されるのは正規表現の結果です。 + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off`は設定(エンドポイントとキー)を保持しながらJevへの問い合わせを停止します。フックは設定なしの場合とまったく同じように正規表現ポリシーを実行し、`failproofai jev status`は「off (switched off)」と表示します。`--mode observe`または`--mode enforce`で再度切り替えられます。 + +同じプロバイダーで`setup`を再実行すると保存済みのキーが保持されるため、モードの切り替えはフラグ1つで済みます。プロバイダーを切り替えると最初からやり直しとなり、そのプロバイダーのキーが求められます。リクエストを別のホストに移動する`--base-url`も同様です。保存済みのキーは、指定されたホスト、またはそのプロバイダー自身のAPIにのみ送信されます。 + +## 設定ファイル + +すべてのデータは`setup`によって書き込まれる1つのファイル`~/.failproofai/jev.json`に保存されます。 + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| フィールド | 意味 | +| --- | --- | +| `provider` | `typesafe`、`openrouter`、`vercel`、`cloudflare`、`custom`、または`failproofai`(このファイルではなくFailproofAI Cloud接続からキーを取得する。[FailproofAI Cloud経由のJev](/ja/reference/jev-cloud)を参照)。 | +| `apiKey` | `Authorization: Bearer `として送信されます。 | +| `baseUrl` | `custom`の場合は必須。それ以外の場合はプロバイダーのAPIベースを置き換えます。`https`必須。`localhost`への平文`http`は`mode: observe`の場合のみ受け付けられます。ローカルポートは認証されないため、プロキシが停止している間は、エージェント自身を含むマシン上の任意のプロセスが代わりに応答する可能性があります。 | +| `accountId` | Cloudflareのみ: 32文字の小文字16進数。 | +| `model` | プロバイダーのデフォルトモデルIDを置き換えます。バージョン付きIDはJev 1.13を指定する必要があります。APIキーの形式をした値は拒否され(返答にも含まれません)、`--model`に貼り付けられたキーは保存も送信もされません。 | +| `timeoutMs` | ツール呼び出しがJevを待つ時間。正規表現結果を使用するまでの時間。100〜10000、デフォルトは3000。 | +| `mode` | `enforce`(デフォルト)、`observe`、または`off`(設定を保持しJevを実行しない)。 | + +3つのルールが設定ファイルを保護します。 + +- **オーナーのみ。** パーミッション`0600`で書き込まれます。他のユーザーまたはグループが読み書きできるコピーは**拒否**され、`chmod 600 ~/.failproofai/jev.json`を実行するか`setup`を再実行するまでフックは正規表現にフォールバックします。ディレクトリも確認されます。`~/.failproofai`は他のユーザーが**書き込み可能**であってはなりません。ファイル自体のパーミッションに関係なく、そこに書き込めるユーザーはファイルを置き換えられるからです。`setup`は書き込みビットを見つけた場合に削除します。`failproofai jev status`は設定が拒否された場合にその旨を表示し、ファイルに記載されたエンドポイントを示します。他のユーザーが変更した可能性があるため、`chmod`を実行する前に自分のファイルであることを確認してください。このようなファイルで`setup`を再実行すると、保存済みのキーはプロバイダー自身のAPIにのみ引き継がれます。それ以外のエンドポイントが記載されている場合はキーの再入力が必要です(`--key-stdin`)、またはプロバイダーへのリクエストに戻す場合は`--base-url default`を使用します。 +- **グローバルのみ。** リポジトリはJevを有効にしたり、別のエンドポイントに向けたり、モデルを選択したりすることはできません。プロジェクト内の`.failproofai/jev.json`は無視され、プロバイダー、URL、モデル、アカウントIDはそのファイルからのみ読み込まれます。リポジトリのエージェント設定が設定できる環境変数からは読み込まれません(`FAILPROOFAI_HOME`もこれを回避する手段ではありません。これはJevのみのリダイレクトではなく、ポリシーを含むfailproofaiディレクトリ全体を移動します)。 +- **キーのみ環境変数から取得可能。** ファイルに`apiKey`がない場合、`FAILPROOFAI_JEV_API_KEY`がそのセッションのキーとして使用されます(`setup --key-from-env`でそのようなファイルを書き込みます)。ファイルに保存されているキーを置き換えることはなく、ファイルなしでJevを有効にすることもできません。変数が設定されていない場合、そのシェルではJevは単純にオフになります。`failproofai jev status`はその旨を表示し、終了コード0で終了し、設定はそのままです(`status --json`は`"reason": "no-env-key"`とともに`"status": "key-missing"`を報告します)。`failproofaid`デーモンはシェルの環境変数を参照しないため、`failproofai config`でセットアップしたマシンではキーをファイルに保存してください。 + +## どのJevが応答するか + +Failproof AIの判定しきい値はJev 1.13を基準に調整されているため、そのファミリー(`jev-1.13.x`、またはOpenRouterの`typesafe/jev-1.13-`)からの回答のみが使用されます。プロバイダーがJevをエイリアスのみで識別し、バージョンを報告しない場合(Vercel、およびバージョンを通知しない場合のCloudflare)、回答は使用されますが未検証として記録されます。`custom`エンドポイントは応答したモデルを報告する必要があります。唯一の例外は、設定したバージョンなしの`--model`名で、エコーバックされた場合は同様に未検証として記録されます。別のバージョンを報告する回答、またはバージョンを報告しない`custom`の回答は使用されません。その呼び出しは`model-mismatch`という理由で正規表現にフォールバックします。 + +## Jevが回答できない場合 + +以下のそれぞれの場合、その呼び出しの正規表現結果にフォールバックし、理由とともに記録されます。`failproofai jev status`がこれを集計します。 + +| 理由 | 原因 | +| --- | --- | +| `timeout` | `timeoutMs`内に回答なし。 | +| `http-429` | プロバイダーがキーをレート制限した。 | +| `rate-limited` | Failproof AI自身のリミッターが送信前に呼び出しを保留した。毎秒5リクエスト、最大5バーストまで、プロバイダーが`429`を返した後は一時的に停止。プロバイダー側ではない。 | +| `http-500`、`http-502`、`http-503`、… | プロバイダーでのサーバーエラー。正確なステータスが記録されます。 | +| `out-of-credits` | HTTP 402:プロバイダーアカウントのクレジットが残っていない。 | +| `provider-refused` | Cloudflareからの「Model execution failed (Payment error)」というHTTP 402:プロバイダーがこのリクエストのモデル実行を拒否した。通常は課金の問題ではないため、クレジットを追加しても解決しません。 | +| `http-401`、`http-403` | キーが拒否された。 | +| `http-404` | `/systemone`に何もサービスされていないため、ベースURLが誤っています。`/systemone`はベースURLに付加されるため、各プロバイダーはバージョンルートに配置しています。`failproofai jev models`でエンドポイントが実際に何を提供しているか確認できます。 | +| `network` | エンドポイントに到達できなかった。 | +| `http-301`、`http-302`、`http-307`、`http-308` | エンドポイントがリダイレクトで応答した。リダイレクトは決して辿らないため、回答は常に設定内のURLからのみ来ます。`--base-url`を最終URLに設定してください。 | +| `malformed` | エンドポイントが応答したが、JevのAnswerではありませんでした。JSONでないボディ、または回答が含まれていないボディ。 | +| `cloudflare-error`、`cloudflare-incomplete` | Cloudflareのエンベロープが失敗、またはまだ完了していないジョブを報告した。 | +| `model-mismatch` | Jev 1.13以外のバージョンが応答した、または`custom`エンドポイントがどのモデルが応答したかを報告しなかった。 | +| `request-cut` | **障害ではありません。** Jevが応答しましたが、呼び出しの一部しか表示されなかったため、その回答では何もクリアされませんでした。[Jevが応答したが呼び出し全体を対象としていない場合](#when-jev-answered-but-not-on-the-whole-call)を参照してください。 | + +`failproofai jev status`はさらにいくつかの稀な理由(`upstream-error`(回答にプロバイダー自身のエラーが含まれていた)や`config`など)を表示することがあり、名前を付けられない理由はすべて`other`として集計されます。 + +`request-cut`がこの表に含まれているのは、`failproofai jev status`が他の理由とともに集計し、またこれもすべてのdenyを維持するからです。しかし、プロバイダーに関して何も示していない唯一の理由でもあります。リクエストは届いてJevが回答しました。上記のすべての行とは異なり、その回答は依然としてカウントされます。Jev自身のdenyまたは警告は、破棄されるのではなく正規表現結果に加えて適用されます。したがって、`request-cut`が続く場合は、エンドポイントが不調なのではなく、全体を送信するには大きすぎる呼び出しが評価器に届いているということです。クレジットの追加やURLの変更では改善しません。 + +## Jevが応答したが呼び出し全体を対象としていない場合 + +さらに2つの状況が発生する可能性があり、どちらもJevの回答失敗ではありません。いずれも、呼び出しまたは会話のどれだけがひとつのリクエストに収まったかに関係します。 + +**呼び出し自体の一部が収まらなかった。** ツール呼び出しは固定バジェット内で送信されますが、非常に大きなもの(非常に大きな`Write`、巨大なMCPボディ、上限までパディングされたコマンド)は収まった部分のみで送信されます。Jevはまだ回答し、その回答はカウントされます。Jev自身のdenyや警告は通常通り適用されます。しかし**クリア**することはできません。呼び出しの一部に対する判定はその呼び出し全体の判定ではないからです。そのため、すべてのポリシーdenyが維持され、呼び出しは`request-cut`という理由でフォールバックとして記録されます。これが意味するルール:呼び出しを大きくするとクリアランスを失う可能性があり、クリアランスを得ることは決してできません。 + +**メッセージが収まらなかった。** 長いプロンプト、エージェントの最後のメッセージ、またはこの評価器自身のストアがすでに上限に達したプロンプト。**何も変わりません**:呼び出しは他のものとまったく同じように判定、クリア、記録され、フォールバックとしてカウントされません。入力した内容の長さが判定を決定することはなく、切り捨てによって同意が作り出されることもありません。プロンプトがすでに上限に達した状態で届いた場合、「あなたはこれを要求しなかった」という結論はそもそも導き出せない状態になります。 + +両者の境界線は誰がテキストを書いたかです。呼び出しはエージェントのものであり、長さが重要度を軽減できるルールはエージェントが悪用できるものになります。プロンプトはあなたのものであり、その長さをシグナルとして扱うことは、仕様書やスタックトレースを貼り付けることへの罰にしかなりません。 + +## マシンから何が送信されるか + +Jevが評価する各ツール呼び出しについて、プロバイダーに1つのリクエストが送信されます。その内容は以下の通りです。 + +- ツール呼び出し自体(APIキー、ベアラートークン、`KEY=`代入などのシークレットはリダクトされます) +- あなたが入力した最近のプロンプト(エージェントのハーネスが追加したテキストは除去されます) +- 最新のプロンプト前のエージェントの最後のメッセージ(エージェントが書いたものとしてラベル付け) +- パスがプロジェクト内かどうかなど、ローカルで計算された情報(最初のレビュー済み呼び出し時のセッションのプロジェクトルート、[セッション中固定](/ja/reference/jev-intent#the-project-root))および現在のgitブランチ + +これらはあなたの設定内のエンドポイントにのみ、あなたのキーの下で送信されます。 + +## 無効にする + +```bash +failproofai jev remove +``` + +これにより`~/.failproofai/jev.json`が削除されます。次のツール呼び出し以降、フックは以前と同様に正規表現ポリシーを実行します。`~/.failproofai/state/semantic/`以下のセッションごとのストア(`sessions/`に記録されたプロンプト、`roots/`にプロジェクトルート)はそのまま残り、自然に期限切れになります。設定を保持しながらJevへの問い合わせを停止するには、代わりに`failproofai jev setup --mode off`を使用してください。 + +## コマンドリファレンス + +| コマンド | 結果 | +| --- | --- | +| `failproofai jev --url --key-stdin` | 1つのコマンドで設定。プロバイダーはURLのホストから決定される | +| `failproofai jev --url --token ` | 同上。コマンドラインにキーを指定(履歴とプロセスリストに残る) | +| `failproofai jev setup --provider --key-stdin` | stdinからパイプされたキーで設定を書き込む | +| `failproofai jev setup --provider ` | 同上。マスクされたプロンプトでキーを入力 | +| `failproofai jev setup --key-from-env` | キーを保存しない。セッションごとに`FAILPROOFAI_JEV_API_KEY`を読み込む | +| `failproofai jev setup --mode observe` | 保存済みのキーを維持しながらモードを切り替え(`enforce`、`observe`、`off`) | +| `failproofai jev setup --model ` / `--base-url ` | モデルまたはAPIベースをオーバーライド。`default`でオーバーライドをクリア | +| `failproofai jev setup --timeout-ms ` | 呼び出しごとのバジェットを変更 | +| `failproofai jev status [--json]` | 設定、パーミッション、最近のアクティビティ(キーは表示しない) | +| `failproofai jev test [--json]` | 1回のライブリクエスト:レイテンシと応答したバージョン | +| `failproofai jev models [--provider ] [--url ] [--json]` | そのエンドポイントの`/models`が報告するモデルID(設定済みのものをマーク) | +| `failproofai jev remove` | 設定を削除。Jevをオフにする | \ No newline at end of file diff --git a/docs/ja/reference/jev.mdx b/docs/ja/reference/jev.mdx new file mode 100644 index 000000000..7514954d9 --- /dev/null +++ b/docs/ja/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev インテグレーション リファレンス" +description: "Jev の設定、プロバイダー、キー、リクエストデータ、および障害時の動作について。" +icon: "braces" +--- + +Jev は Failproof AI において 2 つの用途があります。 + +| 用途 | 実行タイミング | 返却内容 | 開始ガイド | +| --- | --- | --- | --- | +| セッション評価 | セッション終了後 | 固定回答問題のスコア | [Jev 評価](/ja/evaluations/jev) | +| ツールコール ポリシーレビュー | ゲート付きツールコールの実行前 | インストール済みポリシーと合わせた判定結果 | [Jev ポリシー](/ja/policies/jev) | + +## リファレンスページ + +| トピック | 詳細 | +| --- | --- | +| [評価クエスチョン](/ja/reference/jev-evaluations) | Boolean および順序付きスコアの基準、結果、制限、バックフィル。 | +| [プロバイダー比較と独自キーの設定](/ja/reference/jev-providers) | TypeSafe、OpenRouter、Vercel、Cloudflare、カスタムエンドポイント、URL の推論、モデル ID、`jev.json`、モード、フォールバックコード。 | +| [FailproofAI Cloud ルート](/ja/reference/jev-cloud) | マシンキーの権限、自動オブザーブ設定、使用量制限、接続状態、データ処理。 | + +ローカル CLI コマンドについては [Failproof AI CLI リファレンス](/ja/reference/failproof-cli) を参照してください。[ローカルダッシュボードリファレンス](/ja/reference/local-dashboard#set-up-jev) では、Jev の設定とアクティビティビューについて説明しています。 \ No newline at end of file diff --git a/docs/ja/reference/mcp.mdx b/docs/ja/reference/mcp.mdx new file mode 100644 index 000000000..33018cc19 --- /dev/null +++ b/docs/ja/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCPサーバー" +description: "Claude、Cursor、Codex、またはその他のMCPクライアントを、自分の権限でFailproof AI Cloudに接続します。" +icon: "plug" +--- + +AIツールをFailproof AI Cloudに接続し、エージェントのデータを操作できます。セッションやイベントの照会、読み取り専用SQLの実行、ダッシュボード・アラート・イシュー・監査・ポリシーの参照が可能です。また、権限があれば、アラートの作成やポリシーのデプロイといった変更操作も行えます。 + +すべての呼び出しは**あなた自身**の権限で、接続時に選択した**1つ**の組織内で実行されます。 + +ホスト型・セルフホスト型を問わず、アドレスは共通です: + +```text +https://gateway.befailproof.ai/mcp +``` + +## クライアントの接続 + +クライアントにアドレスを追加してください。ツールを初めて使用するとブラウザが開きます。Failproof AI Cloudの場所を選択し、サインインして組織を1つ選び、**Allow** をクリックします。**Cancel** を選択した場合は何も接続されません。 + +ページにはアプリ名とリダイレクト先が表示されます。独自のウェブアドレスで識別されていないアプリは **unverified app** と表示されるため、自分のクライアントから操作を開始した場合にのみ続行してください。 + + + + claude.aiまたはClaude Desktopで、**Settings → Connectors → Add custom connector** に進みます。名前を `Failproof AI` と入力し、アドレスを入力して **Add**、次に **Connect** を選択します。 + + TeamプランおよびEnterpriseプランでは、まずオーナーが組織用のコネクターを追加します。その後、各メンバーが自分のアカウントを接続します。 + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + 次に、Claude Code内で `/mcp` を実行し、`failproofai` を選択して **Authenticate** をクリックします。 + + + `~/.cursor/mcp.json` またはプロジェクトの `.cursor/mcp.json` に以下を追加します: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursorのサーバー一覧に **Needs login** と表示されます。それを選択してサインインしてください。 + + + `~/.codex/config.toml` に以下を追加します: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + 次に、`codex mcp login failproofai` を実行します。 + + + OAuthを使用したStreamable HTTP経由のリモートMCPサーバーをサポートするクライアントであれば使用できます。上記のアドレスを設定してください。クライアントIDやシークレットの設定は不要です。 + + + +## 接続ごとに1つの組織 + +接続は選択した組織内でのみ機能します。2つの組織を使用するには、`failproofai-acme` や `failproofai-sandbox` のように異なる名前でサーバーを2回追加し、それぞれを別の組織に接続してください。 + +デモ組織への接続は受け付けていません。代わりに自分の組織を選択してください。 + +## 権限 + +接続では、組織内であなたが持つ権限の範囲内で操作できます。権限はリアルタイムで反映されます。管理者が権限を追加すればツールもそれを取得し、権限を削除すれば次の呼び出し時にツールからも失われます。 + +| 権限 | ツールでできること | +| --- | --- | +| `events:read` | イベントの一覧表示、セッションの概要確認、エージェントと環境の一覧表示 | +| `evaluations:read` | セッションの一覧表示、評価結果とジョブの確認・要約 | +| `evaluations:trigger` | 評価の作成、新バージョンの公開、オン/オフの切り替え、バックフィル、セッションの再評価 | +| `dashboards:read`、`dashboards:write` | ダッシュボードの参照、または作成・名前変更・クエリの追加 | +| `queries:read`、`queries:write` | 保存済みクエリの参照、または保存・編集 | +| `queries:run` | 読み取り専用SQLクエリの1件実行とクエリスキーマの確認 | +| `alerts:read`、`alerts:write` | アラートの参照、または作成・編集・一時停止・削除・テスト | +| `issues:read` | イシューの参照、確認、コメント | +| `issues:create` | アラートに対するイシューの作成 | +| `issues:close` | イシューの解決とクローズ | +| `audits:read`、`audits:write` | 監査・実行・検出結果の参照、または監査の作成・編集と実行の開始 | +| `code_fixes:read` | イシューの修正方法の確認、および自分のエージェントが修正するためのコンテキスト取得 | +| `code_fixes:write` | Failproof AI Cloudでの修正を開始し、GitHubにプルリクエストを作成 | +| `policies:read`、`policies:write` | ポリシー・マシン・デプロイメントの参照、またはポリシーの公開・デプロイ・ロールバック | + +一部のツールは組織データを読み取らないため権限が不要です:セッションやイベントのリンク作成、このドキュメントの検索などがこれにあたります。 + +AIツールは、APIキー・ユーザー・設定・組織管理には一切アクセスできず、イベントの送信も行えません。 + +## 変更の承認 + +クライアントがプロンプトを表示できる場合、書き込み操作の前に確認が求められます。変更内容を確認し、**Approve this change** を選択して続行してください。拒否するか約4分以内に回答しない場合、変更は行われません。クライアントによっては1分で待機を終了するため、速やかに回答してください。 + + + プロンプトをサポートしないクライアントでは確認が行われず、クライアントが呼び出しを行った時点で書き込みが実行されます。その場合、クライアント自身の確認が唯一の安全策となるため、書き込みツールでは必ず有効にしておいてください。 + + +## 接続済みアプリの確認と削除 + +**Settings → Integrations → MCP** に、現在の組織の接続済みアプリが権限と最終使用日とともに一覧表示されます。**Revoke** を選択すると即座にアクセスが遮断されます。クライアントからサーバーを削除しても接続が取り消されます。 + +1つの組織につき最大5つのアプリを接続できます。同じアプリを再接続すると、以前の接続が置き換えられます。 + +## セルフホスト型デプロイメント + +接続時に **Self-hosted Failproof AI Cloud** を選択し、サインイン時に使用するアドレスを入力してください。デプロイメントは公開HTTPSでアクセス可能である必要があります。 + +ツール呼び出しとその結果は、AIツールとデプロイメントの間でホスト型Failproofゲートウェイを経由します。ゲートウェイはそれらを保存しません。 + +## データの取り扱い + +結果は接続したAIツールに送信され、そのツールのプロバイダーが独自の規約に基づいて処理します。各ツール呼び出しについて、Failproof AIはツール名・結果・所要時間・組織のみを記録します。引数や結果の内容は記録されません。詳しくは[プライバシーポリシー](https://befailproof.ai/privacy/)をご覧ください。 + +## トラブルシューティング + +| 表示内容 | 対処方法 | +| --- | --- | +| "Started in another browser" | クライアントが開いたブラウザ(Cookieを許可した状態)でサインインを完了し、クライアントから再度開始してください | +| **Allow** 後にエラーが発生する | リンクは1回限り有効で10分で期限切れになります。クライアントから再度開始してください | +| 期待していたツールが表示されない | その組織での権限がありません。管理者に確認してください。権限取得後に再接続は不要です | +| クライアントがサインインを繰り返し要求する | 接続が取り消されたか、組織を退出したか、90日間未使用の状態になっています。再接続してください | +| "You have 5 connected apps" と表示される | **Settings → Integrations → MCP** でいずれかを削除してから再接続してください | + +解決しない場合は [support@befailproof.ai](mailto:support@befailproof.ai) までメールでお問い合わせください。 \ No newline at end of file diff --git a/docs/ja/reference/otel.mdx b/docs/ja/reference/otel.mdx new file mode 100644 index 000000000..b379c4088 --- /dev/null +++ b/docs/ja/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "コーディングエージェントへのOTELオプトイン、配信の確認、および以前の設定の復元。" +icon: "radio" +--- + +`failproofai otel` は、FailproofAI Cloud へのオプションの OpenTelemetry レポートを設定します。まず `failproofai config` でマシンを接続し、組織の管理者に **Settings → OpenTelemetry** を有効にするよう依頼してください。 + +インタラクティブなセットアップでは、Cloud キーフィールドとエージェント選択の後に OpenTelemetry について確認します。このオプションのステップはデフォルトで「No」になっています。「Yes」を選択すると OTEL エージェントを選択できます。接続が書き込まれた後、同じ有効化コードが実行されます。セットアップ前に Esc を押しても変更は適用されません。無人セットアップ、指定済みキー、オープンソースモード、および保存済み接続の保持では、オプトインは行われません。 + +## エージェントの有効化 + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +サポートされているエージェントは `claude`、`codex`、および `copilot`(VS Code)です。Copilot のセットアップには VS Code の実行ファイルまたはインストール済みの Copilot 拡張機能が必要です。設定ディレクトリのみが残っている状態では不十分です。どちらも見つからない場合、セットアップは Copilot をスキップします。 + +`--local` は、Cloud に直接送信するのではなく、ローカルリレーに送信します。Copilot は、設定に認証ヘッダーを保存できないため、自動的にリレーを使用します。 + +リレーはあなたのマシン上でのみ待ち受けます。設定済みの FailproofAI デーモンは数秒以内に変更を検知します。再起動は不要です。別のアプリケーションがリレーポートを使用している場合、ステータスはオフと表示され、デーモンは引き続き実行されます。 + + +テキストキャプチャはデフォルトで有効です。プロンプトやツールの詳細を省略するには `--no-content` を追加してください。エージェントのバージョンによって公開されるコンテンツ制御が異なります。機密データと組み合わせて使用する前に、エージェントがエクスポートする内容を確認してください。 + + +Codex がエクスポートするのは会話ログのみであり、内部ランタイムのトレースやメトリクスは含まれません。Codex の設定に `log_user_prompt = false` が明示的に記載されている場合、その設定はオフのままになります。有効化時にその選択が維持される場合、セットアップはその旨を通知します。 + +### レポートパスの選択 + +エージェントのトランスクリプトレポートが有効になっている場合、セットアップは次のように確認します: + +> failproofai already sends Claude Code sessions to Cloud. Send them with OTEL instead? Transcript upload for Claude Code stops. + +デフォルトは「No」です。`--yes` を指定すると、プロンプトなしで切り替えが実行されます。他のエージェントおよびポリシーの適用には影響しません。 + +Codex のセットアップは、エクスポーター設定を書き込む前に、コレクターの変更をデーモンが確認するまで待機します。確認がタイムアウトした場合、セットアップは Codex を起動する前に待機するよう警告します。 + +Config v2 では、記憶されたトレースリストを `agents.selected`(検出履歴は `agents.seen`)に保持します。エージェントごとのトランスクリプト設定は `collector.agents..sessions`、OTEL の所有権は `otel.agents`、リレー設定は `collector.otlp.enabled` / `collector.otlp.port` に保持されます。これらの分離されたキーにより、古い OTEL 設定が読み取り可能な状態を維持します。セットアップはトランスポート設定やエージェント設定の復元に必要な状態を失わずに、トレースリストを変更できます。 + +## セットアップの確認 + +```bash +failproofai otel status +``` + +ステータスには、各エージェント、FailproofAI による設定管理の有無、送信先、組織の取り込みスイッチ、リレーの状態、および最後のリレーアップロード結果が表示されます。 + +組織スイッチが `unknown` の場合、サーバーがその情報を提供しなかったか、到達できなかったことを意味します。これはエラーではなく、旧バージョンの Cloud での設定を妨げるものではありません。 + +Cloud が OTEL をまだサポートしていない場合、リレーは拒否されたエクスポートを破棄せずに保持します。組織の取り込みがオフの場合、`enable` は何も書き込まずにエラーで終了します。まず管理者に有効化を依頼してください。 + +## アプリケーション向けの設定出力 + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +出力は OTLP/HTTP エクスポーター用のシェル環境ブロックです。Cloud 出力では `OTEL_EXPORTER_OTLP_ENDPOINT` を Cloud の OTLP ベース `https:///otel` に設定し、エクスポーターは `/v1/` を追加します。`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` のようなシグナルごとの変数には、完全な `https:///otel/v1/logs` が必要です。ローカル出力はリレー `http://127.0.0.1:` を指します。Cloud 出力には設定済みの API キーが含まれます。これはシークレットとして扱ってください。ローカル出力にはキーは含まれません。ローカル出力を使用するには、まずローカルエージェントを有効化してリレーを起動してください。 + +## 以前の設定の復元 + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable は FailproofAI が書き込んだ設定のみを復元し、無関係な変更は保持します。また、各エージェントの以前のトランスクリプトレポート設定を復元します。最後に管理されていたローカルエージェントが無効化されると、リレーはエクスポートの受け付けを停止します。 + +Codex の場合、disable は `collector.agents.codex.sessions_resume_after`(エポックミリ秒)も記録します。既存のロールアウトバイトは配信済みとして扱われるため、OTEL でキャプチャされたセッションが再度アップロードされることはありません。その後に追加されたデータは引き続きトランスクリプトレポートを通じて送信されます。 + +すべてのコマンドは `--help` をサポートしています。アプリケーションおよびコーディングエージェントの例については、[OpenTelemetry in Cloud](/ja/agenteye/opentelemetry) を参照してください。 \ No newline at end of file diff --git a/docs/ja/reference/slack.mdx b/docs/ja/reference/slack.mdx new file mode 100644 index 000000000..43eb5d807 --- /dev/null +++ b/docs/ja/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack アプリ" +description: "Slack から Failproof Assistant に質問し、スレッドでチャートを受け取り、ボタンで変更を承認できます。" +icon: "slack" +--- + +Slack から [Failproof Assistant](/ja/sessions/assistant) に質問できます。チャンネルでアプリをメンション、ダイレクトメッセージを送信、または `/failproof <質問>` を使用してください。回答には**ご自身の** Failproof AI 権限が使用され、チャートはスレッドに届き、何かを変更する操作は事前に承認を求めます。 + +公式アプリは 1 つだけです。Failproof AI Cloud がホスト型でもセルフホスト型でも同様に動作します。 + + + 回答は AI モデルによって生成されるため、不正確な場合があります。重要な内容はリンクされたソースデータで必ず確認してください。 + + +## ワークスペースを接続する + +Failproof AI の `settings:write` 権限と、Slack ではワークスペースの管理者またはオーナー、あるいはアプリを追加するユーザーである必要があります。 + + + + 1. **設定 → インテグレーション** に移動し、**Slack に追加** を選択します。 + 2. Slack でアプリを承認します。 + 3. Failproof AI に戻り、ワークスペースを組織に接続することを確認します。 + + + 1. アプリを追加して、**ホーム** タブを開きます。 + 2. **FailproofAI Cloud で続ける** を選択するか、**独自の URL を使用する** を選択してサインイン先のアドレスを入力します。 + 3. 続行ボタンを選択し、サインインして組織を選び、確認します。リンクは 1 回のみ有効で、10 分後に期限切れになります。 + + + +1 つのワークスペースは 1 つの組織に、1 つの組織は 1 つのワークスペースに接続されます。 + +アカウントをお持ちでない場合は、まず[アカウントを作成](https://app.befailproof.ai/login)してから接続してください。 + +## Slack でのあなたの識別 + +初回の質問時に、アプリはどのメンバーであるかを以下のように判断します。 + +- **メールアドレスによる自動識別**:接続済みワークスペースの正規メンバーであり、Slack のメールアドレスが確認済みで、そのメールアドレスを使用する組織メンバーがちょうど 1 人の場合。 +- **それ以外の場合**:Failproof AI を開いて Slack ユーザーをアカウントにリンクするためのプライベートな **アカウントをリンク** ボタンが表示されます。 + +## 質問する + +| 場所 | 方法 | +| --- | --- | +| チャンネル | アプリをメンションする。続けるにはそのスレッドに返信(メンション不要) | +| ダイレクトメッセージ | アプリにメッセージを送る | +| アプリが参加しているグループダイレクトメッセージ | メンションし、その後スレッドに返信して続ける | +| Slack Connect チャンネル | アプリをメンションする | +| アプリが参加しているすべての会話 | `/failproof <質問>` で回答付きのスレッドを開始 | +| `/failproof help` | アプリでできることを確認する | +| `/failproof status` | 接続中の組織とリンクされているユーザーを確認する | +| `/failproof link` | リンクされている Failproof AI アカウントを確認する | + +1 つのスレッドが 1 つの会話です。同僚が同じスレッドでアプリをメンションすると、それぞれの権限に基づいた回答が得られます。スレッドを開始した本人のみ、メンションなしで会話を続けられます。 + +回答がデータの場合、アプリはチャートまたは表を投稿し、Failproof AI で開くリンクを表示します。 + +## 変更を承認する + +アシスタントが行うすべての変更は、最初に **承認** と **キャンセル** ボタンが表示され、**承認** の前に Slack がもう一度確認を求めます。ボタンに回答できるのは質問した本人のみで、ボタンは 5 分後に期限切れになり、変更はその人の権限で実行されます。 + +Slack からアシスタントが変更できるのは、権限を持っている場合に限り、保存済みクエリとダッシュボード、評価、アラート、監査、課題、ポリシー、およびコード修正の提案です。API キー、ユーザー、設定は変更できません。 + +## リンクプレビュー + +Slack に貼り付けた Failproof AI の課題、セッション、評価のリンクは、ホスト型 Failproof AI Cloud ではカードに展開されます。カードには、リンクを展開したユーザーが閲覧できる内容のみが表示されます。セルフホストのアドレスへのリンクは展開されませんが、アシスタント自身の回答内のカードは引き続き表示されます。 + +## Slack Connect チャンネル + +別のワークスペースのユーザーも、組織のメンバーであれば、アカウントをリンクした後にアプリを使用できます。回答は会話内の全員(組織のメンバーでない方を含む)に表示されるため、全員が見られる場所で質問することをご認識ください。 + +チャンネル内の他のすべてのワークスペースに組織にリンクされたメンバーが存在するまで、アプリは回答しません。それまでの間は、質問した人に理由を伝えます。 + +## アプリが要求する権限 + +| Slack 権限 | 理由 | +| --- | --- | +| `app_mentions:read` | アプリへのメンションを検知するため | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | ダイレクトメッセージとアプリのスレッドへの返信を受信するため。アプリはその他のメッセージを無視し、過去のメッセージを読み返すことはありません | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | 会話の種類を確認し、回答を誰が見られるかを把握するため | +| `chat:write` | 回答と承認ボタンを投稿するため | +| `commands` | `/failproof` を提供するため | +| `files:write` | チャートを投稿するため | +| `links:read`, `links:write` | 貼り付けられた Failproof AI リンクのプレビューを表示するため | +| `users:read`, `users:read.email` | Failproof AI アカウントとの照合、および名前の表示のため | + +## 切断する + +**設定 → インテグレーション** に移動して **切断** を選択するか、アプリの **ホーム** タブで **切断** を使用するか、Slack からアプリを削除してください。 + +いずれかの操作により、ワークスペースの接続、ボットトークン、リンク済みアカウント、スレッドの記録が削除されます。過去の Slack 会話はダッシュボードで引き続き閲覧できます。その後、組織は任意のワークスペースをすぐに接続できます。 + +## データとプライバシー + +質問と回答は、スレッドを開始した人の下で、組織のダッシュボードに会話として保存されます。Slack のデータが AI モデルのトレーニングに使用されることはありません。アプリが受信するデータと保持期間については、[プライバシーポリシー](https://befailproof.ai/privacy/)をご覧ください。 + +## トラブルシューティング + +| 表示されるメッセージ | 対処方法 | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | ワークスペースの管理者がアプリの **ホーム** タブを開いて選択する | +| "This link expired or was already used." | **ホーム** タブで Cloud を再度選択して新しいリンクを取得する | +| "This org is already connected to a Slack workspace." | 先に設定で切断する | +| "That Slack workspace is connected to another org." | 先にその組織から切断する | +| "Link your account to use the assistant." | ボタンを選択して Failproof AI で確認する | +| グループダイレクトメッセージでアプリが回答しない | Slack でアプリを再度追加してグループ権限を付与する。接続は維持されます | +| "I won't post answers from your organization here" | そのワークスペースの組織メンバーがアプリをメンションしてアカウントをリンクする | + +それでも解決しない場合は、[support@befailproof.ai](mailto:support@befailproof.ai) までメールでお問い合わせください。 \ No newline at end of file diff --git a/docs/ja/sessions/sentiment.mdx b/docs/ja/sessions/sentiment.mdx new file mode 100644 index 000000000..8e60cff51 --- /dev/null +++ b/docs/ja/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "センチメント分析" +description: "Jevのセンチメントスコアで、苛立ちや混乱、修正を求めるメッセージを見つけましょう。" +icon: "smile" +--- + +Jevは、エージェントに送られた各メッセージに対して、**怒り**、**苛立ち**、**喜び**、**困惑**という4つの感情を0〜100のスコアで評価します。さらに、エージェントのパフォーマンスに関する3つのシグナルも計測します: + +- **Correcting**:エージェントが間違いを犯したとユーザーが指摘している。 +- **Resolved**:エージェントが問題を解決したとユーザーが確認している。 +- **Doubtful**:エージェントの回答が正しいか、あるいは実際に作業を行ったかをユーザーが疑問視している。 + +センチメント分析を活用することで、ユーザーが我慢の限界に達しているような会話や、頻繁に修正が入るエージェント、うまく機能している返答を見つけることができます。これはJevに組み込まれたスコアリング機能であり、エバリュエーションを自分で作成する必要はありません。独自の固定回答の質問については、[Jevのエバリュエーションを作成](/ja/evaluations/jev)してください。 + + + センチメント機能は、管理者が組織向けに有効にするまでオフになっています。Jevはメッセージごとに1回のスコアリングリクエストを送信し、エージェントの返信とともに対象メッセージを受け取ります。スコアリングには組織のモデル予算が使用されます。 + + +## 有効にする + +1. **管理 → 設定** に移動します。 +2. **人間の入力センチメント** の項目で、スイッチを **オン** にして保存します。 + +最初に前日分のメッセージがスコアリングされます。その後、新しいメッセージは到着から1〜2分以内にスコアリングされます。 + +## レビューする会話を探す + +**Observe → Sentiment** を開きます。時間、環境、エージェント、またはセッションIDでフィルタリングできます。ヘッダーにはメッセージ数とセッション数が表示され、**フラグが立てられた** メッセージの数と、最も強いシグナルの種類が示されます。怒り、苛立ち、修正、困惑、疑念のいずれかのスコアが100点中35点に達すると、そのメッセージにフラグが立てられます。 + +![メッセージ数・セッション数、フラグ付きメッセージ、時系列のJevスコアを表示するSentimentダッシュボード。](/images/dashboard/sentiment-overview.png) + +**Score over time** を使用してシグナルを比較します。表示するスコアを選択してから、ポイントをクリックするとその時間帯のメッセージを確認できます。**By agent** テーブルでは、特定のシグナルが集中しているエージェントを把握できます。**Messages** では、最も強いネガティブスコア順に並べ替えたり、個別のスコアで絞り込んだりすることができます。メッセージをセッション内で開くと、問題の原因を判断する前に周辺の会話を読み返せます。 + +![最もネガティブなスコア順に並べられたSentimentメッセージリスト。各ソースセッションへのリンク付き。](/images/dashboard/sentiment-messages.png) + +## スコアリングされるメッセージ + +ユーザーが入力したメッセージのみが対象です: + +- SDKを使用して人間の入力として記録された、カスタムエージェント向けのメッセージ。 +- Claude Code、Codex、OpenCode、pi、Hermes、OpenClawに入力されたプロンプト(セッションのトランスクリプトが送信される場合、これがデフォルトの動作です)。スケジュールされたジョブ、注入された指示、サブエージェントへの引き継ぎ、エージェントのランタイム自身が生成するテキストはスコアリングされません。また、`claude -p`、`codex exec`、`hermes -z` のような非インタラクティブな実行も対象外です。これらのプロンプトはスクリプトによって生成されたものであり、人間が入力したものではありません。 + +スコアリングはユーザー自身の言葉を評価の対象とします。「直して」のような短く端的な指示は怒りとして判定されません。また、質問することは困惑としてカウントされません。新しいリクエストは修正とはみなされず、感謝の言葉だけでは解決済みとしてカウントされません。 \ No newline at end of file diff --git a/docs/ja/start/use-jev.mdx b/docs/ja/start/use-jev.mdx new file mode 100644 index 000000000..41b548676 --- /dev/null +++ b/docs/ja/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Jev を使う" +description: "完了したセッションの評価に Jev evals を、ライブのツール呼び出しレビューに Jev policies を設定します。" +icon: "sparkles" +--- + +Jev はエージェント実行の 2 つのタイミングで役立ちます。完了したセッションを既知の回答と照合してスコアリングするか、エージェントへの指示のコンテキストを踏まえてツール呼び出しをレビューします。 + + + + 完了したセッションを「顧客は返金を求めましたか?はいかいいえで答えてください。」のような、いくつかの既知の回答がある質問に対してスコアリングできる場合は、Jev eval を使用します。セッション全体のパターンを発見するのに役立ちます。 + + ## eval を作成する + + Cloud ダッシュボードで **Analyze → eval authoring → new eval** を開きます。固定回答の質問を 1 つ入力し、**draft** を選択して、分類器スコアが選ばれていることを確認します。実際のセッションで[テスト](/ja/evaluations/test)してからデプロイしてください。 + + ![質問を記述し、ドラフトを確認してデプロイする共有の eval 作成フォーム。このスクリーンショットはコードドラフトを示していますが、Jev には固定回答の質問を使用してください。](/images/dashboard/eval-authoring-draft.png) + + ## スコアを確認する + + 新しいセッションが完了したら、**Observe → Evaluations** を開くか、Cloud CLI を使用します。 + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI はスコアを読み取ります。Jev eval の作成は現在ダッシュボードで行います。質問の種類と例については [Jev evaluations](/ja/evaluations/jev) を参照してください。 + + + 文字列マッチングポリシーがツール呼び出しの安全性を判断するためにリクエストのコンテキストを必要とする場合は、Jev ポリシーレビューを使用します。まず **observe** モードで開始することで、インストール済みのポリシーが各呼び出しを判断しながら Jev の回答を確認できます。 + + Jev のチェックはパックから提供されます。Failproof AI はパックを同梱していません。インストールするまで、Jev は設定されていても何も確認しません。 + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Cloud Jev を設定する + + Cloud ダッシュボードで **Administration → Keys** を開き、**machine** プリセットでキーを作成します。[クイックスタート](/ja/start/quickstart)に示されているように、`failproofai config` でそのキーを使用します。既存の Jev 設定がないマシンでは、observe モードで Cloud Jev が有効になります。接続を確認するには: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## 独自のエンドポイントを使用する + + ローカルダッシュボードで **Settings → Jev** を開きます。プロバイダーを選択し、トークンを貼り付け、**observe** を選択して Jev をオンにします。 + + ![プロバイダー、トークンフィールド、observe モードが選択されたローカルの Jev 設定パネル。](/images/dashboard/jev-settings.png) + + または、ターミナルからエンドポイントを設定してテストします。 + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + フックされたエージェントに `README.md` のファイル読み取りツールを使用させます。そのツール呼び出しがセッションに表示されることを確認し、ローカルダッシュボードの **Policies → Activity** で内容を確認します。observe の結果が正しければ、[Jev policies](/ja/policies/jev) でいつ適用するかを説明しています。プロバイダーの詳細と設定については、[インテグレーションリファレンス](/ja/reference/jev)を参照してください。 + + \ No newline at end of file diff --git a/docs/ko/admin/product-analytics.mdx b/docs/ko/admin/product-analytics.mdx new file mode 100644 index 000000000..8daab623d --- /dev/null +++ b/docs/ko/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "제품 분석" +description: "Failproof AI Cloud가 자체적으로 수집하는 사용 텔레메트리, 절대 수집하지 않는 항목, 그리고 비활성화 방법에 대해 설명합니다." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud는 유지 관리자에게 **소프트웨어 자체에 관한** 사용 텔레메트리를 전송합니다. 에이전트 데이터는 절대 포함되지 않습니다. 셀프 호스팅 설치 시 기본적으로 활성화되어 있으며, 비활성화할 수 있습니다. + +## 수집 항목 + +모든 이벤트는 다섯 가지 차원을 포함하며, 개인을 식별할 수 있는 정보는 포함하지 않습니다. + +| 차원 | 예시 | 설명 | +| --- | --- | --- | +| `product` | `agenteye` | 이벤트를 전송한 제품 | +| `component` | `dashboard`, `server`, `cli` | 이벤트를 전송한 제품의 구성 요소 | +| `app_version` | `0.0.1-beta.81` | 실행 중인 빌드 버전 | +| `deployment_kind` | `self_hosted` | 고객 설치, 데모, QA, 또는 개발 환경 여부 | +| `org_id` | UUID | 작업이 발생한 조직의 불투명 식별자 | + +이 외에도 이벤트는 **콘텐츠가 아닌 사용 현황만** 기록합니다. 예를 들어 조회한 페이지(실제 URL이 아닌 `/:org/sessions/:id`와 같은 라우트 패턴), 적용된 필터의 종류 및 수, 작업 성공 여부, 소요 시간 등이 포함됩니다. + +Slack 앱은 워크스페이스 연결 및 해제, 계정 연동, 질문 수, 차트 게시, 승인 결정, 고정 카테고리별 오류를 기록합니다. Slack 워크스페이스, 사용자, 채널 ID, 이메일, 질문, 답변, SQL, 토큰은 절대 포함되지 않습니다. + +### 조직 이름 + +불투명한 `org_id`와 함께 조직 이름, URL 슬러그, 대시보드 주소를 모든 이벤트가 아닌 조직 레코드에 한 번만 기록합니다. 이를 통해 사용 패턴이 어느 계정에 속하는지 파악하거나, 보고된 문제를 조사할 때 활용합니다. 이것이 제품이 사용자에 관해 전송하는 유일한 식별 정보입니다. + +### 사용량 합계 + +서버는 각 조직의 측정된 사용량 합계를 보고하며, 이는 사용량 페이지에서 확인할 수 있는 수치와 동일합니다. 이벤트, 세션, 에이전트, 환경, 평가 실행, 점수, 감사 실행, 저장된 쿼리, 대시보드, 알림, 이슈, API 키, 멤버 수와 측정 기간의 날짜만 포함됩니다. 식별자, 이름, 쿼리 텍스트는 포함되지 않으며, 로그인 여부와 관계없이 전송됩니다. + +## 절대 수집하지 않는 항목 + +- **프롬프트, 모델 응답, 이벤트 내용** — 텍스트, 접두사, 해시 형태 모두 포함하지 않습니다 +- **세션, 에이전트, 트레이스 식별자** +- **평가자 점수 이름** +- **오류 메시지, 예외 텍스트, 응답 본문** — 상태 코드와 고정 목록의 카테고리만 포함됩니다 +- **도구 인수, SQL, 쿼리 텍스트** +- **연결된 앱 세부 정보** — MCP 클라이언트 연결 또는 해제 시 권한 수만 전송되며, 앱 이름이나 토큰은 절대 포함되지 않습니다 +- **이메일 주소** +- **리퍼러 URL 또는 쿼리 문자열** +- **화면 녹화, DOM 캡처, 클릭 및 커서 추적** + +## 셀프 호스팅 설치에서 비활성화하기 + +대시보드와 서버 모두에 `DO_NOT_TRACK=1`을 설정하세요. 각각 독립적으로 동작하므로 한쪽에만 설정하면 나머지는 계속 보고합니다. 변경 사항을 적용하려면 서버를 재시작하세요. + +릴리스 README에는 다른 옵트아웃 설정 및 텔레메트리 비활성화 확인 방법이 설명되어 있습니다. + +## 옵트아웃 시 한 번의 핑 전송 + +`DO_NOT_TRACK` 대신 제품 설정으로 옵트아웃하면, 대시보드는 프로세스 시작 시 1/1000 확률로 이를 기록하는 **익명의 핑 하나**를 전송할 수 있습니다. 이를 통해 텔레메트리를 끄는 운영자 수를 파악합니다. 조직, 사용자, 호스트명, URL, IP 등의 식별자는 포함되지 않으며, 제품, 컴포넌트, 버전, 배포 유형, 사유만 포함됩니다. 옵트아웃된 서버는 아무것도 전송하지 않습니다. + +`DO_NOT_TRACK`을 사용하면 이 핑도 전송되지 않습니다. 조직 정책상 외부 텔레메트리 전송을 금지하는 경우 이 설정을 사용하세요. + +## 전송 대상 + +포트 443에서 TLS를 통해 PostHog(`us.i.posthog.com`)로 전송됩니다. 단일 호스트명이므로, 단일 이그레스 규칙으로 차단할 수도 있습니다. + +개인 정보 처리 방식에 대한 자세한 내용은 [개인정보 처리방침](https://befailproof.ai/privacy/)을 참조하세요. \ No newline at end of file diff --git a/docs/ko/agenteye/opentelemetry.mdx b/docs/ko/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..6cea27033 --- /dev/null +++ b/docs/ko/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "OTLP를 사용하여 코딩 에이전트 및 애플리케이션 텔레메트리를 FailproofAI Cloud로 전송합니다." +icon: "radio" +--- + +OpenTelemetry를 사용하면 표준 OTLP/HTTP 프로토콜을 통해 에이전트 트레이스, 로그, 메트릭을 FailproofAI Cloud로 전송할 수 있습니다. 선택 사항이며, 활성화하지 않아도 기존 FailproofAI 통합은 계속 정상 작동합니다. + +## 조직의 수집 기능 활성화 + +조직 관리자가 **설정 → OpenTelemetry**를 열고 수집 기능을 켭니다. 에이전트 리포팅에 사용되는 것과 동일한 `events:add` 권한을 가진 Cloud API 키를 사용하세요. + +수집 기능이 꺼져 있으면 Cloud는 OTLP 내보내기를 거부하므로, `failproofai otel enable`을 실행해도 아무 변화가 없으며 에이전트는 기존 방식으로 세션을 계속 전송합니다. `failproofai otel status`를 실행하여 조직 설정을 확인하고, 관리자에게 활성화를 요청하세요. + +## 코딩 에이전트 연결 + +`failproofai config`로 머신을 연결한 후 에이전트를 선택합니다: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +설정 명령은 Claude Code, Codex, Copilot을 지원하며, 상황에 따라 Cloud 또는 로컬 인증 릴레이를 자동으로 선택합니다. Copilot은 자동으로 로컬 릴레이를 사용합니다. 릴레이를 사용하기 전에 FailproofAI 데몬을 먼저 시작하세요. + +FailproofAI가 이미 해당 에이전트의 세션 트랜스크립트를 전송 중이라면, 설정 시 해당 에이전트를 OTEL로 전환할지 묻습니다. 기본값은 아니오입니다. 수락하면 해당 에이전트의 트랜스크립트 업로드가 중단되지만, 정책 적용이나 다른 에이전트의 리포팅에는 영향을 주지 않습니다. + +## 애플리케이션 연결 + +애플리케이션의 OpenTelemetry 계측에 다음 환경 변수를 사용하세요: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +엔드포인트는 Cloud의 OTLP 베이스 URL인 `https://app.befailproof.ai/otel`이며, 내보내기 도구가 `/v1/traces`, `/v1/logs`, `/v1/metrics`를 직접 추가합니다. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`와 같은 신호별 변수는 그대로 사용되므로, 전체 경로(예: `https://app.befailproof.ai/otel/v1/logs`)를 지정해야 합니다. + +``를 실제 API 키로 교체하세요. 시크릿이 셸 히스토리, 화면 녹화, 커밋된 설정 파일에 포함되지 않도록 주의하세요. 머신이 이미 설정된 경우, `failproofai otel env --service my-agent`를 실행하면 기존 키가 포함된 블록을 출력합니다. 출력 결과에는 자격 증명이 포함됩니다. + +Cloud는 프로토버프 또는 JSON 형식의 OTLP/HTTP 내보내기(gzip 압축 요청 포함)를 트레이스, 로그, 메트릭에 대해 허용합니다. OTLP/gRPC는 지원하지 않습니다. + +메트릭은 내보내기 도구 호환성을 위해 수신 처리되지만, 저장하거나 표시하지는 않습니다. 지원되는 에이전트 트레이스와 코딩 에이전트 로그는 세션으로 변환되며, 에이전트가 내보내지 않는 필드는 비어 있게 됩니다. + +## 프롬프트 텍스트 캡처 + + +텍스트 캡처에는 프롬프트, 도구 인수, 기타 민감한 콘텐츠가 포함될 수 있습니다. `failproofai otel enable`을 실행하면 캡처가 켜집니다. 프롬프트 및 도구 세부 정보 캡처를 끄려면 `--no-content`를 추가하세요. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +에이전트를 직접 설정하는 경우, 에이전트 고유의 콘텐츠 캡처 제어 옵션을 사용하세요: + + + + 위의 애플리케이션 블록과 함께 에이전트 환경에 다음 변수를 추가하세요: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + 프롬프트와 도구 세부 정보 캡처를 방지하려면 두 콘텐츠 변수를 모두 `0`으로 설정하세요. + + + Codex 사용자 설정에서 OTEL 설정을 사용하세요: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Codex 대화 콘텐츠는 로그에 포함됩니다. 내부 런타임 트레이스와 메트릭은 비활성화된 상태로 두세요. Codex는 제공한 전체 엔드포인트를 사용합니다. 프롬프트를 제외하려면 `log_user_prompt`를 `false`로 설정하세요. 설정 명령은 명시적인 `false` 값을 그대로 유지합니다. + + + 로컬 릴레이와 함께 Gemini의 텔레메트리 설정을 사용하세요: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI는 `failproofai otel enable`에서 지원하지 않습니다. 직접 인증된 수집기를 사용하여 수동으로 설정하세요. 프롬프트를 캡처하지 않으려면 `logPrompts`를 `false`로 설정하세요. + + + 다음 VS Code 사용자 설정을 사용하세요: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + `failproofai otel enable copilot`을 실행하여 인증된 릴레이를 활성화하세요. 콘텐츠를 제외하려면 `captureContent`를 `false`로 설정하세요. + + + +## 설정 확인 및 되돌리기 + +릴레이는 일시적인 네트워크 또는 서버 장애가 발생해도 텔레메트리를 보관하고 복구 후 재시도합니다. 저장하기에 너무 큰 이벤트를 포함하여 영구적인 `400` 거부 응답이 반환되면 페이로드를 수정해야 합니다. 릴레이는 거부된 배치를 반복 전송하지 않고 검사를 위해 보관합니다. + +`401` 또는 `403` 응답 이후에는 동일 조직에 대해 `events:add` 권한을 가진 키로 자격 증명을 교체하세요. 재연결 시 자격 증명 문제로 거부된 OTLP 내보내기는 자동으로 재전송되지 않습니다. 해당 배치 복구는 운영자에게 요청하세요. 원래 조직에서 그대로 유지해야 합니다. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status는 FailproofAI가 관리하는 설정과 외부에서 직접 설정한 텔레메트리를 구분하여 표시합니다. Disable을 실행하면 이전 관리 설정과 에이전트의 이전 트랜스크립트 업로드 선택이 복원됩니다. + + + 명령 옵션, 로컬 릴레이 설정, 문제 해결. + \ No newline at end of file diff --git a/docs/ko/evaluations/jev.mdx b/docs/ko/evaluations/jev.mdx new file mode 100644 index 000000000..9390d40c4 --- /dev/null +++ b/docs/ko/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev 평가" +description: "Jev를 사용하여 완료된 세션을 알려진 답변이 있는 질문에 대해 채점합니다." +icon: "list-checks" +--- + +Jev 평가는 **완료된 세션**을 읽고 0에서 1 사이의 점수를 부여합니다. "고객이 긴박함을 표현했는가?" 또는 "고객이 얼마나 불만족스러워했는가?"처럼 답변이 미리 알려진 경우에 활용하세요. 여러 실행에 걸친 패턴을 파악하는 데 도움이 되며, 도구 호출을 중단하지는 않습니다. 도구가 실행되기 **전**에 내리는 결정에는 [Jev 정책](/ko/policies/jev)을 사용하세요. + +## 대시보드에서 만들기 + +1. **Analyze → eval authoring**을 열고 **new eval**을 선택합니다. +2. 하나의 질문과 가능한 답변을 설명합니다. 예: "에이전트가 환불 정책을 확인하기 전에 환불을 약속했는가? yes 또는 no로 답하시오." **draft**를 선택하고 결과가 분류 점수인지 확인합니다. +3. 최근 세션에서 [테스트한 후](/ko/evaluations/test) [배포](/ko/evaluations/deploy)합니다. 새로 완료된 세션이 채점되며, 기존 기록도 필요하다면 [백필](/ko/evaluations/deploy#score-sessions-you-already-have)하세요. + +![공유 eval 작성 폼으로, 고정 답변 질문을 설명하고 초안을 검토한 뒤 테스트 후 배포합니다. 예시는 코드 평가이며, Jev 질문도 동일한 작성 흐름을 사용합니다.](/images/dashboard/eval-authoring-draft.png) + +어시스턴트는 코드, Jev 분류, [판정자(judge)](/ko/evaluations/judge) 중에서 선택할 수 있습니다. 배포 전에 선택 결과를 확인하세요. Jev는 산문 형식의 추론 없이 점수만 제공하므로, 설명이 필요한 경우에는 판정자를 선택하세요. 질문 유형과 점수 한도에 대한 자세한 내용은 [Jev 평가 레퍼런스](/ko/reference/jev-evaluations)를 참고하세요. + +## 점수 확인하기 + +**Observe → Evaluations**를 열면 에이전트별, 시간별 결과를 차트로 확인할 수 있습니다. 터미널에서는 Cloud CLI로 동일한 결과를 조회할 수 있습니다: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI는 결과를 조회하며, 작성 및 배포는 대시보드에서 이루어집니다. 필터에 대한 자세한 내용은 [Cloud CLI 레퍼런스](/ko/reference/cloud-cli#evaluations)를 참고하세요. \ No newline at end of file diff --git a/docs/ko/evaluations/judge.mdx b/docs/ko/evaluations/judge.mdx new file mode 100644 index 000000000..f1bb8e979 --- /dev/null +++ b/docs/ko/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLM 판정자" +description: "코드로는 측정할 수 없는 것들 — 정확성, 어조, 에이전트가 정책을 따랐는지 여부 — 을 세션 단위로 평가합니다. 좋은 응답이 어떤 것인지 설명하면, 모델이 대화를 읽고 점수를 매깁니다." +icon: "scale" +--- + +호스팅된 Python 평가는 숫자로 셀 수 있는 것들을 비교합니다. 도구 호출 횟수, 오류 수, 세션 소요 시간 등이 그 예입니다. 하지만 답변이 *올바른지*, 응답이 무례했는지, 에이전트가 행동하기 전에 정책을 확인했는지는 판단할 수 없습니다. + +**LLM 판정자**는 이를 판단할 수 있습니다. 좋은 응답이 어떤 것인지 평범한 언어로 설명하면, 모델이 세션을 읽고 근거와 함께 0에서 1 사이의 점수를 반환합니다. + + +판정자는 실행되는 세션마다 모델 호출 비용이 발생하지만, 코드 평가는 무료입니다. 대화 내용을 *이해*해야만 답할 수 있는 질문에만 판정자를 사용하세요. 또한 조건을 설정하여, 실제로 해당 질문이 적용되는 세션에서만 실행되도록 하세요. + + +## 어떤 것을 선택해야 할까요? + +| 질문 | 사용 방법 | +| --- | --- | +| 같은 도구를 두 번 호출했나요? | 코드 | +| 오류가 몇 번 발생했나요? | 코드 | +| 세션이 30초 미만이었나요? | 코드 | +| 고객이 긴박함을 표현했나요? | [분류자](/ko/evaluations/jev) | +| 고객의 불만 정도는 어느 수준이었나요? | [분류자](/ko/evaluations/jev) | +| 답변이 실제로 정확했나요? | **판정자** | +| 응답이 무례하거나 무시하는 태도였나요? | **판정자** | +| 환불을 약속하기 전에 환불 정책을 확인했나요? | **판정자** | + +기본 원칙: **셀 수 있는 것 → 코드, 미리 목록화할 수 있는 답변 → [분류자](/ko/evaluations/jev), 설명이 필요한 것 → 판정자.** 판정자는 본 것에 대해 산문으로 설명하는 유형입니다. 점수만으로는 "왜?"라는 질문이 나올 것 같을 때 판정자를 사용하세요. + +미리 결정하지 않아도 됩니다. 측정하고 싶은 것을 설명하면 어시스턴트가 선택하고, 어떤 것을 선택했는지와 그 이유를 알려줍니다. 나중에 변경할 수도 있습니다. + +## 작성 방법 + +1. **Analyze → eval authoring**으로 이동하여 **new eval**을 선택합니다. +2. 판정받고 싶은 내용을 설명하고, **draft**를 선택합니다. +3. **criteria**, **threshold**, **condition**을 검토한 후 배포합니다. + +### Criteria + +질문이 아닌 요구사항 형태로 한두 문장으로 작성합니다. + +> 어시스턴트는 환불 정책을 먼저 확인하지 않고 환불을 약속하거나 승인해서는 안 됩니다. + +어떤 경우에 *실패*로 판정될지 구체적으로 명시하세요. "응답이 좋았나요?"는 아무 의미 없는 숫자를 돌려줍니다. 위의 문장처럼 작성해야 실행 가능한 의미 있는 점수를 얻을 수 있습니다. + +### Threshold + +해당 점수 이상이면 세션이 통과로 처리됩니다. `0.7`이 합리적인 시작점입니다. 0에서 1 사이의 전체 점수는 항상 저장되므로, threshold는 합격/불합격만 결정합니다. 분포를 확인하고 조정할 수 있습니다. + +### Condition + +다른 평가와 동일한 Python 조건이며, 여기서는 훨씬 더 중요합니다. 조건이 없으면 판정자가 조직 내 **모든** 세션에서 실행되어, 세션마다 모델 호출 비용이 발생합니다. + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +조건 없이 판정자를 배포하면 대시보드에서 경고를 표시합니다. 소량의 세션을 가진 에이전트를 완전히 판정하고 싶은 경우처럼 의도적인 선택일 수도 있지만, 실수가 아닌 의식적인 결정이어야 합니다. + +## 판정자가 보는 것 + +대화 내용을 순서대로 보여주며, 세션이 길 경우 최신 순서로 표시됩니다. + +- 사용자가 말한 내용 +- 어시스턴트의 응답 +- **에이전트가 호출한 모든 도구와 해당 호출의 반환값(순서대로)** + +마지막 항목 덕분에 "X를 하기 *전에* Y를 했는가"라는 질문이 가능합니다. 실패한 도구 호출은 실패로 표시되므로, "오류에서 적절히 복구했는가"도 판단할 수 있습니다. + +매우 긴 세션은 모델의 컨텍스트에 맞게 잘립니다. 이 경우 추론 내용에 명시적으로 표시됩니다. 세션의 일부만 보고 판단한 결과가 전체를 본 것처럼 표시되는 일은 절대 없습니다. + +## 결과 읽기 + +판정자는 다른 점수 평가와 마찬가지로 **점수**를 생성하므로, 차트 표시, 필터링, 알림 트리거 방식도 동일합니다. 숫자와 함께 판정자의 **추론** — 본 내용을 설명하는 단락 — 도 저장됩니다. 점수가 의외일 때는 추론을 먼저 읽어보세요. 대부분 흥미로운 세션이거나 criteria를 더 구체화해야 한다는 신호입니다. + +명확한 경우에는 점수가 안정적이지만, 비트 단위로 완전히 결정론적이지는 않습니다. 경계선에 있는 단일 점수는 최종 판결이 아니라 세션을 직접 읽어보라는 신호로 받아들이세요. + +## 제한 사항 + +- **테스트는 아직 지원되지 않습니다.** 드라이 런에는 세션 할당이 없으며, 그 할당이 모델 예산 사용을 승인하는 역할을 하기 때문에 테스트 호출에 청구할 대상이 없습니다. 좁은 조건으로 배포한 후 첫 번째 결과 몇 개를 직접 확인하세요. +- **백필은 지원되지 않습니다.** 코드 평가를 수개월치 기록에 소급 적용하는 것은 무료이지만, 판정자로 하면 몇 분 만에 전체 예산을 소진할 수 있습니다. +- **criteria를 수정하면 새 버전이 게시됩니다.** 이전 점수와 새 점수는 비교할 수 없으므로, 하나의 추세선에 혼합되지 않고 별도로 보관됩니다. +- **판정자는 항상 점수를 생성합니다.** 메트릭이나 어서션은 생성하지 않습니다. + +## 예산이 소진되면 + +판정자는 조직의 모델 예산을 소비합니다. 예산이 소진되면 판정자 평가는 자동으로 실패하는 대신 명확한 이유와 함께 중단되며, **코드 평가는 정상적으로 계속 실행됩니다.** 예산을 늘리면 다음 세션부터 재개됩니다. \ No newline at end of file diff --git a/docs/ko/policies/authority.mdx b/docs/ko/policies/authority.mdx new file mode 100644 index 000000000..f56e3ca8a --- /dev/null +++ b/docs/ko/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "정책 권한" +description: "Jev 의미 평가기가 허용할 수 있는 정책 판정과 최종 판정의 범위." +icon: "scale" +--- + +FailproofAI Cloud 또는 직접 설정한 키를 통해 [Jev 정책 검토](/ko/policies/jev)를 구성하면, 게이트된 각 도구 호출은 실행 중인 정책과 Jev 양쪽에서 판단을 받습니다. Jev는 해당 호출이 실제로 무엇을 하는지, 그리고 작업을 입력한 사용자가 그것을 요청했는지 확인합니다. 각 정책의 **권한(authority)** 은 두 판단이 충돌할 때 어떻게 처리할지를 결정합니다. + +Jev를 구성하지 않은 경우 권한은 아무런 효과가 없습니다. 모든 정책은 기존 방식 그대로 적용됩니다. + +## Hard와 Reviewable + +- **Hard**가 기본값입니다. Hard 정책의 거부(deny) 또는 지시(instruct)는 최종적입니다. Jev가 이를 허용할 수 없으며, hard deny는 Jev를 기다리지 않고 호출을 즉시 차단합니다. +- **Reviewable**은 Jev가 정책의 판정을 허용할 수 있음을 의미합니다. 단, `reviewedBy`에 명시된 의미 검사를 통해서만 가능합니다. 판정은 명시된 **모든** 검사가 해당 호출에 대해 질의되었고, 각 검사가 아무것도 발견하지 못했거나 사용자가 이를 요청했다고 기록한 경우에만 허용됩니다. 사용자의 요청 없이 우려 사항을 **발견(fired)**한 검사는 해당 판정이 경고(warning)에 불과하더라도 차단을 유지합니다. 해당 도구에 적용되지 않아 Jev가 질의하지 않은 검사는 다른 검사의 결과와 무관하게 아무것도 허용하지 않습니다. 완화(softening)가 하나라도 있으면 동의로 간주됩니다. 호출이 사용자가 지시한 작업의 일부이고 그 범위를 벗어나지 않는다면, Jev는 deny를 경고로 전환하며, 그 경고가 정책의 차단을 허용하고 에이전트에게 전달됩니다. + +다음 조건이 모두 충족될 때만 정책이 reviewable이 됩니다: + +1. `authority: "reviewable"`을 선언해야 합니다. +2. `reviewedBy`가 비어 있지 않은 목록이어야 하며, 모든 항목은 설치된 팩이 선언한 Jev 검사여야 합니다. Failproof AI는 Jev 검사를 직접 제공하지 않습니다. [아래의 열여섯 가지 검사](#semantic-policy-names)는 `failproofai policies add FailproofAI/jev-policies`를 통해 제공됩니다. 검사를 선언하는 팩이 없으면 모든 정책은 hard입니다. +3. `alwaysOn`이 아니어야 합니다. 에이전트가 Failproof AI를 비활성화하지 못하도록 막는 보호 장치는 항상 hard입니다. + +그 외의 경우는 모두 hard입니다. 필드 누락, 값 오타, 비어 있거나 형식이 잘못된 `reviewedBy`, 또는 현재 머신에서 질의할 수 없는 이름이 있는 경우가 해당됩니다. 알 수 없는 이름이 있으면 해당 항목을 건너뛰는 것이 아니라 전체 선언을 hard로 만듭니다. `reviewedBy`는 "이 모든 검사가 질의되어야 하며, 어느 것도 거부해서는 안 된다"를 의미하므로, 이름을 건너뛰면 Jev가 요청한 것보다 적은 검사로 정책을 허용할 수 있게 되기 때문입니다. + +Jev가 구성된 후에는 Failproof AI가 `reviewable` 선언을 거부할 때 프로세스당 한 번씩 경고를 기록합니다. Jev가 없는 경우에는 아무 메시지도 출력하지 않습니다. 권한이 아무것도 결정하지 않기 때문입니다. `failproofai publish`는 이러한 선언이 포함된 팩의 빌드를 거부하므로, 팩 작성자는 누군가 설치하기 전에 문제를 발견할 수 있습니다. 팩이 검사를 선언하는 경우에는 팩이 선언한 검사를 기준으로, 그렇지 않은 경우에는 `FailproofAI/jev-policies`의 열여섯 가지 이름을 기준으로 `reviewedBy`를 검증합니다. + +## 권한 선언 위치 + +정책이 머신에 도달하는 각 방식에는 권한을 결정하는 고유한 위치가 있습니다: + +| 출처 | 선언 위치 | 기본값 | +| --- | --- | --- | +| 내장 정책 | 아래 표 | Reviewable로 나열된 경우를 제외하고 Hard | +| 직접 작성한 정책 파일 | `customPolicies.add`의 `authority` 및 `reviewedBy` | Hard | +| 정책 팩 | 팩 매니페스트(`failproofai-pack.json`)의 각 정책 항목 | Hard | +| 클라우드 관리 정책 | 활성 배포의 정책 할당 | Hard. 배포에서 아직 설정하지 않으므로 현재 모든 클라우드 관리 정책은 hard입니다. | + +팩이나 클라우드 관리 정책의 경우, 정책 코드 내부에 설정된 필드는 무시됩니다. 매니페스트 또는 할당이 결정합니다. 팩은 자신의 정책만 설명할 수 있습니다. 팩의 정책 이름에는 `/`를 포함할 수 없으며 팩 자체의 접두사 아래에 등록되므로, 어떤 매니페스트도 내장 정책이나 다른 팩의 정책을 reviewable로 표시할 수 없습니다. 팩의 코드가 등록하지만 매니페스트에 선언하지 않은 정책은 hard입니다. + +바이트 단위로 동일한 코드를 가진 두 팩 또는 두 클라우드 관리 정책은 하나의 아티팩트를 공유하고 하나의 정책으로 로드됩니다. 해당 정책은 모든 팩이 reviewable로 선언한 경우에만 reviewable이 되며, Jev는 그 중 어느 하나가 명시한 모든 검사를 허용해야 합니다. 하나라도 hard로 선언하거나 선언하지 않으면 hard로 유지됩니다. 팩이나 정책이 나열된 순서는 중요하지 않습니다. + +대부분의 머신은 `FailproofAI/policies` 팩에서 내장 정책을 가져오며, 해당 팩의 매니페스트에서 권한을 읽습니다. 아래의 reviewable 항목들은 해당 팩을 포함하는 릴리스가 설치된 후에 적용됩니다. 이전 릴리스에는 reviewable 항목이 없으므로 모든 정책이 hard로 유지됩니다. + +## 직접 작성한 정책에서 권한 선언하기 + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish`는 두 필드를 모두 팩 매니페스트에 복사하므로, 팩으로 게시된 정책은 작성자가 지정한 권한을 유지합니다. 선언이 적용되지 않을 경우 팩 빌드를 거부합니다. `"hard"` 또는 `"reviewable"` 이외의 값, 이름 목록이 아닌 `reviewedBy`, 또는 검사가 아닌 이름(팩이 검사를 선언하는 경우 팩 자체의 [Jev 검사](/ko/policies/publish-a-pack#jev-checks-in-a-pack), 그렇지 않은 경우 내장 검사)이 있을 때 거부합니다. + +## 내장 정책 + +의미 정책이 동일한 우려 사항을 실질적으로 다루는 경우에만 reviewable입니다. 그 외의 모든 내장 정책은 hard입니다. + +우려 사항을 다루는 것은 필요 조건이지만 충분 조건은 아니며, 두 가지 오류 방식 모두 조용히 발생합니다: + +- **한 번도 질의되지 않는 검사**는 차단을 영구적으로 만듭니다. `reviewedBy`는 논리곱(conjunction)이므로 질의되지 않은 검사는 절대 허용하지 않습니다. 따라서 정책이 매칭하는 형태에 대해 사전 조건이 발동되지 않는 검사와 짝을 이룬 정책은 절대 허용될 수 없습니다. +- **질의되었지만 발동되지 않는 검사**는 "우려 없음"으로 응답하며, 우려가 없으면 허용됩니다. 따라서 정책의 형태를 모델링하지 않는 검사와 짝을 이루면 정책을 검토하는 것이 아니라 — 해당 검사가 이해하지 못하는 입력에 대해 정확히 정책을 끄는 것입니다. + +Instruct 모드의 의미 정책은 절대 deny로 응답할 수 없지만, 차단을 유지할 수는 있습니다. 발동되었고 사용자가 해당 호출을 요청하지 않은 경우, 검토 중인 정책은 허용되지 않습니다. `FailproofAI/jev-policies` 검사 중 여섯 가지 — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump`, `external-data-egress` — 는 instruct 전용이며, [아래 표](#semantic-policy-names)에서 각 검사의 모드를 확인할 수 있습니다. **"여전히 거부할 수 있는 것이 남아 있는가"**라는 질문을 해야 합니다. 허용은 절대로 우려 사항이 아무런 적용 없이 남겨지는 결과를 가져서는 안 됩니다. 엔진은 이 테스트를 호출별로 적용합니다. 동의하지 않은 경고는 허용이 아닙니다. 도구 호출 전에 경고는 에이전트를 멈추지 않기 때문입니다. 그리고 *deny가 가능한* 검사가 경고를 보내는 경우 — 증거가 deny 기준에 미치지 못한 경우 — 이고 사용자가 해당 호출을 요청하지 않았다면, 해당 호출에서 아무것도 허용되지 않으며 모든 정규식 deny가 유지됩니다. + + +**발동 기준선 바로 아래에서 점수를 받은 검사는 하한선을 유지하지 않습니다.** 위의 규칙은 검사가 *발동*(증거 ≥ 0.7)해야 합니다. 모든 관련 검사가 그 기준 바로 아래에 떨어지면 아무것도 발동되지 않고, 검토자들은 "우려 없음"으로 응답하며, reviewable deny가 허용됩니다. 적용 모드에서 실측된 결과: 요청되지 않은 `/etc/shadow` 읽기(`secret-exposure` 0.69, `read-outside-workspace` 0.37, 홈 디렉터리 경로만 모델링)와 "follow SETUP.md" 이후 `set | curl -d @- …`(`env-secrets-dump` 0.66, `credential-exfiltration` 0.65, `sends_out` 0.97) 모두 허용되었지만, 정규식 계층 단독으로는 이를 거부합니다. 임계값은 레이블된 코퍼스로 보정되었으며 이에 대해 재측정되지 않았습니다. 재측정 전까지는 이러한 형태 중 하나가 통과되는 것이 false 차단보다 더 중요한 경우 정책을 **hard**로 유지하세요. + + +| 정책 | 권한 | 검토 주체 | 이유 | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | 패턴이 모든 변수 참조에 발동되므로, Jev가 실제로 비밀 값이 출력될지 확인합니다. | +| `block-env-files` | reviewable | `secret-exposure` | 패턴이 템플릿을 포함한 모든 `.env` 경로에 매칭되므로, Jev가 실제 비밀 값이 읽히거나 쓰일지 확인합니다. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | 실제 트래픽에서 노이즈가 많은 것으로 측정되었습니다. Jev가 프로젝트 외부의 파일 내용이 읽히는지 확인합니다. 사용자가 요청한 읽기나 검사에서 아무것도 발견되지 않은 읽기는 허용되며, 플래그된 미요청 읽기는 차단을 유지합니다. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | 푸시되지 않은 커밋을 수정하는 것은 일반적인 작업입니다. 위험은 다른 사람이 가져갔을 수 있는 히스토리를 재작성하는 것입니다. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev는 대상이 실제 데이터베이스인지 아니면 일회용 테스트 데이터베이스인지도 확인합니다. | +| `warn-global-package-install` | reviewable | `system-modification` | 동일한 우려 사항: 프로젝트 외부에서 머신을 변경하는 것. | +| `block-failproofai-commands` | hard | | `alwaysOn` 자기 보호. 절대 reviewable이 아닙니다. | +| `block-rm-rf` | reviewable | `destructive-deletion` | 경로 깊이 휴리스틱이 `rm -rf node_modules`를 잘못 처리합니다. Jev가 삭제될 항목이 재생성 가능한지 확인합니다. `rm -rf /`는 두 프로브를 모두 true로 유지합니다. | +| `block-sudo` | hard | | 권한 상승. | +| `block-curl-pipe-sh` | hard | | 인터넷에서 다운로드한 코드를 실행합니다. | +| `block-push-master` | hard | | 보호된 브랜치에 직접 푸시합니다. | +| `block-work-on-main` | hard | | `commit-on-protected-branch`가 정확히 이 우려 사항을 다루지만 instruct 모드이므로 절대 deny로 응답할 수 없으며, 다른 검사도 이를 다루지 않습니다. | +| `block-force-push` | reviewable | `git-history-rewrite` | Jev의 프로브는 매처의 상위 집합이며 `--force-with-lease`를 포함합니다. 허용되는 것은 자신의 브랜치에 강제 푸시하는 경우입니다. | +| `block-secrets-write` | reviewable | `secret-exposure` | 경로 매칭이 고정되지 않아 `src/auth/credentials.ts`가 감지됩니다. Jev가 실제 키 자료가 작성되는지 확인합니다. | +| `block-kubectl` | reviewable | `production-infra-change` | 읽기 전용 하위 명령을 포함한 전체 CLI를 거부합니다. Jev가 호출이 변경을 수행하는지, 대상이 프로덕션인지 확인합니다. | +| `block-terraform` | reviewable | `production-infra-change` | 동일: `terraform plan`과 `validate`를 허용합니다. | +| `block-aws-cli` | reviewable | `production-infra-change` | 동일: `aws s3 ls`, `aws sts get-caller-identity`를 허용합니다. | +| `block-gcloud` | reviewable | `production-infra-change` | 동일: `gcloud auth list`, `gcloud config list`를 허용합니다. | +| `block-az-cli` | reviewable | `production-infra-change` | 동일: `az account show`를 허용합니다. | +| `block-helm` | reviewable | `production-infra-change` | 동일: `helm list`, `helm status`를 허용합니다. | +| `block-gh-pipeline` | hard | | 파이프라인, 병합 및 비밀 변경을 트리거합니다. | +| `warn-git-stash-drop` | hard | | 스태시된 작업 삭제를 다루는 의미 검사가 없습니다. | +| `warn-git-clean` | hard | | `destructive-deletion`이 우려 사항을 다루지만 발동될 수 없음이 명백합니다. `git clean`은 경로를 명시하지 않으므로 `irreplaceable` 프로브가 판단할 것이 없어 낮은 값으로 응답하며, 증거는 정책의 프로브 중 최솟값입니다. 질의되었지만 발동되지 않는 검사는 판정을 허용하므로, 여기서 짝을 이루면 정책이 꺼집니다. | +| `warn-all-files-staged` | hard | | 광범위한 `git add`가 선택하는 항목을 다루는 의미 검사가 없습니다. | +| `warn-schema-alteration` | hard | | `database-destruction`은 데이터 삭제를 다루며, 스키마 변경은 다루지 않습니다. | +| `warn-package-publish` | hard | | 게시는 되돌릴 수 없으며 이를 다루는 의미 검사가 없습니다. | +| `prefer-package-manager` | hard | | 팀 규약이지, 안전 판단이 아닙니다. | +| `warn-large-file-write` | hard | | 크기 임계값이지, Jev가 판단할 수 있는 것이 아닙니다. | +| `warn-background-process` | hard | | 분리된 프로세스를 다루는 의미 검사가 없습니다. | +| `warn-repeated-tool-calls` | hard | | 호출을 카운트합니다. Jev는 카운트할 수 없습니다. | +| `sanitize-jwt` | hard | | 도구 출력을 편집합니다. 도구 호출 게이트가 아닙니다. | +| `sanitize-api-keys` | hard | | 도구 출력을 편집합니다. 도구 호출 게이트가 아닙니다. | +| `sanitize-connection-strings` | hard | | 도구 출력을 편집합니다. 도구 호출 게이트가 아닙니다. | +| `sanitize-private-key-content` | hard | | 도구 출력을 편집합니다. 도구 호출 게이트가 아닙니다. | +| `sanitize-bearer-tokens` | hard | | 도구 출력을 편집합니다. 도구 호출 게이트가 아닙니다. | +| `require-commit-before-stop` | hard | | 세션 완료 게이트이지, 도구 호출 게이트가 아닙니다. | +| `require-push-before-stop` | hard | | 세션 완료 게이트이지, 도구 호출 게이트가 아닙니다. | +| `require-pr-before-stop` | hard | | 세션 완료 게이트이지, 도구 호출 게이트가 아닙니다. | +| `require-no-conflicts-before-stop` | hard | | 세션 완료 게이트이지, 도구 호출 게이트가 아닙니다. | +| `require-ci-green-before-stop` | hard | | 세션 완료 게이트이지, 도구 호출 게이트가 아닙니다. | + +## Semantic policy names + +이것들은 `FailproofAI/jev-policies`가 선언하는 검사이며, 설치 후 `reviewedBy`가 허용하는 값입니다. Failproof AI 자체는 이들 중 아무것도 제공하지 않습니다. 해당 팩(또는 이 이름들을 선언하는 다른 팩) 없이는 이를 명시하는 어떤 정책도 reviewable이 되지 않습니다. 각각은 Jev가 앞에 놓인 도구 호출에 대해 응답하는 검사입니다. **모드**는 검사가 응답할 수 있는 내용입니다. `deny` 검사는 강한 증거에서 차단하고, `instruct` 검사는 경고만 합니다. 발동되었고 사용자가 호출을 요청하지 않은 경우, 두 모드 모두 정책의 deny를 유지합니다. **사용자가 재정의 가능**은 사람의 명시적 요청이 이를 허용하는지 여부입니다. + +Jev는 설치된 팩이 선언한 [Jev 검사](/ko/policies/publish-a-pack#jev-checks-in-a-pack)만 질의하며, 그것이 `reviewedBy`가 허용하는 이름입니다. 두 팩이 서로 다르게 선언한 이름은 어느 쪽에도 적용되지 않습니다. FailproofAI 저장소에서 설치되지 않은 팩이 선언한 이 열여섯 가지 이름 중 하나는 해당 팩에서 무시됩니다. 해당 버전은 질의되지 않으며 FailproofAI 자체 버전과 경쟁하지 않습니다. 따라서 서드파티 팩은 코어 팩의 정책을 허용하는 검사가 될 수 없으며, 이 검사 중 하나를 끌 수도 없습니다. 읽을 수 없는 팩 목록이나 모든 검사가 사용 불가능한 팩은 Jev가 질의할 것을 남기지 않습니다. + +| 이름 | 모드 | 사용자 재정의 가능 | Jev가 확인하는 것 | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | 예 | 재생성할 수 없는 데이터를 영구적으로 삭제하는 것. | +| `production-infra-change` | deny | 예 | 라이브 인프라를 변경하는 것. | +| `git-history-rewrite` | deny | 예 | 공유된 git 히스토리를 재작성하거나 삭제하는 것. | +| `push-to-protected-branch` | instruct | 예 | 보호된 브랜치에 직접 푸시하는 것. | +| `commit-on-protected-branch` | instruct | 예 | 보호된 브랜치에 직접 커밋하는 것. | +| `secret-exposure` | deny | 예 | 자격 증명을 읽거나 복사하는 것. | +| `credential-exfiltration` | deny | 아니오 | 비밀이나 개인 파일을 머신 외부로 전송하는 것. | +| `remote-code-execution` | deny | 예 | 인터넷에서 다운로드한 코드를 실행하는 것. | +| `privilege-escalation` | deny | 예 | 상승된 권한으로 실행하는 것. | +| `database-destruction` | deny | 예 | 데이터베이스 데이터를 파괴하거나 대량 수정하는 것. | +| `read-outside-workspace` | instruct | 예 | 프로젝트 외부의 파일을 읽는 것. | +| `agent-config-tampering` | deny | 아니오 | 에이전트 자신의 안전 구성을 변경하는 것. | +| `system-modification` | instruct | 예 | 프로젝트 외부에서 시스템을 변경하는 것. | +| `env-secrets-dump` | instruct | 예 | 환경 비밀을 출력하는 것. | +| `external-destructive-action` | deny | 예 | 외부 도구를 통한 되돌릴 수 없는 작업. | +| `external-data-egress` | instruct | 예 | 외부 도구로 개인 데이터를 전송하는 것. | \ No newline at end of file diff --git a/docs/ko/policies/jev-byok.mdx b/docs/ko/policies/jev-byok.mdx new file mode 100644 index 000000000..42cef1911 --- /dev/null +++ b/docs/ko/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev 평가기 (자체 키 사용)" +description: "TypeSafe의 Jev 분류기가 정규식 필터를 기반으로 에이전트의 도구 호출을 판단하도록, 본인 소유의 Jev 엔드포인트와 키를 사용합니다." +icon: "key-round" +--- + +정규식 정책은 문자열을 매칭합니다. `rm -rf build/`처럼 직접 요청한 명령과 계획에 슬며시 끼어든 `rm -rf ~`를 구분하지 못하기 때문에, 한쪽에서는 지나치게 많이 차단하고 다른 쪽에서는 너무 적게 차단합니다. TypeSafe의 분류기인 **Jev**는 실제로 요청한 내용을 기준으로 호출을 읽고, 빠른 단일 요청으로 일련의 예/아니오 질문에 답합니다. + +본인 소유의 Jev 엔드포인트와 키를 구성하면, Failproof AI는 정규식 정책을 대체하는 것이 아니라 **함께** 각 도구 호출에 대해 Jev에 질의합니다: + +- **하드** 정책의 차단은 최종적입니다. Jev가 이를 해제할 수 없습니다. 검토 가능으로 명시되고 이를 커버하는 Jev 검사를 명시하지 않는 한 모든 정책은 하드입니다. 따라서 아무 내용도 명시하지 않은 커스텀, 팩, Cloud 정책은 하드이며, 항상 활성화된 자기 보호 가드도 항상 하드입니다. +- **검토 가능** 정책의 차단은 해제될 수 있지만, Jev가 해당 정책이 다루는 정확한 우려 사항에 대해 질의받고 "여기 없음" 또는 "사용자가 이를 요청함"이라고 답한 경우에만 가능합니다. 사용자가 해당 호출을 요청하지 않았는데 해당 우려 사항이 실재한다고 판단하는 검사는, 그 자체 판정이 경고에 불과하더라도 차단을 유지합니다. 도구 호출 이전 단계에서 경고는 에이전트를 중단시키지 않기 때문입니다. 그리고 그 검사가 차단 가능한 종류(비밀 노출, 자격 증명 유출, 파괴적 삭제 등)인 경우, 해당 호출에 대해서는 아무것도 해제되지 않습니다. +- 해당 호출이 부여한 작업의 단계이고 그 이상으로 나아가지 않는 경우, 차단은 여전히 **경고**로 완화될 수 있습니다. Jev는 자신의 차단을 경고로 완화하고, 그 경고—호출의 실제 문제를 명시하는—가 정책의 차단을 대체합니다. +- Jev는 정규식으로 설명되지 않는 피해에 대해 자체적으로 경고하거나 차단할 수도 있습니다. +- Jev가 답할 수 없는 경우(타임아웃, 속도 제한, 서버 오류, 크레딧 부족, 예상치 못한 모델 버전), 해당 호출은 Jev 없이와 정확히 동일한 정규식 결과를 받습니다. +- Jev는 전체 호출을 읽고 정확한 우려 사항에 대해 질의받지 않는 한, 정책만 있을 때보다 호출을 더 허용적으로 만들지 않습니다. 그 이하—전체를 전송하기에 너무 큰 호출, 주입 의심—는 모든 해제를 취소하고 모든 차단을 유지합니다. + + +Jev 설정이 없으면 아무것도 변경되지 않습니다: 훅은 항상 그래왔듯이 정규식 정책을 정확히 실행합니다. 설정이 곧 전체 옵트인입니다. + + + +FailproofAI Cloud를 사용 중이신가요? 본인 소유의 키가 필요하지 않습니다: `jev:evaluate`를 포함한 키로 연결된 머신은 조직 플랜에서 Jev를 사용할 수 있습니다. [FailproofAI Cloud를 통한 Jev](/ko/policies/jev-cloud)를 참조하세요. + + +## 공급자 선택 + +Jev는 다섯 가지 경로를 통해 접근할 수 있습니다. 그 중 하나에 대한 키를 준비하세요. + +| 공급자 | `--provider` | 엔드포인트 | 기본 모델 | 비고 | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | 정확한 버전 고정. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | 요청은 제로 데이터 보존 엔드포인트로만 라우팅되며, 다른 공급자로의 폴백은 없습니다. `typesafe/jev-1.13-20260917`과 같은 날짜 포함 버전을 보고합니다. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | 별칭으로만 Jev를 명명하므로, 응답 버전은 미검증으로 기록됩니다. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` 필요. 키당 초당 약 6회 호출이 HTTP 429 이전까지 측정되었습니다. | +| 자체 엔드포인트 | `custom` | `/systemone` | `jev-1.13.0` | TypeSafe의 요청 본문을 수용하고 어떤 모델이 응답했는지 보고하는 모든 엔드포인트. `https`만 가능; 섀도우 모드에서만 일반 `http://localhost`가 허용됩니다. | + + +Vercel의 자체 bring-your-own-key 기능을 사용하면, 실패한 요청이 Vercel의 자격 증명으로 자동 재시도됩니다. 모든 호출이 본인의 TypeSafe 계정에만 청구되고 보여야 한다면, TypeSafe를 직접 사용하세요. + + +## 설정하기 + +명령 하나로 엔드포인트와 키를 설정합니다: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL이 공급자를 결정합니다 + +공급자를 명시할 필요가 없습니다: URL의 **호스트**가 공급자를 결정합니다. + +| URL 호스트 | 공급자 | 추가 필요 사항 | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| 기타 모든 호스트 | `custom` | — 입력한 URL이 기본 URL이 됩니다 | + +이로부터 세 가지가 따릅니다: + +- **공급자 자체 API URL은 오버라이드를 기록하지 않습니다.** `--url https://api.typesafe.ai/v1`은 `--provider typesafe`와 정확히 동일한 설정을 생성합니다. 알려진 공급자에서 다른 경로나 호스트를 지정하면 `--base-url`이 저장하는 것처럼 기본 URL로 저장됩니다. +- **`--provider`는 여전히 추론을 오버라이드합니다.** 이는 본인 소유 호스트에서 공급자의 API를 사용하는 프록시에 접근하는 방법입니다: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **호스트와 모순되는 `--provider`는 거부됩니다.** 추측하지 않습니다. `--provider openrouter --url https://api.typesafe.ai/v1`은 아무것도 기록하지 않고 이유를 설명합니다: 두 지정이 키가 전송될 위치에 대해 일치하지 않습니다. `jev setup --base-url`과 대시보드의 Jev 설정에서도 동일한 쌍이 거부됩니다. (`--provider custom`은 모순이 아닙니다—"이 URL을 그 자체로 처리"를 의미합니다—단 계정별 엔드포인트에 커스텀 경로가 도달할 수 없는 Cloudflare 호스트는 제외.) + +`--url`은 설정 파일의 `baseUrl`과 정확히 동일하게 검증되며, 동일한 메시지로 거부됩니다: `https`, 또는 섀도우 모드에서만 `http://localhost`가 허용됩니다. + +### 키 + +`--key-stdin`으로 파이프하거나, 터미널에서 해당 플래그 없이 명령을 실행하고 마스킹된 프롬프트에서 키를 붙여넣으세요. 어느 방식이든 키는 바로 설정 파일에 저장되며 다시 출력되지 않습니다. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup`은 동일한 플래그를 사용하며, URL 대신 공급자를 명시하려는 경우 `setup --provider `를 사용하는 전체 표기입니다. + +### `--token`과 비용 + +`--token `은 명령줄에 키를 입력하는 방식으로, 머신을 구성하는 가장 빠른 방법이지만 설정 파일 외의 위치에 키를 남기는 유일한 표기입니다: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +명령줄 인수는 이후 셸의 히스토리 파일에 남으며, 명령이 실행되는 동안 프로세스 목록에 있어 `/proc`에서 본인으로 실행 중인 모든 것이 읽을 수 있습니다. `setup`은 `--token`이 사용될 때마다 이를 알립니다. 공유 머신이나 녹화된 세션, 또는 히스토리 파일이 동기화되는 환경에서는 `--key-stdin`을 사용하고, 이 방식으로 전달한 키는 중요하다면 교체하세요. + + +`--token`, `--key-stdin`, `--key-from-env`는 상호 배타적입니다: 하나만 사용하세요. + +그런 다음 키, 엔드포인트, 응답한 Jev를 확인하기 위해 작은 실시간 요청을 전송합니다: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test`는 응답이 타임아웃 이후에 도착하거나(`timeout`으로 모든 훅이 정규식으로 폴백) 검사 질문에 잘못 답하면 제목에 표시하고 종료 코드 1로 종료합니다. + +훅은 모든 도구 호출마다 설정을 읽으므로 다음 호출부터 적용됩니다. 데몬 유무에 관계없이 재시작이 필요하지 않습니다. + +## 동작 확인 + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status`는 공급자, 엔드포인트, 모델, 모드, 설정 파일과 그 권한을 표시하며 키는 절대 표시하지 않습니다. 그 아래에는 최근 활동을 요약합니다: Jev가 평가한 호출 수, 정규식으로 폴백한 빈도와 이유, 지연 시간, 해제된 검토 가능 정책. + +## 섀도우 모드 + +`enforce`가 기본값입니다. Jev가 어떤 결정도 변경하지 않으면서 동작을 관찰하려면 `shadow`로 전환하세요: Jev는 여전히 질의받고 그 판정이 기록되지만, 실제로 적용되는 것은 정규식 결과입니다. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off`는 설정—엔드포인트와 키—을 유지하고 Jev 질의를 중단합니다: 훅은 설정 없이와 정확히 동일하게 정규식 정책을 실행하며, `failproofai jev status`는 "off (switched off)"를 표시합니다. `--mode shadow` 또는 `--mode enforce`로 다시 전환할 수 있습니다. + +동일한 공급자에 대해 `setup`을 재실행하면 저장된 키가 유지되므로 모드 전환은 플래그 하나로 됩니다. 공급자를 전환하면 처음부터 시작하고 해당 공급자의 키를 요청합니다. 요청을 다른 호스트로 이동하는 `--base-url`도 마찬가지입니다: 저장된 키는 제공된 호스트 또는 해당 공급자의 자체 API로만 전송됩니다. + +## 설정 파일 + +모든 것이 `~/.failproofai/jev.json` 하나의 파일에 저장되며, `setup`이 작성합니다: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| 필드 | 의미 | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare`, `custom` 중 하나—또는 `failproofai`로, 이 파일 대신 FailproofAI Cloud 연결에서 키를 가져옵니다([FailproofAI Cloud를 통한 Jev](/ko/policies/jev-cloud) 참조). | +| `apiKey` | `Authorization: Bearer `로 전송됩니다. | +| `baseUrl` | `custom`에 필요; 그 외에는 공급자의 API 기본값을 대체합니다. `https`여야 합니다. `localhost`에 대한 일반 `http`는 `mode: shadow`에서만 허용됩니다: 로컬 포트를 인증하는 것이 없으므로, 프록시가 다운된 동안 에이전트를 포함한 머신의 모든 프로세스가 대신 응답할 수 있습니다. | +| `accountId` | Cloudflare 전용: 32자 소문자 16진수. | +| `model` | 공급자의 기본 모델 ID를 대체합니다. 버전이 지정된 ID는 Jev 1.13을 명명해야 합니다. API 키처럼 생긴 값은 거부되며(반복 출력되지 않음), `--model`에 붙여넣은 키는 절대 저장되거나 모델로 전송되지 않습니다. | +| `timeoutMs` | 도구 호출이 정규식 결과를 사용하기 전에 Jev를 기다리는 시간. 100–10000, 기본값 3000. | +| `mode` | `enforce`(기본값), `shadow`, 또는 `off`(설정 유지, Jev 실행 없음). | + +세 가지 규칙이 이를 보호합니다: + +- **소유자 전용.** 권한 `0600`으로 작성됩니다. 다른 사용자나 그룹이 읽거나 쓸 수 있는 복사본은 **거부**되며, `chmod 600 ~/.failproofai/jev.json`을 실행하거나 `setup`을 다시 실행할 때까지 훅은 정규식으로 폴백합니다. 디렉토리도 확인됩니다: `~/.failproofai`는 다른 사람이 **쓸 수 없어야** 합니다. 거기에 쓸 수 있는 사람은 파일 자체의 권한에 관계없이 파일을 교체할 수 있기 때문입니다. `setup`은 그런 쓰기 비트를 발견하면 제거합니다. `failproofai jev status`는 설정이 거부되었을 때 표시하고 파일이 명명하는 엔드포인트를 보여줍니다: 다른 사람이 변경했을 수 있으므로, `chmod` 전에 본인 것인지 확인하세요. 이런 파일에서 `setup`을 재실행하면 저장된 키는 공급자 자체 API로만 전달됩니다; 파일이 명명하는 다른 엔드포인트는 키를 다시 요구합니다(`--key-stdin`), 또는 `--base-url default`로 공급자로 요청을 돌려보내세요. +- **전역 전용.** 저장소는 Jev를 켜거나, 다른 엔드포인트로 지정하거나, 모델을 선택할 수 없습니다: 프로젝트 내 `.failproofai/jev.json`은 무시되며, 공급자, URL, 모델, 계정 ID는 그 파일에서만 읽히고—저장소의 에이전트 설정이 설정할 수 있는 환경에서는 절대 읽히지 않습니다. (`FAILPROOFAI_HOME`은 우회 방법이 아닙니다: Jev만 리디렉션하는 것이 아니라 정책을 포함한 전체 failproofai 디렉토리를 이동합니다.) +- **키만 환경에서 올 수 있습니다.** 파일에 `apiKey`가 없으면, `FAILPROOFAI_JEV_API_KEY`가 해당 세션에 대해 제공합니다(`setup --key-from-env`는 이런 파일을 작성합니다). 파일이 보유한 키를 절대 대체하지 않으며, 파일 없이 Jev를 켤 수 없습니다. 변수가 설정되지 않은 경우, Jev는 해당 셸에서 단순히 꺼집니다: `failproofai jev status`는 이를 표시하고, 종료 코드 0으로 종료하며 설정을 그대로 둡니다(`status --json`은 `"reason": "no-env-key"`와 함께 `"status": "key-missing"`을 보고합니다). `failproofaid` 데몬은 셸의 환경을 보지 못하므로, `failproofai config`로 설정된 머신에서는 파일에 키를 보관하세요. + +## 어떤 Jev가 응답하는가 + +Failproof AI의 결정 임계값은 Jev 1.13에 맞춰 조정되었으므로, 해당 계열에서 온 경우에만 답변이 사용됩니다: `jev-1.13.x`, 또는 OpenRouter의 `typesafe/jev-1.13-`. 공급자가 별칭으로만 Jev를 명명하고 버전을 보고하지 않는 경우(Vercel, 그리고 버전을 명시하지 않는 Cloudflare), 답변은 사용되고 미검증으로 기록됩니다. `custom` 엔드포인트는 응답한 모델을 보고해야 합니다; 단 하나의 예외는 설정한 버전 없는 `--model` 이름으로, 이것이 그대로 반환되면 동일하게 미검증으로 기록됩니다. 다른 버전을 보고하는 답변이나 버전을 보고하지 않는 `custom` 답변은 사용되지 않습니다: 해당 호출은 `model-mismatch` 이유로 정규식으로 폴백합니다. + +## Jev가 답할 수 없을 때 + +다음 각각은 해당 호출에 대해 정규식 결과로 폴백하고 이유와 함께 기록되며, `failproofai jev status`가 집계합니다: + +| 이유 | 원인 | +| --- | --- | +| `timeout` | `timeoutMs` 내에 답변 없음. | +| `http-429` | 공급자가 키를 속도 제한함. | +| `rate-limited` | Failproof AI 자체 제한기가 전송 전에 호출을 보류함: 초당 5회, 최대 5회 버스트, 공급자가 `429`를 반환한 후 잠시 없음. 공급자가 아님. | +| `http-500`, `http-502`, `http-503`, … | 공급자의 서버 오류. 정확한 상태가 기록됩니다. | +| `out-of-credits` | HTTP 402: 공급자 계정에 크레딧이 없음. | +| `provider-refused` | Cloudflare에서 "Model execution failed (Payment error)"를 읽는 HTTP 402: 공급자가 이 요청에 대해 모델 실행을 거부함. 보통 청구 문제가 아니므로 크레딧 충전으로 해결되지 않습니다. | +| `http-401`, `http-403` | 키가 거부됨. | +| `http-404` | `/systemone`에 아무것도 서빙되지 않으므로 기본 URL이 잘못됨—`/systemone`이 기본 URL에 추가되며, 모든 공급자는 버전 루트에서 서빙합니다. `failproofai jev models`는 엔드포인트가 실제로 서빙하는 것을 보여줍니다. | +| `network` | 엔드포인트에 연결할 수 없음. | +| `http-301`, `http-302`, `http-307`, `http-308` | 엔드포인트가 리디렉션으로 응답함. 리디렉션은 절대 따르지 않으므로, 답변은 설정의 URL에서만 옵니다; `--base-url`을 최종 URL로 설정하세요. | +| `malformed` | 엔드포인트가 응답했지만 Jev 답변이 아님—JSON이 아닌 본문, 또는 답변이 없는 본문. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare의 엔벨로프가 실패를 보고하거나, 완료되지 않은 작업. | +| `model-mismatch` | 1.13 외의 Jev 버전이 응답하거나, `custom` 엔드포인트가 응답한 모델을 명시하지 않음. | +| `request-cut` | **장애가 아님.** Jev가 응답했지만 호출의 일부만 보여졌으므로 답변이 아무것도 해제하지 않음. [Jev가 답했지만 전체 호출이 아닌 경우](#when-jev-answered-but-not-on-the-whole-call) 참조. | + +`failproofai jev status`는 `upstream-error`(답변에 공급자 자체 오류가 포함됨) 또는 `config` 같은 드문 이유도 표시할 수 있으며, 명명할 수 없는 이유는 `other`로 합산합니다. + +`request-cut`은 `failproofai jev status`가 나머지와 함께 집계하고, 이 역시 모든 차단을 유지하기 때문에 이 표에 있습니다. 공급자에 대해 아무것도 말하지 않는 유일한 이유입니다: 요청이 도착했고 Jev가 응답했습니다. 위의 모든 행과 달리, 그 답변은 여전히 계산됩니다—Jev 자체의 차단이나 경고가 폐기되는 대신 정규식 결과 위에 적용됩니다. 따라서 연속적으로 발생한다면 호출이 전체를 전송하기에 너무 크게 평가기에 도달하고 있다는 의미이며, 엔드포인트가 문제가 있다거나 크레딧을 충전하거나 URL을 변경해서 해결될 문제가 아닙니다. + +## Jev가 답했지만 전체 호출이 아닌 경우 + +두 가지 더 발생할 수 있으며, 둘 다 Jev가 답에 실패한 것이 아닙니다. 둘 다 호출 또는 대화의 얼마나 많은 부분이 하나의 요청에 맞는지에 관한 것입니다. + +**호출 자체의 일부가 맞지 않음.** 도구 호출은 고정된 예산 내에서 전송되며, 과도하게 큰 것—매우 큰 `Write`, 거대한 MCP 본문, 한도까지 채워진 명령—은 맞는 부분만 전송됩니다. Jev는 여전히 응답하고 그 답변은 여전히 계산됩니다: 자체 차단이나 경고가 평소대로 적용됩니다. 할 수 없는 것은 **해제**입니다. 호출의 일부에 대한 판정은 호출 전체에 대한 판정이 아니기 때문입니다. 따라서 모든 정책 차단이 유지되고, 호출은 `request-cut` 이유로 폴백으로 기록되며 `failproofai jev status`가 위의 이유들과 함께 집계합니다. 이 규칙이 의미하는 것: 호출을 더 크게 만드는 것은 해제를 잃을 수 있고, 해제를 살 수는 없습니다. + +**메시지가 맞지 않음.** 붙여넣은 긴 프롬프트, 에이전트의 마지막 메시지, 또는 이 평가기의 자체 저장소가 이미 한도를 초과한 프롬프트. **아무것도 변경되지 않습니다**: 호출은 다른 것과 정확히 동일하게 판단되고, 해제되고, 기록되며 폴백으로 계산되지 않습니다. 타이핑하는 내용의 길이는 절대 판정을 결정하지 않으며, 잘림이 동의를 만들 수 없습니다: 프롬프트가 이미 한도 초과된 상태로 도착한 경우, "당신이 이를 요청하지 않았다"는 결론을 전혀 도출할 수 없게 됩니다. + +둘의 경계는 누가 텍스트를 작성했는지입니다. 호출은 에이전트의 것이며, 길이가 심각성을 줄이는 규칙은 에이전트가 사용할 수 있는 규칙이 됩니다; 프롬프트는 본인 것이며, 그 길이를 신호로 취급하면 사양이나 스택 트레이스를 붙여넣는 것에만 불이익을 줄 뿐입니다. + +## 머신에서 나가는 것 + +Jev가 평가하는 각 도구 호출에 대해, 하나의 요청이 공급자로 전송되며 다음을 포함합니다: + +- API 키, 베어러 토큰, `KEY=` 할당 등의 비밀이 편집된 도구 호출 자체; +- 에이전트 하네스가 추가한 텍스트가 제거된 최근에 타이핑한 프롬프트; +- 최신 프롬프트 이전 에이전트의 마지막 메시지, 에이전트 작성으로 표시; +- 경로가 프로젝트 내에 있는지 여부 등 로컬에서 계산된 사실—첫 번째 검토된 호출 시 세션이 있던 위치로, [세션에 고정](/ko/reference/jev-intent#the-project-root)됨—및 현재 git 브랜치. + +설정의 엔드포인트로만, 본인 키 아래에서 전송됩니다. + +## 끄기 + +```bash +failproofai jev remove +``` + +이것은 `~/.failproofai/jev.json`을 삭제합니다. 다음 도구 호출부터 훅은 이전과 정확히 동일하게 정규식 정책을 실행합니다. `~/.failproofai/state/semantic/` 아래의 세션별 저장소(`sessions/`의 기록된 프롬프트, `roots/`의 프로젝트 루트)는 그대로 두고 자연히 만료됩니다. Jev 질의를 중단하되 설정을 유지하려면 대신 `failproofai jev setup --mode off`를 사용하세요. + +## 명령 참조 + +| 명령 | 결과 | +| --- | --- | +| `failproofai jev --url --key-stdin` | 명령 하나로 구성; 공급자는 URL의 호스트에서 결정 | +| `failproofai jev --url --token ` | 동일하지만 명령줄에 키를 입력—히스토리와 프로세스 목록에서 볼 수 있음 | +| `failproofai jev setup --provider --key-stdin` | stdin으로 파이프된 키로 설정 작성 | +| `failproofai jev setup --provider ` | 동일하지만 마스킹된 프롬프트에서 키 요청 | +| `failproofai jev setup --key-from-env` | 키를 저장하지 않음; 세션당 `FAILPROOFAI_JEV_API_KEY` 읽기 | +| `failproofai jev setup --mode shadow` | 저장된 키를 유지하며 모드 전환(`enforce`, `shadow` 또는 `off`) | +| `failproofai jev setup --model ` / `--base-url ` | 모델 또는 API 기반 오버라이드; `default`는 오버라이드 해제 | +| `failproofai jev setup --timeout-ms ` | 호출당 예산 변경 | +| `failproofai jev status [--json]` | 설정, 권한 및 최근 활동; 키 제외 | +| `failproofai jev test [--json]` | 실시간 요청 하나: 지연 시간 및 응답한 버전 | +| `failproofai jev models [--provider ] [--url ] [--json]` | 해당 엔드포인트의 `/models`가 보고하는 모델 ID, 구성된 것을 표시 | +| `failproofai jev remove` | 설정 삭제; Jev 꺼짐 | \ No newline at end of file diff --git a/docs/ko/policies/jev-cloud.mdx b/docs/ko/policies/jev-cloud.mdx new file mode 100644 index 000000000..816918ae6 --- /dev/null +++ b/docs/ko/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "FailproofAI Cloud를 통한 Jev" +description: "별도의 TypeSafe 계정이나 키 없이, 조직의 플랜으로 FailproofAI Cloud를 통해 Jev가 에이전트의 도구 호출을 판별하게 하세요." +icon: "cloud" +--- + +[Jev](/ko/policies/jev-byok)(TypeSafe의 분류기)는 각 도구 호출을 실제로 요청한 내용과 대조해 읽고, 정책과 함께 답을 제공합니다 — 정책을 대체하는 것이 아닙니다. **FailproofAI Cloud**를 통하면, 연결된 머신은 이미 연결에 사용 중인 키로 Jev를 사용합니다: TypeSafe 계정도, 별도의 키도, 설정할 엔드포인트도 필요 없습니다. 각 호출은 조직의 기존 플랜 허용량에서 차감됩니다. + +Jev의 모든 동작은 [자체 키 사용 설정](/ko/policies/jev-byok)과 동일합니다: 하드 정책은 항상 최종 결정이며, 검토 가능한 정책의 deny는 해당 우려 사항에 대해 Jev에게 정확히 질의했을 때만 해제되고, 오류가 발생하면 해당 호출의 정규식 결과로 폴백됩니다. + + +**failproofai 1.0.8-beta.0** 이상이 필요합니다. 1.0.7에는 Jev가 없습니다 — 1.0.7 베타 버전보다 정렬상 위에 표시되더라도 마찬가지입니다. Jev 설정이 없으면 아무것도 바뀌지 않습니다: 훅은 항상 해왔던 것처럼 정규식 정책을 그대로 실행합니다. + + +## 활성화하기 + +1. **Jev가 포함된 키를 생성합니다.** FailproofAI Cloud 대시보드에서 **Keys → Create key**를 열고 **machine** 프리셋을 선택합니다. 머신에 필요한 세 가지 권한을 부여합니다: `events:add`(활동 전송), `policies:pull`(정책 수신), `jev:evaluate`(Jev, 조직 플랜에서 차감). 키는 나머지 두 권한 없이는 `jev:evaluate`를 가질 수 없습니다. +2. 해당 키로 **머신을 연결**합니다: + + ```bash + failproofai config --token + ``` + + 조직이 호스팅된 서비스가 아닌 자체 FailproofAI Cloud를 운영하는 경우 주소를 추가하세요: `--url https://` (또는 `FAILPROOFAI_CLOUD_URL` 환경 변수 사용). 지정하지 않으면 키가 호스팅 서비스에서 확인되어 연결이 실패합니다. 해당 호스트의 인증서가 사설 CA에서 발급된 경우, CA를 머신의 시스템 신뢰 저장소에 설치하세요(예: `update-ca-certificates` 사용) — `NODE_EXTRA_CA_CERTS`에만 설치하는 것은 충분하지 않습니다: 이벤트를 전송하고 정책을 가져오는 데몬은 시스템 저장소를 읽습니다. [문제 해결](/ko/reference/troubleshooting)을 참조하세요. + +이게 전부입니다. 연결하면 키가 저장되고, 머신에 Jev 설정이 **없는** 경우 FailproofAI Cloud를 통해 **shadow** 모드로 Jev가 활성화됩니다: Jev는 모든 게이팅된 도구 호출에 대해 질의되고 판결이 기록되지만, 실제로 적용되는 것은 정책의 결과입니다. 출력에 이 내용이 표시됩니다: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**`--no-transcripts`를 사용하면 연결 시 Jev가 활성화되지 않습니다.** Jev는 확인된 각 도구 호출과 최근 프롬프트를 FailproofAI Cloud로 전송하는데, 이는 결정 사항만 전송하도록 요청된 연결보다 더 많은 데이터입니다. 키는 여전히 저장되며, 출력에는 Jev가 사용 가능하고 활성화 방법이 표시됩니다: + +```bash +failproofai jev setup --provider failproofai +``` + +Jev를 **끄지도** 않습니다. 머신의 `jev.json`이 이미 FailproofAI Cloud를 통해 Jev를 실행 중이라면 그대로 유지되며, 출력에는 Jev가 여전히 각 확인된 도구 호출과 최근 프롬프트를 전송하고 있으며 `failproofai jev setup --mode off`로 끌 수 있다고 표시됩니다. + + +연결은 기존 `~/.failproofai/jev.json`을 **절대 덮어쓰지 않습니다**. 이미 자체 Jev 엔드포인트를 사용 중이라면 계속 사용되며, 출력에 파일이 설정된 대로 유지되었다고 표시됩니다 — 해당 파일에서 Jev가 꺼져 있는 경우(거부되었거나 수동으로 꺼진 경우)에는 그 사실과 해결 방법도 표시됩니다. 해당 머신을 FailproofAI Cloud로 전환하려면 `failproofai jev setup --provider failproofai`를 실행하세요. + + +## Shadow, enforce 또는 off + +Shadow로 시작해서 정책 페이지에서 Jev가 어떻게 동작하는지 확인한 다음, 실제로 적용할 수 있습니다: + +```bash +failproofai jev setup --mode enforce # Jev의 판결이 적용됩니다: 검토 가능한 deny를 해제하고 자체 판결을 추가할 수 있습니다 +failproofai jev setup --mode shadow # Jev가 질의되고 기록되지만 실제로 적용되는 것은 정책의 결과입니다 +failproofai jev setup --mode off # 설정은 유지하되 Jev에 질의하지 않습니다 +``` + +동일한 설정이 로컬 대시보드에도 있습니다: **Settings → Jev**에 on/off 스위치와 shadow/enforce 옵션이 있습니다. 모드만 다시 작성하고 다른 것은 변경하지 않습니다. 훅은 매 도구 호출마다 설정을 읽으므로 변경 사항은 다음 호출부터 적용되며, 재시작이 필요하지 않습니다. + +## 동작 상태 확인 + +```bash +failproofai jev status +failproofai jev test +``` + +`status`는 제공자를 **FailproofAI Cloud**로, 머신이 연결된 Cloud 호스트, 모드, 키 출처를 **FailproofAI Cloud connection**으로 표시합니다 — 키 자체는 표시되지 않습니다. FailproofAI Cloud `jev.json`이 있지만 Jev를 실행할 수 없는 경우 그 이유를 알려줍니다: + +| `status` 표시 | `status --json` | 의미 | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | 머신은 연결되어 있지만 Jev 키가 저장되어 있지 않습니다: 키에 `jev:evaluate` 권한이 없거나 연결 시 확인하지 못했습니다. 동일한 키로 `failproofai config --token `를 다시 실행하세요; 권한이 없다면 **machine** 키를 사용하세요. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | 이 머신에 Jev 키가 속할 FailproofAI Cloud 연결이 없습니다. | + +`failproofai config --disconnect` 이후에는 FailproofAI Cloud `jev.json`이 더 이상 존재하지 않으므로(꺼진 상태로 유지된 경우 제외) `status`는 단순히 Jev가 off라고 보고합니다. `status --json`은 동일한 정보를 포함합니다(`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`) — 설정이 없거나 거부된 경우에도 마찬가지입니다. `permissions`는 항상 `jev.json`의 것이며, `credentials.json`에 대한 거부는 `credentialsPermissions`를 추가하고, 하나의 명령으로 수정 가능한 경우 `fix`도 추가됩니다. `test`는 실제 요청을 하나 보내고 지연 시간과 응답한 Jev 버전을 보고합니다. 훅 타임아웃 이후에 응답이 도착하거나(훅은 `timeout`으로 기록됨) 확인 질문에 잘못 답하면 종료 코드 1로 종료되며 제목에 표시됩니다. + +대시보드의 **Settings → Jev** 패널에도 **FailproofAI Cloud connection**이 표시됩니다: 머신이 속한 조직과 키에 Jev가 포함되어 있는지 여부. 네트워크 호출 없이 머신 자체 파일에서 읽습니다. + +## 정책 페이지에 표시되는 내용 + +머신은 이미 훅 활동을 FailproofAI Cloud로 전송합니다(`events:add`). Jev가 활성화되면 각 게이팅된 호출 기록에도 실행된 평가자, Jev의 결정, 해제된 정책, 폴백 이유, 지연 시간, 응답한 모델이 포함됩니다 — 결정, 코드, 이름만이며 명령이나 프롬프트는 포함되지 않습니다. 조직의 **Policies** 페이지에서: + +- Jev 자체 판결로 결정된 호출(enforce 모드)은 **Jev**로 귀속되며, 결정적인 확인이 팩에서 온 경우 해당 팩과 버전도 기록에 표시됩니다; +- shadow 모드에서 Jev의 deny나 경고는 관찰 중인 롤아웃 옆에 **would-have**로 표시됩니다; +- Jev가 해제하거나 shadow 모드에서 해제했을 정책은 정책별로 집계됩니다. + +## Jev가 응답하지 못하는 경우 + +다음 각 경우는 해당 호출에 대해 정책 결과로 폴백되며 이유와 함께 기록됩니다: + +| 이유 | 원인 | +| --- | --- | +| `out-of-credits` | 조직의 플랜 허용량이 소진되었습니다. | +| `http-401`, `http-403` | 키가 취소되었거나 `jev:evaluate` 권한이 없습니다. 해당 권한이 있는 키로 재연결하세요. | +| `http-429` | FailproofAI Cloud가 조직의 Jev 요청을 속도 제한하고 있습니다. 요청한 대기 시간(`Retry-After`, 최대 60초)이 지날 때까지 머신은 아무것도 전송하지 않고 모든 호출이 즉시 폴백됩니다. 이런 방식으로 보류된 호출은 `http-429`로 기록되며, 머신 자체 속도 제한이 먼저 적용된 경우 `rate-limited`로 기록됩니다. | +| `http-429` (일일 한도) | 조직의 일일 Jev 호출 횟수가 소진되었습니다: **UTC 기준 하루 10,000회** — FailproofAI Cloud 운영자가 다른 한도를 설정하지 않은 경우. 00:00 UTC에 카운트가 초기화될 때까지 모든 호출이 폴백됩니다; 머신은 최대 1분에 한 번 다시 시도하므로 초기화 후 1분 내에 감지합니다. `failproofai jev test`는 "Daily Jev limit for this org reached; resets at 00:00 UTC."라고 표시합니다. | +| `http-422` | Jev가 이 호출 요청을 거부했습니다. 일반적으로 도구 호출에 Jev의 토큰 예산을 초과하는 밀집 텍스트(base64, hex, 압축된 코드)가 포함된 경우입니다. 해당 호출은 매번 폴백됩니다; 서비스 장애가 아닙니다. | +| `http-502` | Jev를 현재 사용할 수 없습니다. | +| `http-503` | 이 Cloud가 조직의 Jev를 제공할 수 없습니다: 모델 게이트웨이 없음, 아직 프로비저닝되지 않은 조직, 또는 게이트웨이 다운. 관리자에게 문의하세요; 훅은 최대 1분에 한 번 다시 시도합니다. | +| `http-404` | 이 FailproofAI Cloud는 아직 Jev를 제공하지 않습니다. | +| `timeout` | `timeoutMs`(기본값 3000) 내에 응답이 없습니다. | +| `model-mismatch` | 1.13이 아닌 다른 버전의 Jev가 응답했습니다. | + +## 키의 저장 위치와 전송 대상 + +- 키는 `~/.failproofai/credentials.json`에 한 번만 저장됩니다(`0600`, 소유자 전용 디렉터리), 다른 FailproofAI Cloud 자격 증명 옆에 위치합니다. 이 경로에서는 `jev.json`에 키가 없으며, 여기에 키가 작성되면 설정이 유효하지 않게 됩니다. +- `credentials.json`에 소유자 외 누군가(그룹 또는 기타, 읽기 또는 쓰기)에 대한 권한이 **있거나**, 디렉터리가 소유자 외 누군가에 의해 **쓰기 가능**한 경우, 파일은 **거부**되어 읽히지 않으며 수정할 때까지 Jev가 꺼집니다: 파일에 `chmod 600`, 디렉터리에 `chmod 700`을 적용하거나(또는 재연결하면 파일이 `0600`으로 다시 작성되고 디렉터리가 소유자 전용이 됨). 다른 사용자가 읽기만 할 수 있는 디렉터리는 괜찮습니다; 쓰기가 가능하면 파일을 교체할 수 있습니다. +- 키는 연결과 함께 머신에 있는 동안만 유효합니다: 동일한 FailproofAI Cloud에 대한 정책 또는 보고 자격 증명이 **동일한 키**로 동일한 파일에 있어야 합니다. 연결 없이 남겨진 Jev 키는 무시되며 Jev는 꺼진 상태로 유지됩니다. 이는 이전 버전 failproofai의 `config --disconnect`가 Jev 키를 그대로 남겨두거나(제거 방법을 모름), 이전 버전 failproofai의 `config --token`이 다른 키로 연결할 때 발생할 수 있습니다 — FailproofAI Cloud에서 이 키는 다른 조직에 속할 수 있습니다. Jev를 다시 활성화하려면 **machine** 키로 다시 연결하세요. +- 키는 검증된 Cloud 출처로만 전송됩니다. 다른 곳을 가리키는 `jev.json`은 거부됩니다. +- **머신의 에이전트가 키를 읽을 수 있습니다.** `credentials.json`은 소유자 전용이며 에이전트는 해당 소유자로 실행됩니다. failproofai 자체 파일 읽기는 의도적으로 허용되어 있습니다(변경만 `block-failproofai-commands`로 차단됨). 따라서 에이전트와 이 파일 사이에 있는 것은 `block-read-outside-cwd` — *검토 가능한* 정책 — 뿐이며, 홈 디렉터리에서 시작된 세션에서는 아무것도 없습니다. `jev:evaluate` 권한이 있는 키는 사용되는 곳 어디서나 조직의 Jev 허용량을 소모합니다(일일 한도까지). 따라서 머신 키를 다른 결제 자격 증명처럼 취급하세요: 에이전트가 읽었을 가능성이 있다면 Keys 페이지에서 비활성화하고 새 키로 재연결하세요. +- 글로벌 파일만 이를 결정합니다. 저장소는 Cloud Jev를 활성화하거나, 다른 곳으로 지정하거나, 키를 제공할 수 없으며, 이 경로에서는 `FAILPROOFAI_JEV_API_KEY`가 무시됩니다. +- Jev가 평가하는 각 호출마다 FailproofAI Cloud로 하나의 요청이 전송되며, [자체 키 사용 페이지](/ko/policies/jev-byok#what-leaves-the-machine)에 나열된 내용이 포함됩니다(시크릿은 삭제됨). FailproofAI Cloud는 이를 TypeSafe로 전달하며 기록하거나 보관하지 않습니다. + +## 비활성화하기 + +| 명령어 | 결과 | +| --- | --- | +| `failproofai jev setup --mode off` | 설정을 유지하면서 Jev에 질의하지 않습니다. **이것이 지속적인 스위치입니다:** 다시 연결해도 기존 `jev.json`을 덮어쓰지 않으므로, `--mode shadow`로 다시 켜기 전까지 Jev는 꺼진 상태로 유지됩니다. | +| `failproofai jev remove` | `~/.failproofai/jev.json`을 삭제합니다; Jev가 꺼집니다 — `jev:evaluate` 권한이 있는 키로 다음 `failproofai config --token`을 실행하면 `jev.json`이 없는 것을 확인하고 shadow 모드로 다시 Jev를 활성화합니다(`--no-transcripts`로 실행하지 않는 한). 꺼진 상태를 유지하려면 `--mode off`를 사용하세요. | +| `failproofai config --disconnect` | 머신의 연결을 해제합니다: 키가 제거되고, `jev.json`이 FailproofAI Cloud를 지정하고 꺼지지 않은 경우에도 `jev.json`이 제거됩니다. 자체 엔드포인트를 위한 `jev.json`은 유지되며, 꺼진 상태의 것도 유지되므로 다시 연결해도 Jev는 꺼진 상태로 유지됩니다. | + +다음 도구 호출부터 훅은 이전과 동일하게 정규식 정책만 실행합니다. \ No newline at end of file diff --git a/docs/ko/policies/jev.mdx b/docs/ko/policies/jev.mdx new file mode 100644 index 000000000..77c98c8f1 --- /dev/null +++ b/docs/ko/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "게이트된 도구 호출에 Jev의 실시간 검토를 추가한 뒤, 결정을 집행하기 전에 내용을 확인합니다." +icon: "shield-check" +--- + +Jev는 도구 호출을 에이전트에게 주어진 요청과 대조하여 검토합니다. 문자열 매칭 정책이 유효한 작업을 차단하거나, 맥락이 필요한 위험한 동작을 놓칠 때 사용하세요. `PreToolUse` 또는 `PermissionRequest` 게이트에서 기존 정책과 함께 응답합니다. 세션이 종료된 **이후**의 점수가 필요하다면 [Jev evaluations](/ko/evaluations/jev)를 사용하세요. + +## 관찰 모드로 시작하기 + +Failproof AI를 설치하고 [지원되는 하네스](/ko/reference/harnesses)에 훅을 연결하세요. failproofai 1.0.8-beta.0 이상이 필요합니다. + +Failproof AI에는 Jev 검사가 기본 포함되어 있지 않습니다. 팩으로 설치해야 하며, 그렇지 않으면 Jev가 호출되지 않습니다: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +그런 다음 요청이 Jev에 전달되는 방식을 선택하세요: + +| 경로 | 첫 번째 단계 | +| --- | --- | +| FailproofAI Cloud | `jev:evaluate` 권한이 있는 **machine** 키로 연결합니다. Jev 설정이 없는 머신에서는 `failproofai config`를 실행하면 Jev가 관찰 모드로 활성화됩니다. | +| 직접 사용하는 프로바이더 | 로컬 대시보드에서 **Settings → Jev**를 열고 프로바이더를 선택한 뒤 토큰을 붙여넣고 **observe**를 선택합니다. 또는 `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`를 실행하세요. | + +![로컬 대시보드의 Jev 설정 화면: 프로바이더, 엔드포인트, 토큰, 그리고 Jev 활성화 전 관찰 모드 설정.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test`는 엔드포인트를 확인합니다. 훅 경로를 확인하려면, 훅이 연결된 에이전트에게 파일 읽기 도구로 `README.md`를 열도록 요청하세요. 해당 도구 호출이 세션에 나타나는지 확인한 뒤, [로컬 대시보드](/ko/reference/local-dashboard#review-policy-activity)의 **Policies → Activity**에서 내용을 검토하세요. `status`의 Jev 카운트가 증가해야 합니다. 관찰 모드는 기존 정책 결과를 그대로 적용하면서 Jev가 어떤 결정을 내렸을지를 기록합니다. + +## 집행 시점 결정하기 + +**hard** 정책은 항상 최종 결정권을 가집니다. Jev는 명시적으로 **reviewable**로 표시된 정책의 deny만 취소할 수 있으며, 해당 정책에서 지정한 우려 사항을 실제로 검토한 경우에만 가능합니다. 취소 결정에 의존하기 전에 [정책 권한](/ko/policies/authority)을 먼저 확인하세요. Jev는 자체적으로 경고하거나 거부할 수도 있습니다. 응답할 수 없는 경우에는 정책 결과가 해당 호출을 결정합니다. + +관찰 결과가 적절해 보이면 **Settings → Jev**에서 집행 모드로 전환하거나 다음을 실행하세요: + +```bash +failproofai jev setup --mode enforce +``` + +프로바이더 URL, Cloud 키, 설정, 폴백, 각 요청과 함께 전송되는 데이터에 대한 자세한 내용은 [Jev 통합 레퍼런스](/ko/reference/jev)를 참조하세요. \ No newline at end of file diff --git a/docs/ko/reference/custom-agents-typescript.mdx b/docs/ko/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..5eeb998eb --- /dev/null +++ b/docs/ko/reference/custom-agents-typescript.mdx @@ -0,0 +1,428 @@ +--- +title: "커스텀 에이전트 (TypeScript)" +description: "@failproofai/sdk의 설정, 이벤트 카탈로그, 스코프 및 프레임워크 어댑터." +icon: "square-js" +--- + +TypeScript SDK의 모든 설정, 메서드, 필드에 대한 설명입니다. 처음 계측하는 경우라면 가이드부터 시작하세요 — 이 페이지는 참조용입니다. + + + + 설치, 계측, 이벤트 메서드, 실습 예제, 그리고 자주 발생하는 문제들. + + + 동일한 이벤트, 동일한 와이어 포맷, 동일한 스풀 — Python 버전. + + + +Node 20.9 이상. ESM과 CommonJS 지원. 런타임 의존성 없음. + + + 이 SDK와 Python SDK는 **동일한 스풀에 동일한 이벤트를 기록합니다**. Node 에이전트와 Python 에이전트가 혼재하는 플릿은 세션 세트가 두 개가 아닌 하나가 되며, 대시보드에서 어떤 것으로도 구분되지 않습니다. 회사 단위가 아닌 서비스 단위로 선택하세요. + + +## 설치 + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +프레임워크 어댑터는 패키지 자체에 포함되어 있습니다. 프레임워크는 **선택적 피어 의존성**으로 — 지원 범위를 명시적으로 보여주기 위해 선언되었을 뿐, 자동으로 설치되지 않으며 `instrument()`를 호출할 때만 임포트됩니다. + +## Failproof 데몬 연결 + +Python SDK와 동일합니다. **Admin → Keys**에서 `events:add` 키를 생성한 후, 에이전트 머신에서 [데몬을 연결](/ko/start/setup#connect-a-machine-to-cloud)하세요. SDK는 디스크에 기록하고, 데몬이 전송합니다. + +## 설정 + +### OpenTelemetry 스팬 (옵트인) + +`npm install @opentelemetry/api @opentelemetry/sdk-trace-base`로 OpenTelemetry를 별도로 설치하세요. +그런 다음 프로바이더의 프로세서에 FailproofAI를 추가합니다: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +기존 프로바이더의 경우, 같은 목록에 다른 프로세서를 유지하세요. `addSpanProcessor`를 노출하는 프로바이더는 `{ provider }`로 전달할 수도 있습니다. 옵션 없이 설정하면 이미 등록된 프로바이더가 없는 경우에만 새 프로바이더를 등록합니다. +`OtelSpanExporter`는 자체 프로세서와 함께 직접 사용할 수도 있습니다. + +내보내기는 연결된 FailproofAI 데몬을 통해 이루어지며, SDK는 네트워크 요청을 보내지 않고 키나 로컬 리스너가 필요하지 않습니다. 관리자에게 [OpenTelemetry 인제스트](/ko/agenteye/opentelemetry) 활성화를 요청하세요. 단순 `instrument()`는 이 익스포터를 활성화하지 않습니다. `uninstrument("otel")`은 자체 프로세서만 비활성화합니다. +스팬 속성이 콘텐츠 캡처를 제어하므로, 종료 전에 프로바이더를 플러시하세요. +OpenTelemetry는 SDK의 하드 의존성이 아닌 선택적 애플리케이션 의존성으로 유지됩니다. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| 옵션 | 설명 | +| --- | --- | +| `environment` | 모든 이벤트에 붙는 레이블 — `production`, `staging`, `prod-eu`. 기본값은 `dev`. | +| `flushInterval` | 타이머가 디스크에 기록하는 주기(초). 기본값은 `0.5`. | +| `baseDir` | 기록 위치. 기본값은 데몬의 스풀 디렉터리이며, 특별한 이유가 없다면 변경하지 마세요. | + +전체 유효성 검사를 통과해야만 적용되므로, 거부된 호출은 새 `baseDir`에 기존 인터벌이 적용되는 상태가 아닌, SDK를 그대로 유지합니다. + +환경 변수로도 설정할 수 있습니다: + +| 변수 | 설명 | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | 코드 변경 없이 `environment`를 설정합니다. `configure()` 옵션이 우선합니다. | +| `FAILPROOFAI_HOME` | 스풀을 보관하는 Failproof AI 루트 디렉터리를 변경합니다. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (기본값), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1`로 설정하면 계측 오류를 로그 대신 예외로 던집니다. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1`로 설정하면 프레임워크 호환성 문제 발생 시 경고 후 계속 진행하는 대신 예외를 던집니다. | + + + **`environment`에 쉼표를 사용하지 마세요.** 인제스트가 필터를 구성할 때 해당 필드를 쉼표로 분리하며, 레이블에 쉼표가 포함된 이벤트는 무시됩니다 — 전체 실행이 조용히 사라집니다. `prod,eu`가 아닌 `prod-eu`로 작성하세요. + + `configure({ environment: "prod,eu" })`는 즉시 오류를 던져서 바로 알 수 있습니다. `AGENTEYE_ENVIRONMENT`는 예외를 던질 수 없으므로 — 호출하는 주체가 없으니 — 한 번 경고를 출력하고 `dev`로 대체합니다. + + +`failproofai.setLogger({ debug, info, warn, error })`를 사용하여 SDK 자체 로그를 원하는 로거로 라우팅하세요. + +## 종료 + +버퍼링된 이벤트는 `process.on("exit")`에서 플러시됩니다. + +시그널로 종료된 프로세스는 이 단계에 도달하지 못하며, Node의 `SIGTERM` 기본 동작은 종료 핸들러를 실행하지 않고 종료하는 것입니다 — 따라서 컨테이너화된 에이전트는 마지막 인터벌이 아직 기록하지 못한 데이터를 잃게 됩니다. + + + **이 SDK는 시그널 핸들러를 자동으로 등록하지 않습니다.** 핸들러를 등록하면 프로세스 동작이 변경됩니다. 리스너가 Node의 기본 종료를 억제하므로, 라이브러리가 자동으로 등록하면 Ctrl-C가 조용히 작동하지 않게 됩니다. 직접 추가하세요: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +단기 스크립트나 서버리스 핸들러는 반환 전에 `await failproofai.flush()`를 호출해야 합니다 — 인터벌만으로는 전달이 보장되지 않습니다. + +## 아이덴티티 + +모든 이벤트는 세션과 에이전트에 속합니다. **스코프가 둘 다 채워주므로** 직접 전달할 일은 거의 없습니다: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +`sessionId`나 `agentId`를 명시적으로 전달하는 것도 가능하며, 명시적 값이 우선합니다. 둘 다 바인딩되지 않고 전달되지도 않으면 Cloud가 조용히 무시할 이벤트를 발송하는 대신 예외를 던집니다. + + + 아이덴티티는 `AsyncLocalStorage`를 통해 전달됩니다. `await`, `.then()`, 타이머, 스코프 내부에서 생성된 모든 콜백을 따라갑니다. 한 실행 중에 저장되어 다른 실행 중에 호출되는 콜백이나 `worker_threads` 경계를 넘어가는 작업은 따라가지 **않습니다** — 이런 경우 `failproofai.propagate()`로 감싸지 않으면 이벤트가 연결되지 않습니다. + + +### 스코프 + +| 스코프 | 발송 | 반환값 | +| --- | --- | --- | +| `session(body)` | 없음 — 아이덴티티만 | `body`의 반환값 | +| `agent(id, options?, body)` | `agent_start`, 이후 `agent_end` | `body`의 반환값 | +| `toolCall(name, options?, body)` | `tool_use`, 이후 `tool_result` | `body`의 반환값 | + +동기 본문은 동기로 유지됩니다: `agent("x", () => 1)`은 프로미스가 아닌 `1`을 반환합니다. + +`toolCall`은 본문의 resolved 값을 도구의 `output`으로 기록합니다. `call.output`을 직접 지정한 경우는 예외입니다. + + + +| 발생한 상황 | 이벤트 | `outcome` | +| --- | --- | --- | +| 블록이 반환됨 | `agent_end` | `"success"`, 또는 지정한 `outcome` | +| 블록에서 예외 발생 | `error`, 이후 `agent_end` | `"failed"` | +| `AbortError` | `agent_end`만 | `"cancelled"` | + +오류는 항상 다시 던져집니다. + +도구 실패는 리프에 기록됩니다 — `error` 문자열이 포함된 `tool_result` — 로 기록되며 실행 수준의 `error` 이벤트는 **발송되지 않습니다**. 에이전트 루프가 잡은 오류는 실행 실패가 아니며, 전파된 오류는 감싸는 `agent()`에 의해 정확히 한 번 보고됩니다. + + + + + +작업이 단일 함수가 아닌 경우 — 생성자에서 열리고 테어다운에서 닫히거나, 기존 제어 흐름에 걸쳐 있는 스코프: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +두 형식 모두 바이트 단위로 동일한 이벤트를 발송합니다. 콜백 형식을 권장합니다: `AsyncLocalStorage.run()` 내부에서 실행되므로 언와인드할 것이 없고 "여기서 열리고 저기서 닫히는" 버그 유형 전체가 발생 불가능합니다. + +자체 실패를 잡는 `using` 블록은 `span.fail(error)`로 보고합니다 — disposer 자체에는 예외 채널이 없습니다. + + + +## 이벤트 카탈로그 + +Python SDK와 동일한 15개 메서드를 camelCase로 제공합니다. 대부분 **쌍으로** 구성됩니다 — 오프너를 호출하고 클로저를 호출하면 SDK가 간격을 측정합니다. + +| | 오프너 | 클로저 | +| --- | --- | --- | +| **에이전트** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **모델** | `modelRequest` | `modelResponse` | +| **도구** | `toolUse` | `toolResult` | +| **훅** | `hookTriggered` | `hookCompleted` | +| **휴먼** | `humanWait` | `humanInput` | + +단독으로 사용되는 메서드: `error`, `humanPause`, `humanInterrupt`. + + + +모든 메서드는 `sessionId`와 `agentId`도 받으며, 스코프가 자동으로 채워줍니다. 생략된 항목은 JSON `null`로 전송되지 않고 제외됩니다. + +| 메서드 | 필수 | 선택 | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +다른 키를 추가하면 커스텀 페이로드 필드가 됩니다. 프레임워크별 항목에는 `fw_*` 네임스페이스를 사용하세요. 선언된 필드와 이름이 충돌하는 경우 승격된 컬럼을 조용히 덮어쓰는 대신 거부됩니다. + + + + + **`duration_ms`는 계산되는 값이며 입력을 허용하지 않습니다.** 네 개의 클로징 메서드는 오프너로부터의 간격을 측정하며, 호출자가 제공한 `duration_ms`를 거부합니다 — 보고된 지속 시간은 위조 불가능해야 합니다. + + 쌍은 에이전트가 아닌 **세션**과 id로 매칭됩니다. `planner` 아래에서 열리고 `worker` 아래에서 닫힌 도구도 올바르게 쌍을 이룹니다 — 중첩된 멀티 에이전트 실행이 실제로 하는 방식이 바로 이것입니다. + + +## 프레임워크 어댑터 + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| 프레임워크 | 지원 버전 | 연결 방식 | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`를 통해 연결되므로, `callbacks:`를 어디에도 전달하지 않아도 모든 `invoke`/`stream`/`batch`가 커버됩니다 — 또는 `langchainHandler()`를 직접 전달하고 패치하지 않을 수도 있습니다. | +| **Vercel AI SDK** | `ai` 4 – 7 | 호출 지점에서 `telemetry()`를 사용하거나, `ai` 7에서 전체 프로세스에 `instrument("ai")`를 사용합니다 (4–6에서는 옵트인 — 아래 참조). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, 에이전트의 모델 및 도구 해결, 그리고 워크플로우 실행/스텝 엔진. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | 워크플로우 실행 및 스텝을 위한 `Settings.callbackManager`(구독) 및 `AgentWorkflow.runStream`. | + +모든 범위는 실제 프레임워크 릴리스를 대상으로 양 끝단에서, ES 모듈과 CommonJS 모두, 매 CI 실행마다 테스트됩니다. + +매핑은 Python SDK와 동일하므로, 같은 프로그램이 어느 언어에서든 동일한 트리를 그립니다. LLM 결정 루프를 소유한 경우에만 **에이전트**가 됩니다 — 그래프 또는 체인 실행, AI SDK `generateText`/`streamText` 호출, Mastra 에이전트, LlamaIndex 에이전트 실행이 해당합니다. LangGraph 노드나 워크플로우 스텝은 중첩 에이전트가 아닌 **훅**(`hook_triggered`/`hook_completed`)입니다. 모델 호출은 토큰 수를 포함한 `model_request`/`model_response` 쌍이며, 도구 호출은 모델 자체의 도구 호출 id를 담습니다. 실패는 발생한 이벤트에 한 번만 기록됩니다. + +설치에 실패한 어댑터는 로그되고 건너뜁니다. 나머지 어댑터는 계속 설치됩니다 — LlamaIndex 오류가 LangGraph를 잃게 해서는 안 되기 때문입니다. + + + 인자 없는 `instrument()`는 프레임워크가 이미 임포트되었는지가 아닌 **resolve 가능한지** 여부로 감지합니다 — Node는 ES 모듈에 대해 Python의 `sys.modules`에 해당하는 것을 노출하지 않습니다. 설치되어 있지만 사용하지 않는 프레임워크도 임포트되고 패치됩니다. 중요하다면 원하는 것을 명시적으로 지정하세요. + + + + 이러한 프레임워크 대부분은 ES 모듈 빌드와 CommonJS 빌드를 별도로 제공하며, Node는 이를 서로 무관한 두 복사본으로 로드합니다. 어댑터는 애플리케이션이 로드하는 복사본(및 이미 `require`된 경우 CommonJS 복사본도)을 패치하므로 두 모듈 시스템 모두 작동합니다. esbuild나 webpack이 **자체 출력으로 번들링한** 프레임워크는 도달할 수 없습니다 — 그 경우 호출 지점 헬퍼를 사용하세요: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### 패치 없이 LangChain 사용하기 + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +핸들러는 `instrument()` 사용 여부와 무관하게 작동하며 중복 기록이 없습니다. `instrument("langchain")`은 Python 어댑터와 동일하게 `sessionId`, `captureContent`, `includeChains`, `graphCallbacks`, `captureLimit`을 받습니다. 호출 시 `metadata: { failproofai_sdk_session_id }`를 지정하면 해당 호출에 대한 세션이 선택됩니다. + +### Vercel AI SDK + +AI SDK는 ES 모듈에서 일반 함수를 내보내며, ES 모듈 네임스페이스는 명세상 불변입니다 — 패치할 곳이 없습니다. SDK 자체가 문서화한 확장 지점을 사용합니다: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +이것이 완전한 통합입니다: 에이전트 스팬, 스텝당 토큰 수를 포함한 모델 요청/응답 쌍, 모든 도구 호출. 하나의 호출 지점이 모든 메이저 버전에서 작동합니다 — `ai` 4–6은 tracer를 읽고, `ai` 7은 telemetry 통합을 읽습니다. + +**`ai` 7에서** `instrument("ai")`는 AI SDK의 전역 텔레메트리 통합 목록을 통해 프로세스 전체에 동일한 작업을 수행합니다. 이는 가산적이며 다른 누구의 것도 가져가지 않습니다. + +**`ai` 4–6에서 `instrument("ai")`는 자체적으로 아무것도 기록하지 않으며, 그 사실을 알리는 경고를 한 번 로그합니다.** 해당 메이저 버전이 가진 유일한 프로세스 전체 훅은 전역 OpenTelemetry tracer 프로바이더 — 한 번 사용되면 OpenTelemetry가 양도를 거부하는 단일 슬롯입니다. 우리 것을 등록하면 이후 시작 시 `NodeSDK.start()`가 조용히 거부되고, http/데이터베이스 스팬이 아무것도 내보내지 않는 tracer로 전송됩니다. 호출 지점에서 `telemetry()`를 사용하거나 `wrapModel`을 사용하세요. 프로세스에 자체 OpenTelemetry가 없다면 `instrument("ai", { registerGlobalTracer: true })`로 옵트인하세요: 그러면 `experimental_telemetry: { isEnabled: true }`를 전달하는 모든 호출을 기록하며, 슬롯이 비어있을 때만 사용합니다. `registerGlobalTracer: false`는 기본값을 유지하고 경고를 없앱니다. + +모델만 한 번 감싸고 싶다면 `wrapModel`을 사용하세요. 도구 호출은 모델 레이어 위에서 발생하므로 모델 호출만 볼 수 있습니다. 아무것도 감싸지 않은 채로 호출된 래핑된 모델은 자체 실행으로 기록됩니다. 스트리밍 호출은 스트림이 멈추는 방식에 따라 닫힙니다 — 소비자가 취소하면 `stop_reason: "cancelled"`, 중간에 실패하면 오류와 함께 `"error"`: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +둘 다 사용해도 괜찮습니다: 미들웨어가 호출이 이미 기록 중임을 감지하고 위임하므로 각 호출은 한 번만 기록됩니다. + +`functionId`는 에이전트 스팬의 이름을 지정합니다. 카디널리티를 낮게 유지하세요 — 주요 대시보드 패싯인 `agent_id`에 저장됩니다. + +### Next.js + +`next build`는 기본적으로 서버의 의존성을 번들링하며, 빌드에 번들링된 프레임워크는 `instrument()`가 도달할 수 없는 복사본입니다. 설정을 한 번 감싸고 Next의 시작 훅에서 `instrument()`를 호출하세요: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai`는 기존 목록을 유지하면서 LangChain, Mastra, LlamaIndex 및 SDK 자체를 `serverExternalPackages`에 추가합니다. 이를 사용하지 않으면 `instrument()`는 도달할 수 없는 각 프레임워크에 대해 한 번씩 경고를 출력하며 조용히 실패하지 않습니다. 패키지를 직접 나열하는 경우 `FAILPROOFAI_NEXT_EXTERNALS=1`로 설정하세요. Vercel AI SDK와 호출 지점 헬퍼는 어느 경우에도 작동합니다. Edge 라우트는 no-op 빌드를 받습니다: SDK를 임포트해도 안전하며 아무것도 기록하지 않습니다. + +### 스트리밍 호출의 토큰 수 + +OpenAI 호환 API는 클라이언트가 요청할 때만 스트림에서 사용량을 보고합니다. LangChain과 Vercel AI SDK는 요청합니다. LlamaIndex는 `OpenAI` LLM에 `additionalChatOptions: { stream_options: { include_usage: true } }`를 전달하고, Mastra는 사용량 활성화된 모델을 빌드하세요 (예: `createOpenAICompatible({ includeUsage: true })`). 그렇지 않으면 스트리밍 모델 호출에 토큰 수가 포함되지 않습니다. + +### 런타임 + +Node ≥ 20.9, Bun, Deno — 모든 프레임워크를 ES 모듈과 CommonJS로, Node 트레이스에 대해 각각 테스트합니다. SDK는 `failproofaid` 데몬과 함께 실행되며, 데몬이 기록된 내용을 전송합니다. + +## 직접 작성한 에이전트 — 프레임워크 없음 + +직접 작성한 에이전트 루프나 어댑터가 없는 프레임워크를 위한 방법입니다. 어댑터가 내부적으로 사용하는 것과 동일한 API로 이벤트를 발송하므로, 트레이스의 형태와 품질이 동일합니다. + +에이전트가 어떻게 구성되어 있는지 알 필요가 없습니다. 직접 작성한 에이전트는 함수 이름이 무엇이든 세 가지 위치가 이미 있으며, 그 세 가지가 통합의 전부입니다: + +| 위치 | 추가할 내용 | 발송 | +| --- | --- | --- | +| **하나의 실행**이 시작되고 끝나는 곳 | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **모델을 호출하는 단일 함수** | 이전에 `event.modelRequest`, 이후에 `event.modelResponse` — 실패 시에도 두 쌍 모두 | 모델 턴당 한 쌍 | +| **도구를 실행하는 단일 함수** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +아이덴티티는 주변 환경에서 가져옵니다: `agent()` 내부의 모든 것은 id를 받지 않아도 해당 실행의 세션에 속하며, 프로그램의 다른 부분 — 에이전트가 자체 데이터베이스에 기록하는 내용을 포함하여 — 은 변경되지 않습니다. + +- **서비스 또는 워커:** 자체 요청이나 작업 id를 `sessionId`로 전달하면, 대시보드의 세션과 자체 로그 또는 데이터베이스의 레코드가 동일한 문자열이 됩니다. +- **서브 에이전트:** `agent()` 호출을 중첩합니다. 내부 호출은 외부를 `parent_id`로 하여 세션에 합류합니다. +- **쌍을 발송하세요.** `modelResponse` 없는 `modelRequest`는 대시보드에서 영원히 실행 중으로 표시되는 스팬이 됩니다 — 그래서 `catch`가 필요합니다. + +저장소의 [`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts)가 완전한 실행 가능 버전입니다: 정확히 이와 같이 계측된 실제 OpenAI 도구 루프로, 매 변경마다 ES 모듈과 CommonJS로 CI에서 실행됩니다. + +## 평가 + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +프로토콜, 워커 설정, 결과 유형에 대해서는 [Evaluator SDK 참조](/ko/reference/evaluator-sdk)를 확인하세요. + + + **평가는 반드시 종료되어야 합니다.** 반환하지 않는 동기 함수는 Node가 가진 단 하나의 스레드를 차단하며, 그 동안 타임아웃이 작동할 수 없습니다. `async` 평가를 작성하세요. + + +## 프로세스에 미치지 않는 영향 + +| | | +| --- | --- | +| **에이전트 루프 차단 없음** | 이벤트는 메모리 내 큐에 들어가고 타이머가 기록합니다. 타이머는 `unref`되어 있으므로, 이 패키지를 임포트해도 스크립트 종료가 절대 차단되지 않습니다. | +| **무제한 증가 없음** | 큐는 개수와 측정된 바이트 수 양쪽으로 제한됩니다. 어느 쪽이든 초과하면 가장 오래된 이벤트가 버려지고 경고가 출력됩니다 — 텔레메트리 중단이 OOM 킬이 되어서는 안 됩니다. | +| **프로세스 종료 없음** | 인코딩할 수 없는 이벤트 하나만 버려지며, 주변 배치에는 영향이 없습니다. 예외를 던지는 getter, 순환 참조, `BigInt`, 단독 서로게이트: 각각 처리되며 전파되지 않습니다. | +| **절반만 기록된 배치 없음** | 콘텐츠는 원자적 이름 변경 전에 `fsync`되고, 이름 변경 후에 디렉터리가 `fsync`됩니다. 실패한 쓰기는 임시 파일을 정리합니다. | +| **트랜스크립트 무단 접근 없음** | 배치는 `0700` 디렉터리 내 `0600` 권한입니다. 목표, 프롬프트, 도구 인수, 도구 출력을 담고 있습니다. | +| **자격증명 전송 없음** | API 키, 토큰, JWT, bearer 헤더, 시크릿 형태의 할당은 바이트가 디스크에 저장되기 전에 삭제됩니다. 데몬은 업로드 전에 다시 한번 삭제합니다. | \ No newline at end of file diff --git a/docs/ko/reference/custom-agents.mdx b/docs/ko/reference/custom-agents.mdx index 7f96a5843..15eb3765f 100644 --- a/docs/ko/reference/custom-agents.mdx +++ b/docs/ko/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -Python 3.10 이상. 런타임 의존성 없음. +Python 3.11 이상. 런타임 의존성 없음. ## 설치 diff --git a/docs/ko/reference/jev-cloud.mdx b/docs/ko/reference/jev-cloud.mdx new file mode 100644 index 000000000..2557f9a6b --- /dev/null +++ b/docs/ko/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "FailproofAI Cloud를 통한 Jev" +description: "라이브 Jev 정책 검토를 위한 Cloud 머신 키, 연결 상태, 한도, 장애 동작." +icon: "cloud" +--- + +이 페이지는 [Jev 정책](/ko/policies/jev)의 Cloud 경로 참조 문서입니다. TypeSafe의 분류기인 Jev는 각 도구 호출을 실제 요청 내용과 비교하여 읽고, 정책 대신이 아니라 정책과 함께 응답합니다. **FailproofAI Cloud**를 통해 연결된 머신은 이미 연결에 사용하는 키로 Jev를 사용합니다. TypeSafe 계정, 별도 키, 엔드포인트 설정이 필요 없습니다. 각 호출은 조직의 기존 플랜 허용량에서 차감됩니다. + +Jev의 모든 동작은 [자체 키 설정](/ko/reference/jev-providers)과 동일합니다. 하드 정책은 항상 최종적이며, 검토 가능한 정책의 거부는 Jev가 정확히 해당 우려 사항에 대해 질의받은 경우에만 해제됩니다. 그리고 모든 실패는 해당 호출의 정규식 결과로 폴백됩니다. + + +**failproofai 1.0.8-beta.0** 이상이 필요합니다. 1.0.7에는 Jev가 없습니다. 1.0.7 베타보다 버전 번호가 높게 정렬되더라도 마찬가지입니다. Jev 설정이 없으면 아무것도 변경되지 않습니다. 훅은 항상 그래왔던 것처럼 정규식 정책을 그대로 실행합니다. + + +## 시작하기 전에 + +에이전트가 실행되는 머신에 Failproof AI를 설치하고, [지원되는 하니스](/ko/reference/harnesses)에 훅을 연결하세요. 처음 시작하는 경우 [빠른 시작](/ko/start/quickstart)에서 훅 설치까지 따라하세요. `failproofai --version`으로 설치된 CLI를 확인하고, Jev 이전 버전이라면 업데이트하세요. 또한 머신 키를 생성하려면 조직의 **Administration → Keys** 페이지에 접근 권한이 필요합니다. + +Jev는 `PreToolUse` 또는 `PermissionRequest` 게이트에서 명명된 도구 호출을 검토합니다. 세션의 모든 이벤트를 검토하지는 않습니다. Jev가 정책 거부를 해제하는 것을 확인하려면 [검토 가능](/ko/policies/authority)으로 표시된 정책이 설치되어 있어야 합니다. 다른 모든 정책 거부는 최종적으로 유지됩니다. + +## 활성화 방법 + +1. **Jev가 포함된 키를 생성합니다.** FailproofAI Cloud 대시보드에서 **Administration → Keys → Create key**를 열고 **machine** 프리셋을 선택합니다. 머신에 필요한 세 가지 권한이 부여됩니다: `events:add`(활동 전송), `policies:pull`(정책 수신), `jev:evaluate`(Jev, 조직 플랜에서 차감). 키는 나머지 두 권한 없이 `jev:evaluate`만 가질 수 없습니다. +2. **해당 키로 머신을 연결합니다.** 프롬프트에서 일회성 시크릿을 확인한 후 전체 설정 명령을 실행합니다: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config`는 데몬을 설치하고, 발견된 에이전트 CLI에 훅을 연결하고, 머신을 연결합니다. 환경 변수는 명령 인수와 셸 히스토리에서 키를 보호합니다. 하니스가 나중에 설치된 경우 [명시적으로 연결](/ko/start/quickstart)하세요. + + 조직이 호스팅 서비스 대신 자체 FailproofAI Cloud를 운영하는 경우 주소를 추가하세요: `--url https://` (또는 `FAILPROOFAI_CLOUD_URL` 내보내기). 이 없으면 키가 호스팅 서비스에 대해 확인되어 연결이 실패합니다. 해당 호스트의 인증서가 사설 CA에서 발급된 경우, `NODE_EXTRA_CA_CERTS`가 아닌 머신의 시스템 신뢰 저장소에 CA를 설치하세요(예: `update-ca-certificates` 사용). 이벤트를 전송하고 정책을 가져오는 데몬은 시스템 저장소를 읽습니다. [문제 해결](/ko/reference/troubleshooting)을 참조하세요. + +이것으로 끝입니다. 연결하면 키가 저장되고, 머신에 Jev 설정이 **없는** 경우 FailproofAI Cloud용 설정이 작성됩니다. 머신이 처음 배포되면(약 30초 이내) FailproofAI Cloud가 모드를 설정합니다: Jev 정책이 배포된 경우 `enforce`, 없는 경우 `off`([모드를 설정하는 주체](#who-sets-the-mode) 참조). 출력에 다음과 같이 표시됩니다: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +FailproofAI Cloud가 배포하는 검사는 Cloud에서 실행됩니다. 머신에 직접 검사를 추가하려면 팩을 설치하세요: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**`--no-transcripts`와 함께 연결하면 Jev가 활성화되지 않습니다.** Jev는 각 검사된 도구 호출과 최근 프롬프트를 FailproofAI Cloud로 전송하는데, 이는 결정 전용 연결이 전송하도록 요청받은 것보다 많습니다. 키는 여전히 저장되며, 출력에 Jev를 사용할 수 있고 활성화 방법이 표시됩니다: + +```bash +failproofai jev setup --provider failproofai +``` + +이 명령은 FailproofAI Cloud를 통한 Jev를 **끄기도** 합니다. FailproofAI Cloud를 통해 Jev를 실행하는 `jev.json`(트랜스크립트가 켜진 이전 연결로 남겨진 것)은 `config --disconnect`가 사용하는 동일한 규칙에 따라 제거되며, 출력에 이 머신에서 FailproofAI Cloud를 통한 Jev가 꺼진 상태로 유지된다고 표시됩니다. 자체 Jev 엔드포인트용 `jev.json`은 그대로 유지되며, `--mode off`로 꺼진 FailproofAI Cloud용 설정도 마찬가지입니다. + + +연결은 기존 `~/.failproofai/jev.json`을 **절대 덮어쓰지 않습니다**. 이미 자체 Jev 엔드포인트를 사용하고 있다면 계속 사용됩니다. 출력에 파일이 그대로 유지되었다고 표시되며, 해당 파일이 Jev를 꺼두는 경우(거부됨 또는 꺼짐) 이를 알리고 수정 방법을 안내합니다. 해당 머신을 FailproofAI Cloud로 전환하려면 `failproofai jev setup --provider failproofai`를 실행하세요. + + +## 모드를 설정하는 주체 + +FailproofAI Cloud에 연결된 머신에서는 **FailproofAI Cloud가 Jev 모드를 설정합니다**. 머신에서는 아무것도 설정하지 않습니다. + +- 머신에 Jev(또는 정규식 + Jev) 정책이 배포된 동안에는 `enforce`입니다. 해당 정책이 타겟팅하는 에이전트의 모든 검사된 도구 호출이 FailproofAI Cloud로 전송되며, Cloud는 해당 검사와 함께 설치된 팩의 검사를 함께 요청합니다. Cloud Jev 정책이 타겟팅하지 않는 에이전트의 호출로 자체 팩 검사도 없는 경우 전혀 전송되지 않습니다. `enforce` 모드에서 Jev의 자체 거부 검사는 정규식 판정을 검토하면서 해제하는 것뿐만 아니라 호출을 차단하기도 합니다. +- 아무것도 없는 경우에는 `off`입니다. `jev.json`에 무슨 내용이 있든 Jev가 전혀 없습니다. + +Jev 정책이 작동하기 전에 먼저 시험해보려면 효과를 **observe**로 설정하여 배포하세요. 검사는 여전히 요청되고 수행했을 작업이 정책 페이지에 **would-have**로 기록되지만, 호출을 차단하거나 해제하지 않습니다. `failproofai jev setup --mode`와 대시보드의 **Settings → Jev** 스위치는 모드가 FailproofAI Cloud에 의해 관리됨을 표시하며 아무것도 변경하지 않습니다. `jev.json`은 Cloud의 검사에 사용되지 않습니다. 다른 공급자를 지정하더라도 마찬가지입니다. `failproofai config --disconnect`는 Jev를 머신 자체 `jev.json`으로 돌려줍니다. + +`failproofai jev status`는 `Jev checks run on FailproofAI Cloud (mode: enforce)`라고 표시합니다. 또한 각 `both` 정책을 검토하는 검사 이름도 나열합니다. 플리트 페이지는 모드를 가진 머신이 요청할 수 없는 이유를 보여줍니다: + +- `transcripts_disabled`: 머신이 `--no-transcripts`로 연결되었으며 Jev가 활성화되지 않습니다. +- `jev_unconfigured`: 머신의 키가 `jev:evaluate`를 가지고 있지 않습니다. +- `jev_rate_limited`: FailproofAI Cloud가 조직의 Jev 속도 제한으로 인해 머신의 일부 호출을 거부했으며, 해당 호출은 정규식 정책만으로 결정되었습니다. +- `jev_unavailable`: 연속으로 여러 호출이 실패하여 머신이 한 번에 1분씩 FailproofAI Cloud의 Jev를 건너뜁니다. 자동으로 재시도합니다. + +FailproofAI Cloud가 5초 내에 응답하지 않으면 Jev 중단 시와 마찬가지로 정규식 정책이 단독으로 결정합니다. 연속 3번 실패하면 머신이 한 번에 1분씩 요청을 중단하므로 Cloud 중단이 모든 도구 호출을 느리게 만들지 않습니다. + +세션 일시 중지(`failproofai config --pause`)는 Cloud 관리 정책을 중지하지 않는 것처럼 FailproofAI Cloud의 Jev 검사도 중지하지 않습니다. 머신에 설치된 팩의 Jev 검사는 일시 중지됩니다. + +## 동작 확인 + +```bash +failproofai jev status +failproofai jev test +``` + +`status`는 공급자를 **FailproofAI Cloud**로, 머신이 연결된 Cloud 호스트, 모드, 키 소스를 **FailproofAI Cloud connection**으로 표시합니다. 키 자체는 절대 표시되지 않습니다. FailproofAI Cloud `jev.json`이 있지만 Jev를 실행할 수 없는 경우 그 이유를 알려줍니다: + +| `status` 표시 | `status --json` | 의미 | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | 머신이 연결되어 있지만 Jev 키가 저장되지 않았습니다. 키에 `jev:evaluate`가 없거나 연결 시 확인할 수 없었습니다. `FAILPROOFAI_CLOUD_TOKEN`에 키를 넣고 `failproofai config`를 다시 실행하세요. 권한이 없는 경우 **machine** 키를 사용하세요. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | 이 머신에 Jev 키가 속할 FailproofAI Cloud 연결이 없습니다. | + +`failproofai config --disconnect` 후에는 FailproofAI Cloud `jev.json`이 더 이상 없으므로(꺼진 상태로 전환된 경우는 유지됨) `status`는 단순히 Jev가 꺼져 있다고 보고합니다. `status --json`은 설정이 없거나 거부된 경우에도 동일한 정보를 전달합니다(`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`). `permissions`는 항상 `jev.json`의 것이고, `credentials.json`에 대한 거부는 `credentialsPermissions`를 추가하며, 하나의 명령으로 수정 가능한 경우 `fix`도 추가됩니다. `test`는 하나의 라이브 요청을 전송하고 지연 시간과 응답한 Jev 버전을 보고합니다. 훅 타임아웃 이후에 응답이 도착하거나(훅은 `timeout`을 기록함) 검사 질문에 잘못 답변하면 종료 코드 1로 종료되고 제목에 표시됩니다. + +대시보드의 **Settings → Jev** 패널도 **FailproofAI Cloud connection**을 표시합니다. 머신이 보고하는 조직과 키에 Jev가 포함되어 있는지를 보여줍니다. 네트워크 호출 없이 머신 자체 파일에서 읽습니다. + +## 실제 호출 확인 + +연결된 에이전트에서 새 세션을 시작합니다. 파일 읽기 도구를 사용하여 `README.md`를 읽고 제목을 보고하도록 요청합니다. 세션에 해당 도구 호출이 포함되어 있음을 확인한 후 `failproofai jev status`를 다시 실행합니다. 최근 평가된 호출 수가 증가해야 합니다. [로컬 대시보드](/ko/reference/local-dashboard#review-policy-activity)에서 **Policies → Activity**를 열어 해당 호출의 Jev 판정과 모드를 검사합니다. Cloud에서는 조직의 **Policies** 페이지에 전달된 활동의 Jev 결과가 표시됩니다. observe 모드에서 판정은 **would-have**로 기록되고 정책 결과가 여전히 호출을 결정합니다. 해제는 검토 가능한 정책이 일치하고 Jev가 명명된 검사를 해제한 경우에만 나타납니다. + +## 정책 페이지에 도달하는 정보 + +머신은 이미 훅 활동을 FailproofAI Cloud(`events:add`)로 전송합니다. Jev가 켜지면 각 게이트된 호출의 레코드에도 어떤 평가자가 실행되었는지, Jev가 무엇을 결정했는지, 어떤 정책을 해제했는지, 폴백 이유, 지연 시간, 응답한 모델이 포함됩니다. 명령이나 프롬프트는 절대 포함되지 않고 결정, 코드, 이름만 포함됩니다. 조직의 **Policies** 페이지에서: + +- Jev의 자체 판정으로 결정된 호출(enforce 모드)은 **Jev**로 귀속되며, 결정 검사가 팩에서 온 경우 레코드에 해당 팩과 버전도 표시됩니다. +- observe 모드에서 Jev의 거부 또는 경고는 관찰 중인 출시 옆에 **would-have**로 나타납니다. +- Jev가 해제했거나 observe 모드에서 해제했을 정책은 정책별로 집계됩니다. +- Jev가 참여한 결정(차단, 경고, 해제, 또는 observe 모드의 would-have)은 요청한 각 검사와 그 검사가 결론 내린 내용을 나열합니다: 판정, 이유(`not-detected`, `exempt`, `fired`, `op-requested` 등), 증거 `p`, `exempt` 답변, 각 프로브의 답변. observe로 배포된 정책의 검사도 나열되며 watched로 표시되고 차단하지 않습니다. Jev는 산문이 아닌 확률로 답변하므로 자유 텍스트 이유가 없습니다. 단순 허용은 집계 수로 롤업되며 이 목록을 가지지 않습니다. + +## Jev가 응답할 수 없는 경우 + +다음 각각은 해당 호출에 대해 정책 결과로 폴백되며 그 이유와 함께 기록됩니다: + +| 이유 | 원인 | +| --- | --- | +| `out-of-credits` | 조직의 플랜 허용량을 모두 사용했습니다. | +| `http-401`, `http-403` | 키가 취소되었거나 `jev:evaluate`를 가지고 있지 않습니다. 해당 권한이 있는 키로 다시 연결하세요. | +| `http-429` | FailproofAI Cloud가 조직의 Jev를 속도 제한하고 있습니다. 요청한 대기 시간(`Retry-After`, 최대 60초)이 끝날 때까지 머신은 아무것도 전송하지 않고 모든 호출이 즉시 폴백됩니다. 이렇게 보류된 호출은 `http-429`로 기록되거나, 머신 자체 속도 제한이 먼저 보류한 경우 `rate-limited`로 기록됩니다. | +| `http-429` (일일 한도) | 조직의 일일 Jev 호출을 모두 사용했습니다: **UTC 기준 하루 10,000회**. FailproofAI Cloud를 운영하는 사람이 다른 한도를 설정하지 않은 경우입니다. 00:00 UTC에 카운트가 초기화될 때까지 모든 호출이 폴백됩니다. 머신은 최대 1분에 한 번씩 다시 요청하므로 초기화 후 1분 이내에 감지합니다. `failproofai jev test`는 "Daily Jev limit for this org reached; resets at 00:00 UTC."라고 표시합니다. | +| `http-422` | Jev가 이 호출의 요청을 거부했습니다. 일반적으로 도구 호출에 Jev의 토큰 예산을 초과하는 밀도 높은 텍스트(base64, hex, 최소화된 코드)가 포함된 경우입니다. 이 호출은 매번 폴백되며 중단이 아닙니다. | +| `http-502` | Jev를 현재 사용할 수 없습니다. | +| `http-503` | 이 Cloud는 조직에 Jev를 제공할 수 없습니다: 모델 게이트웨이 없음, 아직 프로비저닝되지 않은 조직, 또는 게이트웨이 다운. 관리자에게 문의하세요. 훅은 최대 1분에 한 번씩 다시 요청합니다. | +| `http-404` | 이 FailproofAI Cloud는 아직 Jev를 제공하지 않습니다. | +| `timeout` | `timeoutMs` 내에 응답 없음(기본값 3000). FailproofAI Cloud가 머신의 Jev 모드를 설정하는 동안 대기 시간은 5000ms이며 `jev.json`의 `timeoutMs`는 사용되지 않습니다. | +| `model-mismatch` | 1.13이 아닌 다른 Jev 버전이 응답했습니다. | + +## 키의 위치와 용도 + +- 키는 `~/.failproofai/credentials.json`(`0600`, 소유자 전용 디렉토리)에 한 번 저장되며, 다른 FailproofAI Cloud 자격 증명과 함께 있습니다. `jev.json`은 이 경로에 대한 키를 보유하지 않습니다. 거기에 작성된 키는 설정을 무효화합니다. +- `credentials.json`이 소유자 외의 누구에게든(그룹 또는 기타, 읽기 또는 쓰기) **어떤** 권한을 부여하거나, 디렉토리가 소유자 외의 누구에 의해서도 **쓰기** 가능한 경우 읽히지 않고 **거부**되며 Jev는 수정할 때까지 꺼집니다. 파일에 `chmod 600`, 디렉토리에 `chmod 700`(또는 `0600`으로 파일을 다시 작성하고 디렉토리를 소유자 전용으로 만드는 재연결)을 실행하세요. 다른 사람이 읽기만 가능한 디렉토리는 괜찮습니다. 쓰기 가능하면 파일을 교체할 수 있습니다. +- 키는 함께 온 연결이 머신에 있는 동안만 유효합니다: 같은 파일에 같은 키를 가진 동일한 FailproofAI Cloud에 대한 정책 또는 보고 자격 증명. 연결 없이 남겨진 Jev 키는 무시되고 Jev는 꺼진 상태를 유지합니다. 이는 구버전 failproofai의 `config --disconnect`가 Jev 키를 그대로 두거나(제거 방법을 모름), 구버전 failproofai의 `config --token`이 다른 키로 연결할 때 발생합니다. FailproofAI Cloud에서는 다른 조직에 속할 수 있습니다. Jev를 다시 활성화하려면 **machine** 키로 다시 연결하세요. +- 키는 검증된 Cloud 출처에만 전송됩니다. 다른 곳을 가리키는 `jev.json`은 거부됩니다. +- **머신의 에이전트가 키를 읽을 수 있습니다.** `credentials.json`은 소유자 전용이며 에이전트는 해당 소유자로 실행됩니다. failproofai의 자체 파일 읽기는 의도적으로 허용됩니다(`block-failproofai-commands`로 변경만 차단됨). 따라서 에이전트와 이 파일 사이에 있는 것은 `block-read-outside-cwd`(검토 가능한 정책)뿐이며, 홈 디렉토리에서 시작된 세션에서는 아무것도 없습니다. `jev:evaluate`가 있는 키는 사용되는 곳 어디서나 조직의 Jev 허용량을(일일 한도까지) 소비하므로, 다른 지출 자격 증명처럼 머신 키를 취급하세요. 에이전트가 키를 읽었을 가능성이 있다면 Keys 페이지에서 비활성화하고 새 키로 다시 연결하세요. +- 전역 파일만이 이를 결정합니다. 리포지토리는 Cloud Jev를 켜거나, 다른 곳을 가리키거나, 키를 제공할 수 없으며, `FAILPROOFAI_JEV_API_KEY`는 이 경로에서 무시됩니다. +- Jev가 평가하는 각 호출에 대해 하나의 요청이 FailproofAI Cloud로 전송되며, [자체 키 페이지](/ko/reference/jev-providers#what-leaves-the-machine)에 나열된 내용(시크릿 삭제)을 포함합니다. FailproofAI Cloud는 이를 TypeSafe로 전달하며 로그하거나 보관하지 않습니다. + +## 비활성화 방법 + +연결된 머신에서 FailproofAI Cloud가 Jev 정책을 배포하지 않으면 Jev가 꺼집니다. 해당 Jev 정책을 제거하거나 아카이브하세요. + +| 명령 | 결과 | +| --- | --- | +| FailproofAI Cloud에서 머신의 Jev 정책 제거 | 다음 폴링(약 30초) 시 Cloud의 모드가 `off`가 됩니다. `jev.json`에 무슨 내용이 있든 Jev가 전혀 없습니다. | +| `failproofai config --disconnect` | 머신 연결을 끊습니다. 키가 제거되고, `jev.json`이 FailproofAI Cloud를 지정하고 꺼지지 않은 경우 함께 제거됩니다. 자체 엔드포인트용 `jev.json`은 유지됩니다. | + +다음 도구 호출부터 훅은 이전과 똑같이 정규식 정책을 실행합니다. \ No newline at end of file diff --git a/docs/ko/reference/jev-evaluations.mdx b/docs/ko/reference/jev-evaluations.mdx new file mode 100644 index 000000000..1086554c5 --- /dev/null +++ b/docs/ko/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev 평가 참조 문서" +description: "Jev 세션 평가의 질문 유형, 보정된 점수, 제한 사항 및 백필에 대한 설명입니다." +icon: "list-checks" +--- + +이 페이지는 [Jev 평가](/ko/evaluations/jev) 뒤에 있는 질문 형태와 채점 규칙을 설명합니다. 일부 질문은 모델이 대화를 *읽어야* 하지만 그에 대해 *작성할* 필요는 없습니다. "고객이 긴박함을 표현했나요?"는 두 가지 답이 있습니다. "그들이 얼마나 답답해했나요?"는 순서가 있는 몇 가지 답이 있습니다. 질문하기 전에 모든 답을 알고 있습니다. + +**분류기 평가**는 바로 그런 경우를 위한 것입니다. 질문과 가능한 답변을 작성하면, 분류 전용으로 만들어진 소형 모델이 보정된 숫자를 반환합니다 — 자유 형식 텍스트는 절대 반환하지 않습니다. + + +판사와 마찬가지로 분류기 평가는 세션당 모델 호출 비용이 발생합니다. 판사와 다른 점은 범용 모델이 아닌 작고 단일 목적의 모델이라는 것입니다. 따라서 더 빠르고 저렴하지만, 절대 스스로를 설명하지 않습니다. 추론 과정이 필요하다면 [judge](/ko/evaluations/judge)를 사용하세요. + + +## 무엇을 선택해야 할까요? + +| 질문 | 사용 방법 | +| --- | --- | +| 도구 호출이 몇 번 있었나요? | 코드 | +| 세션이 30초 미만이었나요? | 코드 | +| 고객이 긴박함을 표현했나요? | **분류기** | +| 어느 팀이 처리해야 하나요: 청구, 기술, 또는 영업? | **분류기** | +| 고객이 얼마나 답답해했나요? | **분류기** | +| 답변이 실제로 정확했나요? | **judge** | +| 에스컬레이션 정책을 따랐나요, 그리고 왜 그렇게 생각하나요? | **judge** | + +경험 법칙: **셀 수 있는 것 → 코드, 목록으로 나열할 수 있는 답변 → 분류기, 설명이 필요한 것 → judge.** + +미리 결정할 필요는 없습니다. 측정하고자 하는 것을 설명하면 어시스턴트가 선택하고, 어떤 것을 선택했는지와 그 이유를 알려주며, 변경할 수 있습니다. + +## 두 가지 질문 유형 + +### `noul` — 이것이 사실인가요? + +두 가지 답변이 있으며, 두 가지 모두 설명합니다. 결과는 "true" 설명이 맞을 확률입니다: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +양쪽 모두 설명하세요. "긴박함 표현 없음"도 실제 답변이며, 이를 명시하면 반대 답변이 더 명확해집니다. + +### `score` — 이것이 얼마나? + +순서가 있는 루브릭으로, **최악부터 시작합니다**. 결과는 세션이 루브릭에서 어디에 해당하는지를 0–1로 재조정한 값입니다: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**루브릭은 3~5개의 단계를 가지며, 모두 달라야 합니다.** 두 제한 모두 스타일이 아닌 측정 가능한 이유가 있습니다: + +- **두 단계**는 `noul`이 이미 더 잘 처리하는 것으로 축소되며, **다섯 단계 초과**는 모델이 명확한 선택 대신 중간으로 치우치게 만듭니다. 동일한 질문을 동일한 세션에서 채점했을 때 두 단계에서는 0.00, 세 단계에서는 0.01, 열 단계에서는 0.55가 나왔습니다. +- **반복된 단계**는 답변을 임의로 분할합니다. 명백히 화난 세션이 `["Calm", "Frustrated", "Very angry"]`에서는 1.00을 받았지만 `["Angry", "Angry", "Angry"]`에서는 0.66을 받았습니다 — 형식상 올바른 숫자이지만 아무 의미가 없습니다. + +순서가 없는 카테고리 — "청구, 기술, 또는 영업" — 는 루브릭이 아닙니다. 카테고리별로 `noul`로 질문하거나 judge를 사용하세요. + +## 결과 읽기 + +분류기는 judge와 마찬가지로 0에서 1 사이의 **점수**를 생성하므로, 차트 작성, 필터링, 알림 트리거 방식이 동일합니다. 알아두어야 할 두 가지 차이점이 있습니다: + +- **추론 과정이 없습니다.** 해당 필드는 의도적으로 비어 있습니다. 이 모델은 스스로를 설명하지 않으며, 설명을 만들어 내는 것은 기능이 아닌 조작이 됩니다. +- **불확실성에 레이블이 붙습니다.** `score` 질문은 자체 신뢰도를 보고하며, 모델이 확신하지 못한 결과에는 `low_confidence` 태그가 붙습니다 — 따라서 "사람이 검토해야 할 항목"은 추측이 아닌 필터로 처리됩니다. `noul` 질문은 신뢰도를 보고하지 않으므로 태그가 붙지 않습니다. + +매우 긴 세션은 발췌본으로 읽혀 합산됩니다. 세션이 너무 길어 전체를 읽을 수 없을 경우, 결과에 생략된 턴 수가 표시됩니다 — 세션의 일부를 기반으로 한 판단이 전체를 기반으로 한 것처럼 표시되는 일은 절대 없습니다. + +## 제한 사항 + +- **루브릭 단계는 3~5개로, 모두 달라야 합니다.** 위 내용 참조; 두 경계 모두 작성 시점에 적용됩니다. +- **평가당 하나의 질문만 가능합니다.** 두 가지를 묻고 싶다면 두 개의 평가를 만드세요. 차트에서도 그것이 더 유용합니다. +- **질문을 수정하면 새 버전이 게시됩니다.** 이전 점수와 새 점수는 비교할 수 없으므로, 하나의 추세선으로 혼합되지 않고 별도로 보관됩니다. +- **분류기는 항상 점수를 생성합니다** — 메트릭이나 어서션은 생성하지 않습니다. +- **추론 과정 없음**, 위 내용 참조. 숫자가 "왜?"라는 질문을 유발할 것 같다면 judge를 대신 작성하세요. + +## 테스트 및 백필 + +judge와 달리 분류기 평가는 배포 전에 **테스트할 수 있습니다** — 코드 평가와 동일한 방식으로 실제 세션에 대해 [테스트](/ko/evaluations/test)하고, 라이브 적용 전에 점수를 확인할 수 있습니다. + +이미 보유한 세션에 대해 [백필](/ko/evaluations/deploy#score-sessions-you-already-have)도 가능합니다. 세션당 모델 호출 비용이 발생하므로, 모든 것을 다시 실행하기보다는 기간을 의도적으로 설정하세요. \ No newline at end of file diff --git a/docs/ko/reference/jev-intent.mdx b/docs/ko/reference/jev-intent.mdx new file mode 100644 index 000000000..4304088bb --- /dev/null +++ b/docs/ko/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev 의도 캡처" +description: "어떤 하니스 이벤트가 Jev 평가자에게 사람이 요청한 내용을 전달하는지, 어떤 필드가 텍스트를 담고 있는지, 집계에서 절대 제외되는 것은 무엇인지, 그리고 하니스가 전달하는 프롬프트를 신뢰할 때 감수해야 하는 위험에 대해 설명합니다." +icon: "message-square-quote" +--- + +[Jev 정책 검토](/ko/policies/jev)를 구성하면, 평가자는 게이트된 각 도구 호출을 **사람이 요청한 내용**을 기준으로 판단합니다 — 하니스가 에이전트 앞에 제시한 텍스트가 아닙니다. "예, 강제 푸시하세요"와 같은 응답은 **reviewable** 정책을 통과시킬 수 있습니다 — 이것이 평가자의 핵심 존재 이유입니다. 요청을 읽지 못하는 정규식은 실제 작업의 1/3을 막아버리니까요. + +해당 텍스트는 단 하나의 출처에서 옵니다: **하니스가 프롬프트 제출 이벤트 시점에 훅에 직접 전달하는 프롬프트**. Failproof AI는 그 중 사람이 직접 입력한 부분 — 하니스 래핑 제거, 시크릿 삭제, 길이 제한 적용 후 — 을 자체 상태 디렉터리 아래 `0600` 파일에 기록합니다. 디스크에 저장된 세션 트랜스크립트는 에이전트가 명령 하나로 덮어쓸 수 있기 때문에, 프롬프트를 누가 작성했는지 판단하는 근거로 사용하지 않습니다. + +## 감수하는 위험, 솔직하게 + +이미 명령을 실행할 수 있는 에이전트는 하니스로 하여금 프롬프트를 제출하게 만들 수 있습니다. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t`, `pi -p`는 모두 사람이 직접 입력하는 것과 동일한 프롬프트 제출 이벤트를, 동일한 페이로드로, 에이전트가 제어하는 하위 세션에서 발생시킵니다. 에이전트는 Failproof AI의 훅 바이너리를 직접 실행하여 자신이 작성한 페이로드를 stdin으로 넘길 수도 있습니다. Failproof AI 내부에서는 이 둘을 실제 사람 입력과 구별할 방법이 없습니다 — 모두 같은 프로그램이 같은 stdin을 읽는 것이기 때문입니다. + +**즉, 셸을 가진 에이전트는 자신의 동의를 위조할 수 있습니다.** 이것은 2026-09-23에 의식적으로 택한 트레이드오프이며, 양면을 모두 설명합니다: + +- **무엇을 얻는가.** 대안도 만들어서 측정해 보았습니다: 하니스가 프롬프트 작성자로 사람을 명시하는 필드를 요구하고, 그렇지 않으면 아무것도 기록하지 않는 방식입니다. 출시된 어떤 하니스도 그런 필드를 보내지 않으므로, 그 버전은 **모든 하니스에서, 아무것도 기록하지 못했습니다** — Jev는 명시된 의도 없이 모든 호출을 판단했고 단 하나의 정책도 통과시킬 수 없었습니다. 절대 작동하지 않는 캡처는 더 안전한 제품이 아니라, 아무 쓸모가 없는 제품입니다. +- **할 수 없는 것.** 기록된 프롬프트는 오직 **reviewable**로 표시된 정책만 통과시킬 수 있습니다. **hard** 정책은 Jev가 무슨 말을 해도 절대 통과되지 않으므로, 위조된 프롬프트로 hard deny를 allow로 바꾸는 것은 불가능합니다 — 훅을 건너뛰어도 에이전트에게 아무 이득이 없습니다: 하니스는 도구 호출을 위해 Failproof AI를 독립적으로 호출하니까요. +- **최대로 할 수 있는 것.** 위조된 프롬프트가 할 수 있는 최악은 15개의 reviewable 내장 정책 중 하나를 통과시키는 것입니다 — **그 15개 중 12개는 차단 정책입니다**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write`와 6개의 인프라 CLI 차단(`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`)은 모두 deny이므로, 위조된 동의는 환경 시크릿 출력, `.env` 파일 읽기, 프로젝트 외부 읽기, `rm -rf`, 강제 푸시, 시크릿 파일 쓰기, 또는 라이브 인프라 변경에 대한 실제 deny를 allow로 바꿀 수 있습니다. `warn-git-amend`, `warn-destructive-sql`, `warn-global-package-install`만 경고 수준입니다. 기본 설치에서는 12개 중 2개, `protect-env-vars`와 `block-env-files`만 활성화되며, 나머지 10개는 누군가 직접 활성화한 머신에서만 적용됩니다. 프롬프트로 절대 도달할 수 없는 것은 모든 hard 정책입니다 — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, 에이전트가 Failproof AI를 비활성화하는 것을 막는 가드, 그리고 reviewable로 표시되지 않은 다른 모든 내장 정책들. [정책 권한](/ko/policies/authority)에서 15개 전체와 각각이 무엇으로 검토되는지 확인할 수 있습니다. + +여전히 거부되는 것은, 확인하기 쉽고 에이전트가 단순히 요청해서 얻을 수 없는 모든 것입니다: 하니스 자체 페이로드가 머신 제출로 표시한 턴, 서브 에이전트를 명시한 페이로드, 단순 이름이 아닌 세션 ID, 프롬프트 제출 이벤트가 아닌 이벤트, 그리고 하니스 래핑만으로 이루어진 텍스트 — 여러 하니스가 다음 사용자 턴으로 되돌려 보내는 Failproof AI 자체의 스톱 게이트 단어들 포함. + +## 하니스별 표 + +"텍스트 필드"는 Failproof AI의 하니스별 정규화 이후의 stdin 페이로드 필드입니다. "기록됨"은 해당 프롬프트가 사람의 요청으로 저장되는지 여부입니다. + +| 하니스 | `--cli` | 프롬프트 이벤트 → 정규화 | 텍스트 필드 | 기록됨 | 에이전트 마지막 메시지 출처 | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | 예, 단 페이로드의 `source`가 아무도 제출하지 않은 턴(`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`)을 명시하지 않은 경우. `user`, `sdk`, 알 수 없는 값, `source`를 아예 보내지 않는 빌드 모두 기록됨 | 세션 트랜스크립트(`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | 예 | 롤아웃 JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | 예 | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | 예, 프롬프트 전체가 `` 래퍼일 때는 벗겨냄 | 에이전트 트랜스크립트 JSONL | +| OpenCode | `opencode` | `message.updated` (user 역할) → `UserPromptSubmit` | `prompt` | 예 — 단 현재 OpenCode는 해당 이벤트에 텍스트를 담지 않으므로 실제로는 아무것도 기록되지 않음; 동일 메시지 반복은 한 번만 기록됨 | 없음 (세션이 SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | 예, 단 `input_source`가 `extension`인 경우 제외 — 텍스트가 모델이 작성하거나 저장소에서 유래할 수 있는 다른 익스텐션의 `sendUserMessage()` | Pi 세션 JSONL | +| Hermes | `hermes` | 없음 | — | 아니오 — Hermes에는 프롬프트 제출 이벤트가 없음 | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | 예, 단 실행 메타데이터가 머신 실행을 나타내는 경우 제외: `user` 이외의 `trigger`, `external_user` 이외의 `inputProvenance.kind`, 또는 `senderIsOwner: false` | 없음 (`before_agent_run`에 트랜스크립트 경로 없음) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | 예 | 드로이드 세션 JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | 예 | 없음 (세션이 SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | 없음 | 아니오 — `PreInvocation`은 한 턴의 *모든* 모델 호출 전에 발생하며 프롬프트 텍스트를 담지 않음 | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | 예 | 없음 (세션이 SQLite) | + +두 하니스가 아무것도 기록하지 않으며, 이유도 같습니다: 이벤트에 사람이 작성한 텍스트가 없기 때문입니다. Hermes에는 프롬프트 제출 이벤트가 없습니다 — 네이티브 플러그인이 `pre_llm_call`을 직접 처리하며 도구, 세션, 서브에이전트 이벤트만 전달합니다. Antigravity의 `PreInvocation`은 사람 턴과 그 이후의 다섯 번 호출 모두에서 발생하며 프롬프트 필드를 담지 않습니다; 훅은 같은 대화에 `userMessage` 단계를 주입할 수도 있습니다. 두 이벤트 어느 쪽에도 기록할 내용이 없습니다. + +## 프롬프트를 사람의 것으로 만드는 조건 + +1. **이벤트.** Failproof AI가 하니스의 프롬프트 제출 이벤트에 대해 호출되었으며, 핸들러가 이를 `UserPromptSubmit`으로 정규화합니다. +2. **페이로드.** 하니스가 훅의 stdin에 작성하며, 위에서 명시된 필드에 텍스트를 담습니다. 페이로드 없이 Failproof AI에 도달한 호출은 아무것도 기록하지 않습니다. +3. **페이로드에서 해당 턴을 제외하는 내용이 없어야 합니다.** 서브 에이전트를 명시하는 페이로드(`agent_id`)는 에이전트가 스스로에게 프롬프트를 보내는 것입니다. 머신 제출 턴을 명시하는 `source`, `input_source` 또는 OpenClaw 실행 마커는 거부됩니다. **마커가 없는** 것은 아무것도 제외하지 않습니다 — 이것이 아무것도 기록하지 않던 버전과의 차이점입니다. 여기서 언급된 모든 마커는 출시된 모든 빌드에서 없기 때문입니다. +4. **래핑을 제거한 후 남는 내용이 있어야 합니다** (아래 참조). + +**세션 트랜스크립트는 프롬프트를 누가 작성했는지의 증거가 되지 않습니다.** 이전 버전의 이 페이지에서는 트랜스크립트 교차 확인을 설명했습니다: 트랜스크립트에 모델이 프롬프트를 예약한 것이 나타나면 거부하고, 트랜스크립트가 이전 프롬프트가 본 것에서 이어져야 한다는 내용이었습니다. 그 확인은 제거되었습니다. 트랜스크립트는 에이전트가 이미 셸로 접근할 수 있는 파일입니다 — 잘라내거나, 교체하거나, 읽기 한도를 넘겨 패딩하거나, 턴 시작에 스냅샷을 찍고 끝에 복원하거나, 에이전트가 작성한 항목으로 다시 그럴듯하게 만들 수 있습니다. 강화할 때마다 같은 위조의 다른 방식이 뒤따랐으므로, 수리하는 대신 전체 메커니즘을 제거했습니다. + +트랜스크립트는 여전히 한 가지 목적으로 읽힙니다: **에이전트의 마지막으로 보이는 메시지**. 그 메시지는 정의상 에이전트가 작성한 것이며, Jev에게 그렇게 전달되고, 그 자체로는 절대 동의가 되지 않습니다. + +## 프롬프트에서 보존되는 내용 + +하니스는 사람의 말 이상을 프롬프트에 담습니다. 무언가 저장되기 전에: + +- `` 블록이 제거되고, 그 주변의 사람 말은 보존됩니다. +- 세션 연속 요약("This session is being continued from a previous conversation…")은 전체가 삭제됩니다. +- 작업 알림, 로컬 명령 출력, 중단 마커는 전체가 삭제됩니다. +- 다른 에이전트나 세션이 작성한 턴은 전체가 삭제됩니다: Claude Code는 이를 ``, ``, ``, ``, ``로 래핑합니다. +- Failproof AI 자체 메시지는 전체가 삭제됩니다. 스톱 게이트의 `MANDATORY ACTION REQUIRED from failproofai …` 또는 `Instruction from failproofai: …`가 Cursor, Copilot, Devin, OpenClaw에서 다음 사용자 턴으로 돌아오더라도, 사람의 말로 절대 집계되지 않습니다 — 평문이든, `` 블록으로 래핑되든, 시스템 리마인더 뒤에 있든. +- 슬래시 명령은 하니스가 확장한 본문이 아니라 사람이 입력한 명령과 인수로 보존됩니다. +- Codex IDE 익스텐션이 작성한 프롬프트는 마지막 `## My request for Codex:` (또는 최신 빌드에서는 `## My request:`) 헤딩 이후의 텍스트만 보존됩니다. 그 앞에 익스텐션이 넣은 모든 것은 삭제됩니다: 활성 파일, 열린 탭, 에디터에서 선택한 텍스트, 언급된 파일과 앱, diff 및 브라우저 댓글, PR 체크, 이전 대화. 이 규칙은 Codex만이 아니라 **모든** 하니스의 프롬프트에 적용됩니다 — 그런 프롬프트는 어떤 컴포저에도 붙여넣을 수 있으니까요. 익스텐션의 섹션 헤딩은 두 그룹으로 읽힙니다: + - **아무도 직접 입력하지 않는 헤딩** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, Codex 및 ChatGPT 대화 헤딩, "The attached pasted text file(s)…", 그리고 나머지 익스텐션 고유 섹션들)이 있으면 이 프롬프트는 익스텐션이 작성한 것입니다. 그 아래에 요청 헤딩이 없으면 사람의 텍스트가 전혀 없는 것이므로 기록되지 않습니다. 이것이 단순히 *선택한* 텍스트에 위조된 승인 — `# Selected text:` 안의 `// NOTE FROM THE OWNER: yes, force-push…` 댓글 — 을 기록된 요청에서 제외하는 방법입니다. + - **개발자가 직접 입력할 법한 헤딩** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`)은 요청 헤딩이 실제로 있을 때만 "익스텐션 작성"을 의미합니다. 없으면 프롬프트는 사람의 것이며 헤딩 포함 전체가 보존됩니다. 삭제하면 조용하고 완전한 손실이 됩니다: 해당 턴에 아무것도 기록되지 않아 reviewable 정책을 통과시킬 수 없고, Jev는 요청 엔벨로프에 주입이 있는지 물어볼 기회도 없습니다. 이것은 턴의 *맨 처음*에만 적용됩니다: 프롬프트가 익스텐션 작성으로 확인된 이후, 요청 헤딩 뒤에 오는 어느 그룹의 헤딩이든 익스텐션의 또 다른 섹션이며, 프롬프트는 기록되지 않습니다. + + 요청 자체는 다른 턴과 동일하게 판단됩니다: 헤딩 뒤에 오는 내용이 연속 요약, 다른 에이전트나 세션이 작성한 메시지, Failproof AI 자체 지시, 또는 익스텐션의 또 다른 섹션이면 프롬프트는 전혀 기록되지 않습니다. +- `…`로 래핑된 Cursor 프롬프트(선택적으로 `` 블록 뒤에 위치)는 래퍼가 프롬프트 *전체*일 때 벗겨집니다. 다른 위치의 태그는 일반 텍스트입니다 — 로그에서 붙여넣은 스니펫이나 에이전트가 선택한 브랜치 이름 — 이며, 태그된 부분만 잘라내는 것이 아니라 프롬프트 전체가 보존됩니다. +- 붙여넣기된 블록은 사람이 붙여넣은 것으로 표시되어 보존됩니다. + +하니스 텍스트만으로 이루어진 프롬프트는 전혀 기록되지 않습니다. + +## 에이전트의 마지막 메시지 + +"예"와 같은 응답은 그것이 답하는 질문 없이는 아무 의미가 없습니다. 프롬프트가 기록될 때, Failproof AI는 **그 순간** 세션 트랜스크립트에서 에이전트의 마지막으로 보이는 메시지도 읽어서 프롬프트와 함께 저장합니다. Jev는 별도 필드에서 이를 받으며, 에이전트가 작성한 것으로 표시됩니다: 짧은 응답을 설명하는 맥락이 되지만, 그 자체로는 절대 사람의 요청이 되지 않습니다. 트랜스크립트를 읽는 유일한 목적이 이것이며, 트랜스크립트를 재작성해서 얻을 수 있는 최악은 에이전트가 작성한 메시지가 있어야 할 자리에 에이전트가 작성한 메시지를 넣는 것입니다. + +트랜스크립트 끝에서 최대 4 MB까지 읽습니다. 지원되는 트랜스크립트 형식은 Claude Code, Codex 롤아웃(이전 `agent_message` 이벤트와 최신 `AgentMessage` 항목), Cursor, Copilot `events.jsonl`, Pi, Factory, OpenClaw 세션 JSONL입니다. Claude Code 자체의 합성 메시지, API 오류 메시지, 서브에이전트(사이드체인) 메시지는 건너뜁니다. 세션을 SQLite에 보관하는 Goose와 OpenCode, 트랜스크립트가 단일 JSON 문서인 Devin, `before_agent_run` 이벤트에 트랜스크립트 경로가 없는 OpenClaw에는 스냅샷이 없습니다. + +## 저장 + +| 속성 | 값 | +| --- | --- | +| 위치 | `~/.failproofai/state/semantic/sessions//.json`, 여기서 ``은 프롬프트가 입력된 에이전트 프로필입니다: FailproofAI가 아는 에이전트는 `.` (Cloud 정책이 대상으로 하는 ID), 그 외에는 `` | +| 권한 | 파일 `0600`, 디렉터리 `0700`. 그 위의 모든 디렉터리는 `~/.failproofai`까지 `jev.json`의 디렉터리와 동일한 규칙이 적용됩니다: 다른 사용자가 **쓸 수** 있는 디렉터리는 이름을 바꿔 대체할 수 있으므로, 읽기 경로는 가능한 경우 해당 쓰기 비트를 제거하고, 제거할 수 없는 경우 **아무것도 읽지 않습니다**. 그러면 기록된 프롬프트가 위조되는 대신 존재하지 않게 되어 아무것도 통과되지 않습니다 | +| 세션당 보관 | 최근 5개의 프롬프트; 직전과 동일한 프롬프트는 새 슬롯을 차지하지 않고 대체됨 | +| 유효 기간 | 6시간 이상 된 프롬프트는 무시됨 | +| 크기 | 각 프롬프트와 에이전트 메시지는 6,000자로 제한, 앞부분과 뒷부분 보존 | +| 시크릿 | 쓰기 전에 `sanitize-*` 정책과 동일한 패턴으로 삭제됨. 48,000자를 초과하는 텍스트는 앞 28,800자와 뒤 19,200자로 삭제되며, 시크릿이 잘려 있을 수 있는 절단 주변 텍스트는 절대 저장되지 않음 | + +세션 ID가 문자, 숫자, `.`, `_`, `-` 이외의 문자를 포함하거나 128자를 초과하면 파일 이름으로 절대 사용되지 않으므로 해당 ID에 대해서는 아무것도 기록되지 않습니다. + +세션 파일은 처음 프롬프트가 기록될 때만 생성됩니다. 프롬프트만 담으며 — 출처 상태나 트랜스크립트 마크 없음 — 6시간 창보다 오래 조용하면, 다음에 새 세션이 첫 번째 프롬프트를 쓸 때 삭제됩니다. + +프롬프트는 기록된 것과 동일한 에이전트 프로필과 세션 ID로만 다시 읽힙니다. 세션 ID는 에이전트에서 오므로 두 프로필이 같은 ID를 사용할 수 있습니다; 프로필로 키를 구분하면 한 프로필의 말이 다른 프로필의 요청으로 집계되는 일을 방지합니다. 이 레이아웃 이전의 파일들(`sessions/.json`)은 어떤 프로필이 작성했는지 알 수 없으므로, 절대 읽히지 않고 6시간 창과 함께 만료됩니다. + +Jev 엔드포인트가 구성되지 않으면 아무것도 기록되지 않습니다. FailproofAI Cloud Jev 모드에서는, 어떤 Cloud Jev 검사도 할당되지 않고 설치된 팩의 검사도 없는 에이전트 프로필에 대해서는 아무것도 기록되지 않습니다. + +### 프로젝트 루트 + +"프로젝트 내부" — `read-outside-workspace`와 다른 경로 검사가 판단하는 기준 — 는 세션의 **첫 번째 검토된 호출** 시점에 있던 프로젝트 내부를 의미합니다. 루트는 그때 고정되며 이후의 `cd`로 변경되지 않습니다; `cd`는 여전히 상대 경로의 해석에 영향을 줍니다. `cd`를 따라가게 하면 한 호출에서 `cd ~/.ssh`를 실행하여 `~/.ssh`를 다음 호출의 프로젝트로 만들 수 있습니다. + +고정값은 `~/.failproofai/state/semantic/roots/.json`에 `{root, at}`로 저장됩니다: 파일 `0600`, 디렉터리 `0700`, 그리고 위와 동일한 세션 ID 규칙. 7일보다 오래된 파일은 새 세션이 루트를 고정할 때 삭제됩니다. 다른 사용자가 쓸 수 있는 `roots` 디렉터리는 무시되고 대신 현재 디렉터리의 루트가 사용됩니다. 세션을 다시 고정하려면 해당 파일을 삭제하세요. + +## 알려진 한계 + +- **프롬프트의 신뢰도는 훅 호출만큼만 신뢰할 수 있습니다.** 여기의 모든 것은 하니스가 훅의 stdin에 작성한 페이로드를 읽습니다. 명령을 실행할 수 있는 에이전트는 하니스를 헤드리스로 실행하거나(`claude -p`와 위에 나열된 7개) Failproof AI의 훅 바이너리를 자신이 작성한 페이로드로 직접 실행하여 아무도 입력하지 않은 프롬프트를 기록할 수 있습니다. 이것은 페이지 상단에 설명된 수용된 트레이드오프입니다: reviewable 정책만 통과시킬 수 있으며 hard 정책은 절대 통과되지 않습니다 — 하지만 15개의 reviewable 내장 정책 중 12개가 deny이므로, 위조된 프롬프트는 그 12개에서 실제 차단을 allow로 바꿀 수 있습니다. +- **서브 에이전트 감지는 Claude 형태입니다.** `agent_id`를 담은 페이로드는 어떤 하니스에서도 절대 기록되지 않습니다. 이것이 Claude Code, Factory Droid, Devin이 사용하는 필드입니다. Codex는 서브 에이전트 스레드 안에서 프롬프트 이벤트를 발생시키고, Copilot은 프로세스 내 사이드킥을 실행하며, Goose는 `delegate` 도구를 가지고 OpenClaw는 페르소나를 실행합니다 — 이 중 어느 것도 페이로드에 인식 가능한 방식으로 표시하지 않으므로, 그 하니스들에서의 서브 에이전트 프롬프트는 세션 자체의 것으로 기록됩니다. OpenClaw의 `openclaw.agentId`는 **그 마커가 아닙니다**: 출시된 플러그인은 소유자의 실행 포함 모든 실행에 그것을 설정합니다. +- **마커가 없는 스케줄러.** Claude Code의 `schedule_wakeup`과 `loop_wakeup`, OpenClaw의 `cron`과 `heartbeat` 트리거는 하니스가 페이로드에서 그렇게 말하므로 거부됩니다. Goose 자체 스케줄러(`goose schedule add`)와 Codex의 `codex exec`는 아무 말도 하지 않으므로, 그것들이 시작한 실행은 다른 것과 같이 기록됩니다. +- **에이전트의 마지막 메시지는 에이전트가 선택한 메시지일 수 있습니다.** 트랜스크립트는 인증되지 않으므로, 자신의 트랜스크립트를 작성하는 에이전트는 "마지막 메시지"가 무엇을 말하는지 결정할 수 있습니다. 에이전트 작성으로 표시되며 그 자체로는 아무것도 통과시키지 않습니다 — 하지만 `decide.ts`의 v1 경로에서 결정론적 "사용자가 이 대상을 명시했는가" 검사를 통과시킬 수 있으므로, 트랜스크립트를 제어하는 에이전트는 오버라이드가 필요한 대상 이름을 제공할 수 있습니다. +- **익스텐션의 머신 헤딩으로 시작하는 프롬프트는 전체가 삭제됩니다.** `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` 또는 위 첫 번째 그룹의 다른 섹션 헤딩으로 프롬프트를 시작하고 `## My request:` 헤딩을 작성하지 않으면, 해당 턴에 아무것도 기록되지 않아 아무것도 통과되지 않습니다. 이것은 의도적입니다: 그 섹션들은 다른 사람이 제어하는 텍스트(선택한 코드, 리뷰어의 diff 댓글, 페이지 제목)를 담고 있으며, 그것을 사람의 말로 기록하는 것이 더 나쁜 실패입니다. 개발자가 직접 입력할 법한 헤딩은 두 번째 그룹에 있으며 그 자체로는 절대 프롬프트를 삭제하지 않습니다. +- **OpenCode는 실제로 아무것도 기록하지 않습니다.** 현재 OpenCode의 `message.updated` 이벤트에는 텍스트가 없으며, 작업 도구가 생성하는 하위 세션에서도 발생합니다. 그 하위 세션의 "user" 메시지는 부모 에이전트가 작성한 것입니다. +- **`CODEX_HOME`은** `lib/codex-sessions.ts`의 롤아웃 검색에서 **무시됩니다**. 이것은 에이전트 메시지 스냅샷을 찾는 위치에만 영향을 미치며, 프롬프트 기록 여부에는 절대 영향을 주지 않습니다. \ No newline at end of file diff --git a/docs/ko/reference/jev-providers.mdx b/docs/ko/reference/jev-providers.mdx new file mode 100644 index 000000000..92fdfbf08 --- /dev/null +++ b/docs/ko/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev 제공자 및 자체 키 설정" +description: "자체 키로 실시간 Jev 정책 검토를 위한 제공자 엔드포인트, 모델 ID, 구성 및 오류 동작." +icon: "key-round" +--- + +이 문서는 자체 키를 사용하는 [Jev 정책](/ko/policies/jev)의 제공자 및 구성 참조입니다. 정규식 정책은 문자열을 매칭합니다. `rm -rf build/`처럼 사용자가 직접 요청한 명령과 계획에 슬며시 포함된 `rm -rf ~`를 구별할 수 없기 때문에, 한쪽에서는 너무 많이 차단하고 다른 쪽에서는 너무 적게 차단하는 문제가 생깁니다. TypeSafe의 분류기 **Jev**는 실제로 사용자가 요청한 내용을 기준으로 호출을 분석하여, 단 한 번의 빠른 요청으로 일련의 예/아니오 질문에 답합니다. + +자체 Jev 엔드포인트와 키를 구성하면, Failproof AI는 각 도구 호출에 대해 정규식 정책과 **함께** Jev에 질문합니다. Jev가 정규식 정책을 대체하는 것이 아닙니다: + +- **하드** 정책의 거부는 최종적입니다. Jev가 이를 취소할 수 없습니다. 모든 정책은 명시적으로 검토 가능으로 표시되고 해당 정책을 커버하는 Jev 검사를 지정하지 않는 한 하드 정책입니다. 따라서 아무것도 명시하지 않은 커스텀, 팩, Cloud 정책은 하드 정책이며, 항상 활성화된 자기 보호 가드도 항상 하드입니다. +- **검토 가능** 정책의 거부는 취소될 수 있지만, Jev가 해당 정책이 다루는 정확한 우려 사항에 대해 질문을 받고 "여기에는 없음" 또는 "사용자가 이를 요청함"이라고 답한 경우에만 가능합니다. 사용자가 호출을 요청하지 않은 상황에서 우려 사항이 실제임을 발견한 검사는, 해당 검사의 자체 판정이 단순 경고에 불과하더라도 거부를 유지합니다. 도구 호출 전에는 경고가 에이전트를 중지시키지 않기 때문입니다. 그리고 해당 검사가 거부 가능한 항목(시크릿 노출, 자격 증명 유출, 파괴적 삭제 등)인 경우, 해당 호출에서는 아무것도 취소되지 않습니다. +- 호출이 사용자가 지시한 작업의 한 단계이고 그 이상으로 도달하지 않는 경우, 차단이 **경고**로 전환될 수 있습니다. Jev는 자체 거부를 경고로 완화하며, 그 경고—호출의 실제 문제를 명시하여—가 정책의 차단을 대체합니다. +- Jev는 정규식으로 설명할 수 없는 위해에 대해 자체적으로 경고하거나 거부할 수도 있습니다. +- Jev가 답할 수 없는 경우(타임아웃, 속도 제한, 서버 오류, 크레딧 없음, 예상치 못한 모델 버전), 해당 호출은 Jev 없이와 동일하게 정규식 결과를 받습니다. +- Jev는 전체 호출을 읽고 정확한 우려 사항에 대해 질문을 받은 경우가 아니라면, 정책만으로 허용되는 것보다 호출을 더 허용적으로 만들지 않습니다. 그보다 적은 것—전체를 보내기에 너무 큰 호출, 의심되는 주입—은 허가를 철회하고 모든 거부를 유지합니다. + + +Jev 구성이 없으면 아무것도 변경되지 않습니다: 훅은 항상 해왔던 것처럼 정규식 정책을 그대로 실행합니다. 구성 자체가 옵트인 전체입니다. + + + +FailproofAI Cloud를 사용 중이신가요? 자체 키가 필요하지 않습니다: `jev:evaluate`를 가진 키로 연결된 머신은 조직 플랜으로 Jev를 사용할 수 있습니다. [FailproofAI Cloud를 통한 Jev](/ko/reference/jev-cloud)를 참조하세요. + + +## 시작하기 전에 + +에이전트가 실행되는 머신에 **failproofai 1.0.8-beta.0 이상**을 설치하고 [지원되는 하네스](/ko/reference/harnesses)에 훅을 연결하세요. 새 머신이라면 [빠른 시작](/ko/start/quickstart)을 따르거나, Cloud를 사용하지 않는 경우 [로컬 적용 설정](/ko/start/setup#enforce-locally)을 따르세요. 설치된 CLI는 `failproofai --version`으로 확인하세요. + +아래 제공자 중 하나에서 API 키를 받거나, 호환 가능한 엔드포인트와 해당 키를 준비하세요. Jev는 `PreToolUse` 또는 `PermissionRequest` 게이트에서 명명된 도구 호출을 검토합니다. 자체 판정을 내릴 수 있지만, 기존 정책 거부를 취소하려면 [검토 가능](/ko/policies/authority)으로 표시된 설치된 정책도 필요합니다. 하드 정책 거부는 최종적입니다. + +## 제공자 선택 + +Jev는 다섯 가지 경로를 통해 접근할 수 있습니다. 그 중 하나의 키를 가져오세요. + +| 제공자 | `--provider` | 엔드포인트 | 기본 모델 | 참고 | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | 정확한 버전 고정. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | 요청은 제로 데이터 보존 엔드포인트로만 라우팅되며, 다른 제공자로의 폴백 없음. `typesafe/jev-1.13-20260917`과 같이 날짜가 포함된 버전을 보고함. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Jev를 별칭으로만 명명하므로, 응답 버전이 미검증으로 기록됨. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` 필요. 측정 결과 키당 초당 약 6회 호출 전에 HTTP 429 발생. | +| 자체 엔드포인트 | `custom` | `/systemone` | `jev-1.13.0` | TypeSafe의 요청 본문을 수용하고 응답한 모델을 보고하는 모든 엔드포인트. `https`만 허용; 로컬 테스트를 위해 루프백 호스트(`localhost`, `127.0.0.1`, `::1`)에 대한 일반 `http`는 허용됨. | + + +Vercel의 자체 bring-your-own-key 기능을 사용하면, 실패한 요청이 Vercel의 자격 증명으로 자동 재시도됩니다. 모든 호출이 자체 TypeSafe 계정에만 청구되고 그 계정에서만 보이도록 해야 한다면, TypeSafe를 직접 사용하세요. + + +## 설정 방법 + +명령 하나로 엔드포인트와 키를 설정합니다. 기존 정책이 호출을 계속 결정하는 동안 Jev의 판정을 검사할 수 있도록 `observe` 모드로 시작하세요: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### URL이 제공자를 선택합니다 + +제공자를 명시적으로 지정할 필요가 없습니다: URL의 **호스트**가 제공자를 결정합니다. + +| URL 호스트 | 제공자 | 추가 필요 사항 | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| 기타 모든 호스트 | `custom` | — 제공한 URL이 베이스 URL | + +이로부터 세 가지가 따릅니다: + +- **제공자 자체 API인 URL은 오버라이드를 쓰지 않습니다.** `--url https://api.typesafe.ai/v1`은 `--provider typesafe`와 정확히 동일한 구성을 생성합니다. 알려진 제공자에서 다른 경로나 호스트를 지정하면 `--base-url`이 저장하는 것처럼 베이스 URL로 저장됩니다. +- **`--provider`는 여전히 추론을 오버라이드합니다.** 이를 통해 자체 호스트에서 제공자의 API를 말하는 프록시에 접근할 수 있습니다: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **호스트와 모순되는 `--provider`는 거부됩니다.** 추측하지 않습니다. `--provider openrouter --url https://api.typesafe.ai/v1`은 아무것도 쓰지 않고 이유를 설명합니다: 두 설정이 키가 전송될 위치에 대해 불일치합니다. 동일한 쌍은 `jev setup --base-url`과 대시보드의 Jev 설정에서도 거부됩니다. (`--provider custom`은 모순이 아닙니다—"이 URL을 그대로 사용하라"는 의미입니다—단, 커스텀 경로가 도달할 수 없는 계정별 엔드포인트를 가진 Cloudflare 호스트는 예외입니다.) + +`--url`은 구성 파일의 `baseUrl`과 동일하게 검증되며, 동일한 이유로 거부됩니다: `https`, 또는 모든 모드에서 루프백 호스트(`localhost`, `127.0.0.1`, `::1`)에 대한 일반 `http`. 위험: 루프백 서버는 아무것도 인증하지 않으므로, 서버가 다운된 동안 다른 로컬 프로세스가 해당 포트를 차지하여 응답할 수 있습니다. 로컬 테스트 외에는 `https`를 사용하세요. + +### 키 + +`--key-stdin`으로 파이프로 전달하거나, 없이 터미널에서 명령을 실행하고 마스크된 프롬프트에서 키를 붙여넣으세요. 어느 쪽이든 구성 파일에 직접 저장되며 다시 출력되지 않습니다. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup`은 동일한 플래그를 받으며, URL보다 제공자를 명시적으로 지정하려는 경우 `setup --provider `를 사용합니다. + +### `--token`과 비용 + +`--token `은 키를 명령줄에 직접 입력합니다. 이는 머신을 가장 빠르게 구성하는 방법이지만, 구성 파일 외에 키가 남는 유일한 방법이기도 합니다: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +명령줄 인자는 이후 셸 히스토리 파일에 남으며, 명령이 실행되는 동안 프로세스 목록에도 나타납니다—사용자로 실행 중인 모든 것이 `/proc`에서 읽을 수 있습니다. `setup`은 `--token`이 사용될 때마다 이를 알립니다. 공유 머신, 녹화된 세션, 또는 히스토리 파일이 동기화되는 환경에서는 `--key-stdin`을 사용하세요. 이 방법으로 전달한 키는 중요한 경우 교체하세요. + + +`--token`, `--key-stdin`, `--key-from-env`는 상호 배타적입니다: 하나만 사용하세요. + +그런 다음 소규모 실시간 요청을 하나 보내 키, 엔드포인트, 응답한 Jev를 확인하세요: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test`는 타임아웃 후 답변이 도착하거나(`timeout`으로 모든 훅이 정규식으로 폴백됨) 검사 질문에 잘못 답변하면 1을 반환하며 제목에 표시합니다. + +훅은 모든 도구 호출 시 구성을 읽으므로, 다음 호출부터 적용됩니다. 데몬 유무에 관계없이 재시작할 필요가 없습니다. + +## 동작 확인 + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status`는 제공자, 엔드포인트, 모델, 모드, 구성 파일과 권한을 표시하며 키는 절대 표시하지 않습니다. 그 아래에 최근 활동을 요약합니다: Jev가 평가한 호출 수, 정규식으로 폴백한 횟수와 이유, 지연 시간, 취소한 검토 가능 정책. + +## 실제 호출 확인 + +훅이 연결된 에이전트에서 새 세션을 시작하세요. `README.md`의 파일 읽기 도구를 사용하여 제목을 보고하도록 요청하세요. 세션에 해당 도구 호출이 포함되었는지 확인한 후 `failproofai jev status`를 다시 실행합니다: 최근 평가된 호출 수가 증가해야 합니다. [로컬 대시보드](/ko/reference/local-dashboard#review-policy-activity)의 **Policies → Activity**를 열어 호출의 Jev 판정과 모드를 검사하세요. observe 모드에서는 정책 결과가 여전히 호출을 결정합니다. 검토 가능한 정책이 매칭되고 Jev가 명명된 모든 검사를 취소한 경우에만 취소가 나타납니다. 일반 읽기에는 취소할 정책이 없을 수 있습니다. + +## Observe 모드 + +`enforce`가 기본값입니다. Jev가 어떤 결정도 변경하지 않으면서 관찰하려면 `observe`로 전환하세요: Jev는 여전히 질문을 받고 판정이 기록되지만, 정규식 결과가 적용됩니다. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off`는 구성—엔드포인트와 키—을 유지하고 Jev 질문을 중단합니다: 훅은 구성 없이와 동일하게 정규식 정책을 실행하며, `failproofai jev status`는 "off (switched off)"를 표시합니다. `--mode observe` 또는 `--mode enforce`로 다시 전환하세요. + +동일한 제공자로 `setup`을 다시 실행하면 저장된 키가 유지되므로, 모드 전환은 플래그 하나면 됩니다. 제공자를 전환하면 처음부터 시작하며 해당 제공자의 키를 요청합니다. 요청을 다른 호스트로 이동시키는 `--base-url`도 마찬가지입니다: 저장된 키는 키를 제공한 호스트나 제공자의 자체 API에만 전송됩니다. + +## 구성 파일 + +모든 것은 `setup`이 작성하는 하나의 파일 `~/.failproofai/jev.json`에 있습니다: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| 필드 | 의미 | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` 또는 `custom`—또는 `failproofai`. `failproofai`의 키는 이 파일 대신 FailproofAI Cloud 연결에서 가져옵니다([FailproofAI Cloud를 통한 Jev](/ko/reference/jev-cloud) 참조). | +| `apiKey` | `Authorization: Bearer `로 전송됩니다. | +| `baseUrl` | `custom`에 필요; 그 외에는 제공자의 API 베이스를 대체합니다. `https`여야 합니다. `localhost`에 대한 일반 `http`는 `mode: observe`에서만 허용됩니다: 로컬 포트를 인증하는 것이 없으므로, 프록시가 다운된 동안 머신의 모든 프로세스(판정 대상 에이전트 포함)가 그 자리에서 응답할 수 있습니다. | +| `accountId` | Cloudflare 전용: 32자 소문자 16진수. | +| `model` | 제공자의 기본 모델 ID를 대체합니다. 버전이 지정된 ID는 Jev 1.13을 명시해야 합니다. API 키처럼 생긴 값은 거부되어 다시 출력되지 않으므로, `--model`에 붙여넣은 키는 저장되거나 모델로 전송되지 않습니다. | +| `timeoutMs` | 도구 호출이 Jev를 기다리는 시간. 100–10000, 기본값 3000. | +| `mode` | `enforce`(기본값), `observe`, 또는 `off`(구성 유지, Jev 실행 없음). | + +세 가지 규칙이 이를 보호합니다: + +- **소유자 전용.** 권한 `0600`으로 작성됩니다. 다른 사용자나 그룹이 읽거나 쓸 수 있는 사본은 **거부**되며, `chmod 600 ~/.failproofai/jev.json`을 실행하거나 `setup`을 다시 실행할 때까지 훅이 정규식으로 폴백합니다. 디렉토리도 확인됩니다: `~/.failproofai`는 다른 사람이 **쓰기 가능**해서는 안 됩니다. 거기에 쓸 수 있는 사람은 파일 자체의 권한에 관계없이 파일을 교체할 수 있기 때문입니다. `setup`은 그 쓰기 비트를 발견하면 제거합니다. `failproofai jev status`는 구성이 거부되었을 때 알리고 파일이 명명한 엔드포인트를 표시합니다: 다른 사람이 변경했을 수 있으므로, `chmod` 전에 자신의 파일인지 확인하세요. 그러한 파일에서 `setup`을 다시 실행하면 저장된 키는 제공자 자체 API에만 전달됩니다; 파일이 명명한 다른 엔드포인트는 키를 다시 필요로 합니다(`--key-stdin`), 또는 `--base-url default`로 요청을 제공자로 돌려보내세요. +- **전역 전용.** 저장소는 Jev를 활성화하거나, 다른 엔드포인트를 지정하거나, 모델을 선택할 수 없습니다: 프로젝트 내부의 `.failproofai/jev.json`은 무시되며, 제공자, URL, 모델, 계정 ID는 해당 파일에서만 읽힙니다—저장소의 에이전트 설정이 설정할 수 있는 환경에서는 절대 읽지 않습니다. (`FAILPROOFAI_HOME`은 이를 우회하는 방법이 아닙니다: Jev만 리디렉션하는 것이 아니라 정책을 포함한 전체 failproofai 디렉토리를 이동시킵니다.) +- **키만 환경에서 올 수 있습니다.** 파일에 `apiKey`가 없으면 `FAILPROOFAI_JEV_API_KEY`가 해당 세션에 대해 제공합니다(`setup --key-from-env`는 그런 파일을 작성합니다). 파일이 가진 키를 대체하지 않으며, 파일 없이 Jev를 활성화할 수 없습니다. 변수가 설정되지 않은 경우, Jev는 해당 셸에서 단순히 꺼집니다: `failproofai jev status`는 이를 알리고, 0을 반환하며 구성을 그대로 둡니다(`status --json`은 `"reason": "no-env-key"`와 함께 `"status": "key-missing"`을 보고합니다). `failproofaid` 데몬은 셸의 환경을 보지 않으므로, `failproofai config`로 설정한 머신에서는 파일에 키를 보관하세요. + +## 어떤 Jev가 응답하는가 + +Failproof AI의 결정 임계값은 Jev 1.13에 맞게 보정되었으므로, 해당 패밀리에서 답변이 올 때만 사용됩니다: `jev-1.13.x`, 또는 OpenRouter의 `typesafe/jev-1.13-`. 제공자가 Jev를 별칭으로만 명명하고 버전을 보고하지 않는 경우(Vercel, 그리고 버전을 말하지 않는 Cloudflare), 답변이 사용되지만 미검증으로 기록됩니다. `custom` 엔드포인트는 응답한 모델을 보고해야 합니다; 유일한 예외는 구성한 비버전 `--model` 이름으로, 그것이 반환될 때 동일한 방식으로 미검증으로 기록됩니다. 다른 버전을 보고하는 답변이나 버전을 보고하지 않는 `custom` 답변은 사용되지 않습니다: 해당 호출은 `model-mismatch` 이유로 정규식으로 폴백됩니다. + +## Jev가 답할 수 없을 때 + +다음 각각은 해당 호출에 대해 정규식 결과로 폴백되며 그 이유와 함께 기록됩니다. `failproofai jev status`는 이를 합산합니다: + +| 이유 | 원인 | +| --- | --- | +| `timeout` | `timeoutMs` 내에 답변 없음. | +| `http-429` | 제공자가 키의 속도를 제한함. | +| `rate-limited` | Failproof AI 자체 리미터가 전송 전 호출을 보류함: 초당 5개 요청, 최대 5개 버스트, 제공자가 `429`를 응답한 후 잠시 없음. 제공자가 아님. | +| `http-500`, `http-502`, `http-503`, … | 제공자의 서버 오류. 정확한 상태가 기록됨. | +| `out-of-credits` | HTTP 402: 제공자 계정에 크레딧이 없음. | +| `provider-refused` | Cloudflare에서 "Model execution failed (Payment error)"를 읽는 HTTP 402: 제공자가 이 요청에서 모델 실행을 거부함. 대개 청구 문제가 아니므로 크레딧 충전으로 해결되지 않음. | +| `http-401`, `http-403` | 키가 거부됨. | +| `http-404` | `/systemone`에서 아무것도 제공되지 않으므로 베이스 URL이 잘못됨—`/systemone`이 추가되며, 모든 제공자는 버전 루트에서 제공함. `failproofai jev models`는 엔드포인트가 제공하는 것을 표시함. | +| `network` | 엔드포인트에 도달할 수 없음. | +| `http-301`, `http-302`, `http-307`, `http-308` | 엔드포인트가 리디렉션으로 응답함. 리디렉션은 절대 따르지 않으므로 답변은 항상 구성의 URL에서만 옵니다; `--base-url`을 최종 URL로 설정하세요. | +| `malformed` | 엔드포인트가 응답했지만 Jev 답변이 아님—JSON이 아닌 본문이거나 답변이 없음. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare의 엔벨로프가 실패를 보고하거나, 아직 완료되지 않은 작업. | +| `model-mismatch` | 1.13 이외의 Jev 버전이 응답하거나, `custom` 엔드포인트가 응답한 모델을 명시하지 않음. | +| `request-cut` | **중단이 아닙니다.** Jev가 응답했지만 호출의 일부만 보여져 답변이 아무것도 취소하지 않음. [Jev가 응답했지만 전체 호출에 대해서가 아닐 때](#when-jev-answered-but-not-on-the-whole-call) 참조. | + +`failproofai jev status`는 `upstream-error`(제공자 자체 오류가 담긴 답변) 또는 `config`와 같은 더 드문 이유도 표시할 수 있으며, 명명할 수 없는 이유는 `other`로 합산됩니다. + +`request-cut`이 이 표에 있는 이유는 `failproofai jev status`가 나머지와 함께 집계하고, 모든 거부를 그대로 두기 때문입니다. 여기서 제공자에 대해 아무것도 말하지 않는 유일한 이유입니다: 요청이 도착했고 Jev가 응답했습니다. 위의 모든 행과 달리, 그 답변은 여전히 중요합니다—Jev 자체의 거부나 경고가 버려지는 것이 아니라 정규식 결과 위에 적용됩니다. 따라서 연속적인 `request-cut`은 호출이 전체를 보내기에 너무 큰 상태로 평가자에 도달하고 있다는 의미이지, 엔드포인트에 문제가 있다는 것이 아닙니다. 크레딧 충전이나 URL 변경으로는 해결되지 않습니다. + +## Jev가 응답했지만 전체 호출에 대해서가 아닐 때 + +두 가지 추가 상황이 발생할 수 있으며, 둘 다 Jev가 응답하지 못한 것이 아닙니다. 둘 다 호출이나 대화의 얼마나 많은 부분이 하나의 요청에 맞았는지에 관한 것입니다. + +**호출 자체의 일부가 맞지 않았습니다.** 도구 호출은 고정된 예산 안에서 전송되며, 너무 큰 것—매우 큰 `Write`, 거대한 MCP 본문, 한도까지 채워진 명령—은 맞는 부분으로 전송됩니다. Jev는 여전히 응답하며 그 답변은 여전히 중요합니다: 자체 거부나 경고가 평소와 같이 적용됩니다. 하지만 **취소**할 수는 없습니다. 호출의 일부에 대한 판정은 호출에 대한 판정이 아니기 때문입니다. 따라서 모든 정책 거부가 유지되며, 호출은 `request-cut` 이유로 폴백으로 기록됩니다. `failproofai jev status`는 이를 위의 이유들과 함께 집계합니다. 이것이 주는 규칙: 호출을 더 크게 만들면 취소를 잃을 수 있으며, 취소를 살 수는 없습니다. + +**메시지가 맞지 않았습니다.** 붙여넣은 긴 프롬프트, 에이전트의 마지막 메시지, 또는 이 평가자의 자체 저장소가 이미 한도를 초과한 프롬프트. **아무것도 변경되지 않습니다**: 호출은 다른 것과 동일하게 판정되고, 취소되고, 기록되며 폴백으로 계산되지 않습니다. 입력하는 내용의 길이는 판정을 결정하지 않으며, 잘림이 동의를 만들어낼 수 없습니다: 프롬프트가 이미 한도 초과 상태로 도착한 경우, "당신이 이것을 요청하지 않았다"는 것이 전혀 도출될 수 없는 결론이 됩니다. + +둘의 경계는 누가 텍스트를 작성했느냐입니다. 호출은 에이전트의 것이고, 길이가 심각도를 줄일 수 있도록 허용하는 규칙은 에이전트가 사용할 수 있는 규칙이 됩니다; 프롬프트는 사용자의 것이고, 그 길이를 신호로 취급하는 것은 사양이나 스택 트레이스를 붙여넣는 것을 처벌할 뿐입니다. + +## 머신에서 나가는 것 + +Jev가 평가하는 각 도구 호출에 대해, 하나의 요청이 제공자에게 전송되며 다음을 포함합니다: + +- 도구 호출 자체, API 키, 베어러 토큰, `KEY=` 할당과 같은 시크릿은 편집됨; +- 최근에 입력한 프롬프트, 에이전트의 하네스가 추가한 텍스트는 제거됨; +- 최신 프롬프트 이전 에이전트의 마지막 메시지, 에이전트 작성으로 레이블됨; +- 경로가 프로젝트 내부인지 여부—첫 번째 검토된 호출 시 세션이 있던 것으로 [세션에 고정됨](/ko/reference/jev-intent#the-project-root)—및 현재 git 브랜치와 같이 로컬에서 계산된 사실. + +구성에 있는 엔드포인트로만, 사용자의 키 아래에서 전송됩니다. + +## 끄기 + +```bash +failproofai jev remove +``` + +이는 `~/.failproofai/jev.json`을 삭제합니다. 다음 도구 호출부터 훅은 이전과 동일하게 정규식 정책을 실행합니다. `~/.failproofai/state/semantic/` 아래의 세션별 저장소(세션의 경우 `sessions/`, 프로젝트 루트의 경우 `roots/`)는 그대로 남아 만료됩니다. Jev 질문을 중단하되 구성을 유지하려면 대신 `failproofai jev setup --mode off`를 사용하세요. + +## 명령 참조 + +| 명령 | 결과 | +| --- | --- | +| `failproofai jev --url --key-stdin` | 단일 명령으로 구성; 제공자는 URL의 호스트에서 결정됨 | +| `failproofai jev --url --token ` | 동일, 명령줄에 키 포함—히스토리와 프로세스 목록에 나타남 | +| `failproofai jev setup --provider --key-stdin` | stdin으로 파이프된 키로 구성 작성 | +| `failproofai jev setup --provider ` | 동일, 마스크된 프롬프트에서 키 요청 | +| `failproofai jev setup --key-from-env` | 키 저장 없이; 세션당 `FAILPROOFAI_JEV_API_KEY` 읽기 | +| `failproofai jev setup --mode observe` | 모드 전환(`enforce`, `observe` 또는 `off`), 저장된 키 유지 | +| `failproofai jev setup --model ` / `--base-url ` | 모델 또는 API 베이스 오버라이드; `default`로 오버라이드 초기화 | +| `failproofai jev setup --timeout-ms ` | 호출당 예산 변경 | +| `failproofai jev status [--json]` | 구성, 권한 및 최근 활동; 키는 절대 표시 안 함 | +| `failproofai jev test [--json]` | 실시간 요청 하나: 지연 시간과 응답한 버전 | +| `failproofai jev models [--provider ] [--url ] [--json]` | 해당 엔드포인트의 `/models`가 보고하는 모델 ID, 구성된 것에 표시 | +| `failproofai jev remove` | 구성 삭제; Jev 꺼짐 | \ No newline at end of file diff --git a/docs/ko/reference/jev.mdx b/docs/ko/reference/jev.mdx new file mode 100644 index 000000000..dc1553124 --- /dev/null +++ b/docs/ko/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev 통합 참조" +description: "Jev의 구성, 프로바이더, 키, 요청 데이터, 실패 동작에 대한 참조 문서입니다." +icon: "braces" +--- + +Jev는 Failproof AI에서 두 가지 용도로 사용됩니다. + +| 용도 | 실행 시점 | 반환 값 | 시작하기 | +| --- | --- | --- | --- | +| 세션 평가 | 세션이 완료된 후 | 고정 답변 질문에 대한 점수 | [Jev 평가](/ko/evaluations/jev) | +| 도구 호출 정책 검토 | 게이트된 도구 호출이 실행되기 전 | 설치된 정책과 함께 제공되는 판정 | [Jev 정책](/ko/policies/jev) | + +## 참조 페이지 + +| 주제 | 세부 내용 | +| --- | --- | +| [평가 질문](/ko/reference/jev-evaluations) | 불리언 및 순서 점수 기준, 결과, 제한, 백필. | +| [프로바이더 비교 및 자체 키 설정](/ko/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare, 커스텀 엔드포인트, URL 추론, 모델 ID, `jev.json`, 모드, 폴백 코드. | +| [FailproofAI Cloud 라우트](/ko/reference/jev-cloud) | 머신 키 권한, 자동 관찰 설정, 사용량 제한, 연결 상태, 데이터 처리. | + +로컬 CLI 명령어는 [Failproof AI CLI 참조](/ko/reference/failproof-cli)에서 확인할 수 있습니다. [로컬 대시보드 참조](/ko/reference/local-dashboard#set-up-jev)에는 Jev 설정 및 활동 뷰가 설명되어 있습니다. \ No newline at end of file diff --git a/docs/ko/reference/mcp.mdx b/docs/ko/reference/mcp.mdx new file mode 100644 index 000000000..bb9327a48 --- /dev/null +++ b/docs/ko/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP 서버" +description: "자신의 권한으로 Failproof AI Cloud에 Claude, Cursor, Codex 또는 다른 MCP 클라이언트를 연결하세요." +icon: "plug" +--- + +AI 도구를 Failproof AI Cloud에 연결하여 에이전트 데이터를 활용하세요. 도구에서 세션과 이벤트를 조회하고, 읽기 전용 SQL을 실행하고, 대시보드, 알림, 이슈, 감사 로그, 정책을 읽을 수 있습니다. 권한이 있다면 알림 생성이나 정책 배포와 같은 변경 작업도 수행할 수 있습니다. + +모든 호출은 연결 시 선택한 **하나**의 조직 내에서 **본인의** 권한으로 실행됩니다. + +호스팅 또는 자체 호스팅 여부에 관계없이 모두 동일한 주소를 사용합니다: + +```text +https://gateway.befailproof.ai/mcp +``` + +## 클라이언트 연결 + +클라이언트에 주소를 추가하세요. 도구를 처음 사용할 때 브라우저가 열립니다. Failproof AI Cloud의 위치를 선택하고, 로그인한 뒤 조직 하나를 선택하고 **허용**을 클릭하세요. **취소**를 선택하면 아무것도 연결되지 않습니다. + +페이지에는 앱 이름과 반환 주소가 표시됩니다. 자체 웹 주소로 식별되지 않는 앱은 **확인되지 않은 앱**으로 표시되므로, 본인의 클라이언트에서 직접 시작한 경우에만 계속 진행하세요. + + + + claude.ai 또는 Claude Desktop에서 **설정 → 커넥터 → 커스텀 커넥터 추가**로 이동하세요. 이름을 `Failproof AI`로 입력하고, 주소를 입력한 뒤 **추가**, **연결**을 선택하세요. + + Team 및 Enterprise 플랜에서는 소유자가 먼저 조직용 커넥터를 추가합니다. 이후 각 구성원이 개인 계정을 연결합니다. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + 그런 다음 Claude Code 내에서 `/mcp`를 실행하고, `failproofai`를 선택한 뒤 **인증**을 클릭하세요. + + + `~/.cursor/mcp.json` 또는 프로젝트의 `.cursor/mcp.json`에 다음을 추가하세요: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor에서 서버 옆에 **로그인 필요**가 표시됩니다. 클릭하여 로그인하세요. + + + `~/.codex/config.toml`에 다음을 추가하세요: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + 그런 다음 `codex mcp login failproofai`를 실행하세요. + + + OAuth를 사용하는 Streamable HTTP 방식의 원격 MCP 서버를 지원하는 클라이언트라면 모두 사용 가능합니다. 위 주소를 입력하세요. 클라이언트 ID나 시크릿은 별도로 설정할 필요가 없습니다. + + + +## 연결당 하나의 조직 + +하나의 연결은 선택한 조직 내에서만 동작합니다. 두 조직을 사용하려면 서버를 `failproofai-acme`와 `failproofai-sandbox`처럼 서로 다른 이름으로 두 번 추가하고, 각각 별도의 조직에 연결하세요. + +데모 조직은 연결을 허용하지 않습니다. 본인 소유의 조직을 선택하세요. + +## 권한 + +연결은 아래 권한 범위 내에서 조직에서 본인이 할 수 있는 작업을 수행할 수 있습니다. 현재 권한을 따르므로, 관리자가 권한을 부여하면 도구도 해당 권한을 갖게 되고, 권한이 회수되면 다음 호출부터 도구도 해당 권한을 잃습니다. + +| 권한 | 도구가 할 수 있는 작업 | +| --- | --- | +| `events:read` | 이벤트 목록 조회, 세션 개요 읽기, 에이전트 및 환경 목록 조회 | +| `evaluations:read` | 세션 목록 조회, 평가 결과 및 작업 읽기 및 요약 | +| `evaluations:trigger` | 평가 생성, 새 버전 게시, 활성화/비활성화, 백필, 세션 재평가 | +| `dashboards:read`, `dashboards:write` | 대시보드 읽기, 또는 생성·이름 변경·쿼리 추가 | +| `queries:read`, `queries:write` | 저장된 쿼리 읽기, 또는 저장 및 편집 | +| `queries:run` | 읽기 전용 SQL 쿼리 실행 및 쿼리 스키마 읽기 | +| `alerts:read`, `alerts:write` | 알림 읽기, 또는 생성·편집·일시정지·삭제·테스트 | +| `issues:read` | 이슈 읽기, 확인 처리, 댓글 작성 | +| `issues:create` | 알림에서 이슈 열기 | +| `issues:close` | 이슈 해결 및 종료 | +| `audits:read`, `audits:write` | 감사 로그·실행 내역·발견 사항 읽기, 또는 감사 생성·편집 및 실행 시작 | +| `code_fixes:read` | 이슈 수정 방법 확인 및 에이전트가 수정할 수 있도록 컨텍스트 가져오기 | +| `code_fixes:write` | Failproof AI Cloud에서 수정 시작 (GitHub에 풀 리퀘스트 생성) | +| `policies:read`, `policies:write` | 정책·머신·배포 현황 읽기, 또는 정책 게시·배포·롤백 | + +조직 데이터를 읽지 않는 일부 도구는 권한이 필요 없습니다: 세션 및 이벤트 링크 생성, 이 문서 검색이 여기에 해당합니다. + +AI 도구는 API 키, 사용자, 설정, 조직 관리에 접근할 수 없으며, 이벤트를 전송할 수도 없습니다. + +## 변경 사항 승인 + +클라이언트가 프롬프트를 표시할 수 있는 경우, 쓰기 작업 전에 먼저 확인을 요청합니다. 변경될 내용을 확인하고 **이 변경 사항 승인**을 선택하면 진행됩니다. 거부하거나 약 4분 내에 응답하지 않으면 아무것도 변경되지 않습니다. 일부 클라이언트는 1분 후 대기를 중단하므로 신속하게 응답하세요. + + + 프롬프트를 지원하지 않는 클라이언트는 확인 요청을 받지 않으며, 클라이언트가 호출을 보내는 즉시 쓰기 작업이 실행됩니다. 이 경우 클라이언트 자체의 확인이 유일한 보호 수단이므로, 쓰기 도구에서는 이를 반드시 활성화해 두세요. + + +## 연결된 앱 및 연결 취소 + +**설정 → 통합 → MCP**에서 현재 조직의 연결된 앱 목록을 권한 및 최근 사용 시간과 함께 확인할 수 있습니다. **취소**를 선택하면 즉시 앱 접근이 차단됩니다. 클라이언트에서 서버를 제거해도 연결이 취소됩니다. + +조직당 최대 5개의 앱을 연결할 수 있습니다. 같은 앱을 다시 연결하면 이전 연결이 대체됩니다. + +## 자체 호스팅 배포 + +연결 시 **자체 호스팅 Failproof AI Cloud**를 선택하고 로그인에 사용하는 주소를 입력하세요. 배포 환경은 공개 HTTPS로 접근 가능해야 합니다. + +도구 호출과 그 결과는 AI 도구와 배포 환경 사이에서 호스팅된 Failproof AI 게이트웨이를 통해 전달됩니다. 게이트웨이는 이를 저장하지 않습니다. + +## 데이터 처리 방식 + +결과는 연결된 AI 도구로 전달되며, 해당 도구 제공업체의 약관에 따라 처리됩니다. 각 도구 호출에 대해 Failproof AI는 도구 이름, 결과, 소요 시간, 조직만 기록하며, 인수나 결과 내용은 절대 기록하지 않습니다. [개인정보 처리방침](https://befailproof.ai/privacy/)을 참고하세요. + +## 문제 해결 + +| 표시되는 내용 | 해결 방법 | +| --- | --- | +| "다른 브라우저에서 시작됨" | 쿠키를 허용한 상태로 클라이언트가 열어준 브라우저에서 로그인을 완료하고, 클라이언트에서 다시 시도하세요 | +| **허용** 후 오류 발생 | 링크는 한 번만 사용 가능하며 10분 후 만료됩니다. 클라이언트에서 다시 시도하세요 | +| 예상한 도구가 목록에 없음 | 이 조직에서 해당 권한을 보유하고 있지 않습니다. 관리자에게 문의하세요. 권한을 받은 후 재연결은 필요하지 않습니다 | +| 클라이언트가 계속 로그인을 요청함 | 연결이 취소되었거나, 조직을 떠났거나, 90일간 미사용 상태였습니다. 다시 연결하세요 | +| "연결된 앱이 5개입니다" | **설정 → 통합 → MCP**에서 하나를 취소한 후 다시 연결하세요 | + +여전히 문제가 해결되지 않으셨나요? [support@befailproof.ai](mailto:support@befailproof.ai)로 이메일을 보내주세요. \ No newline at end of file diff --git a/docs/ko/reference/otel.mdx b/docs/ko/reference/otel.mdx new file mode 100644 index 000000000..b6c6746ec --- /dev/null +++ b/docs/ko/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "코딩 에이전트에 OTEL을 활성화하고, 전송 상태를 확인하며, 이전 설정을 복원하세요." +icon: "radio" +--- + +`failproofai otel`은 FailproofAI Cloud에 대한 선택적 OpenTelemetry 보고를 구성합니다. 먼저 `failproofai config`로 머신을 연결하고, 조직 관리자에게 **설정 → OpenTelemetry** 활성화를 요청하세요. + +대화형 설정에서는 Cloud 키 입력 및 에이전트 선택 이후에 OpenTelemetry 관련 질문이 표시됩니다. 이 선택적 단계의 기본값은 아니요입니다. 예를 선택하면 OTEL 에이전트를 선택할 수 있으며, 연결이 저장된 후 동일한 활성화 코드가 실행됩니다. 설정 도중 Esc를 누르면 아무것도 변경되지 않습니다. 비대화형 설정, 키 직접 지정, 오픈소스 모드, 저장된 연결 유지의 경우에는 자동으로 활성화되지 않습니다. + +## 에이전트 활성화 + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +지원되는 에이전트는 `claude`, `codex`, `copilot`(VS Code)입니다. Copilot 설정에는 VS Code 실행 파일 또는 설치된 Copilot 확장이 필요합니다. 설정 디렉터리만 남아 있는 경우로는 충분하지 않으며, 둘 다 찾을 수 없으면 설정 과정에서 Copilot을 건너뜁니다. + +`--local`은 Cloud로 직접 전송하는 대신 로컬 릴레이로 전송합니다. Copilot은 인증 헤더를 설정에 저장할 수 없으므로 자동으로 릴레이를 사용합니다. + +릴레이는 사용자 머신에서만 수신 대기합니다. 구성된 FailproofAI 데몬은 몇 초 내에 변경 사항을 반영하므로 재시작이 필요하지 않습니다. 다른 애플리케이션이 릴레이 포트를 사용 중이면 상태에서 비활성으로 표시되며, 데몬은 계속 실행됩니다. + + +텍스트 캡처는 기본적으로 활성화되어 있습니다. 프롬프트 및 도구 세부 정보를 제외하려면 `--no-content`를 추가하세요. 에이전트 버전마다 다른 콘텐츠 제어 방식을 제공할 수 있으므로, 민감한 데이터와 함께 사용하기 전에 에이전트가 내보내는 항목을 확인하세요. + + +Codex는 내부 런타임 트레이스나 메트릭이 아닌 대화 로그만 내보냅니다. Codex 구성에서 `log_user_prompt = false`를 명시적으로 설정한 경우 해당 설정은 유지되며, 활성화 시 이 선택이 보존되었음을 알리는 메모가 출력됩니다. + +### 보고 경로 선택 + +에이전트에 대한 트랜스크립트 보고가 활성화된 경우 설정 과정에서 다음과 같이 묻습니다: + +> failproofai already sends Claude Code sessions to Cloud. Send them with OTEL instead? Transcript upload for Claude Code stops. + +기본값은 아니요입니다. `--yes`를 사용하면 프롬프트 없이 전환을 수락합니다. 다른 에이전트 및 정책 적용에는 영향을 미치지 않습니다. + +Codex 설정은 익스포터 설정을 작성하기 전에 데몬이 컬렉터 변경을 확인할 때까지 대기합니다. 확인이 시간 초과되면 Codex를 시작하기 전에 잠시 기다리라는 경고가 표시됩니다. + +Config v2는 기억된 트레이싱 목록을 `agents.selected`에 저장하고(감지 기록은 `agents.seen`에), 에이전트별 트랜스크립트 기본 설정은 `collector.agents..sessions`에, OTEL 소유권은 `otel.agents`에, 릴레이 설정은 `collector.otlp.enabled` / `collector.otlp.port`에 각각 유지합니다. 이렇게 키를 분리함으로써 이전 OTEL 구성을 읽을 수 있습니다. 즉, 전송 기본 설정이나 에이전트 설정 복원에 필요한 상태를 잃지 않고도 트레이싱 목록을 변경할 수 있습니다. + +## 설정 확인 + +```bash +failproofai otel status +``` + +Status는 모든 에이전트, FailproofAI의 설정 관리 여부, 대상, 조직의 수집 스위치 상태, 릴레이 상태, 마지막 릴레이 업로드 결과를 표시합니다. + +조직 스위치가 `unknown`으로 표시되면 서버가 해당 정보를 제공하지 않았거나 연결할 수 없는 상태임을 의미합니다. 이는 오류가 아니며, 이전 버전의 Cloud에서 구성을 방해하지 않습니다. + +Cloud가 아직 OTEL을 지원하지 않는 경우, 릴레이는 거부된 내보내기를 삭제하지 않고 보관합니다. 조직의 수집이 비활성화된 경우, `enable`은 아무것도 작성하지 않고 오류와 함께 종료됩니다. 관리자에게 먼저 활성화를 요청하세요. + +## 애플리케이션 구성 출력 + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +출력은 OTLP/HTTP 익스포터를 위한 셸 환경 블록입니다. Cloud 출력은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 Cloud의 OTLP 기본 주소인 `https:///otel`로 설정하며, 익스포터가 `/v1/`을 추가합니다. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`와 같은 신호별 변수에는 `https:///otel/v1/logs`와 같이 전체 URL이 필요합니다. 로컬 출력은 릴레이인 `http://127.0.0.1:`를 가리킵니다. Cloud 출력에는 구성된 API 키가 포함되므로 비밀로 취급하세요. 로컬 출력에는 키가 포함되지 않습니다. 로컬 출력을 사용하려면 먼저 로컬 에이전트를 활성화하여 릴레이가 실행 중인 상태여야 합니다. + +## 이전 설정 복원 + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable은 FailproofAI가 작성한 설정만 복원하고, 관련 없는 변경 사항은 유지하며, 각 에이전트의 이전 트랜스크립트 보고 선택을 복원합니다. 마지막으로 관리되는 로컬 에이전트가 비활성화되면 릴레이는 내보내기 수락을 중단합니다. + +Codex의 경우, disable은 `collector.agents.codex.sessions_resume_after`(에포크 밀리초)도 기록합니다. 기존 롤아웃 바이트는 전달된 것으로 처리되어 OTEL로 캡처된 세션이 다시 업로드되지 않으며, 이후에 추가된 내용은 트랜스크립트 보고를 통해 계속 전달됩니다. + +모든 명령은 `--help`를 지원합니다. 애플리케이션 및 코딩 에이전트 예제는 [OpenTelemetry in Cloud](/ko/agenteye/opentelemetry)를 참조하세요. \ No newline at end of file diff --git a/docs/ko/reference/slack.mdx b/docs/ko/reference/slack.mdx new file mode 100644 index 000000000..b451052d1 --- /dev/null +++ b/docs/ko/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack 앱" +description: "Slack에서 Failproof Assistant에게 질문하고, 스레드에서 차트를 받고, 버튼으로 변경 사항을 승인하세요." +icon: "slack" +--- + +Slack에서 [Failproof Assistant](/ko/sessions/assistant)를 사용하세요. 채널에서 앱을 멘션하거나, 다이렉트 메시지를 보내거나, `/failproof <질문>` 명령어를 사용할 수 있습니다. 답변은 **본인의** Failproof AI 권한을 기반으로 생성되며, 차트는 스레드에 전달되고, 무언가를 변경하는 작업은 먼저 승인을 요청합니다. + +공식 앱은 하나이며, Failproof AI Cloud가 호스팅 방식이든 자체 호스팅 방식이든 동일하게 작동합니다. + + + 답변은 AI 모델이 생성하므로 정확하지 않을 수 있습니다. 중요한 내용은 연결된 소스 데이터와 대조하여 확인하세요. + + +## 워크스페이스 연결 + +Failproof AI에서 `settings:write` 권한이 필요하며, Slack에서는 워크스페이스 관리자 또는 소유자이거나 앱을 추가하는 사람이어야 합니다. + + + + 1. **Settings → Integrations**으로 이동하여 **Add to Slack**을 선택합니다. + 2. Slack에서 앱을 승인합니다. + 3. Failproof AI로 돌아와 워크스페이스를 조직에 연결하는 것을 확인합니다. + + + 1. 앱을 추가한 다음 **Home** 탭을 엽니다. + 2. **Continue with FailproofAI Cloud**를 선택하거나, **Use my own URL**을 선택하고 로그인 주소를 입력합니다. + 3. 계속 버튼을 선택하고, 로그인한 후 조직을 선택하고 확인합니다. 링크는 한 번만 사용할 수 있으며 10분 후에 만료됩니다. + + + +하나의 워크스페이스는 하나의 조직에 연결되고, 하나의 조직은 하나의 워크스페이스에 연결됩니다. + +계정이 없으신가요? 먼저 [계정을 만든](https://app.befailproof.ai/login) 후 연결하세요. + +## Slack에서의 사용자 식별 + +처음 질문할 때 앱이 사용자를 다음과 같이 파악합니다. + +- **이메일로 자동 식별**: 연결된 워크스페이스의 정식 멤버이고, Slack 이메일이 확인되었으며, 조직 내에서 해당 이메일을 사용하는 멤버가 정확히 한 명인 경우 +- **그 외의 경우**: Failproof AI를 열어 Slack 사용자를 계정에 연결하는 비공개 **Link your account** 버튼이 제공됩니다. + +## 질문하기 + +| 위치 | 방법 | +| --- | --- | +| 채널 | 앱을 멘션합니다. 이후 해당 스레드에서 멘션 없이 답글을 달아 대화를 이어갑니다 | +| 다이렉트 메시지 | 앱에게 메시지를 보냅니다 | +| 앱이 참여 중인 그룹 다이렉트 메시지 | 멘션 후 스레드에서 답글로 대화를 이어갑니다 | +| Slack Connect 채널 | 앱을 멘션합니다 | +| 앱이 참여 중인 모든 대화 | `/failproof <질문>`으로 답변이 담긴 스레드를 시작합니다 | +| `/failproof help` | 앱이 할 수 있는 작업을 확인합니다 | +| `/failproof status` | 연결된 조직과 현재 연결된 계정을 확인합니다 | +| `/failproof link` | 연결된 Failproof AI 계정을 확인합니다 | + +하나의 스레드는 하나의 대화입니다. 동료들이 같은 스레드에서 앱을 멘션할 수 있으며, 각자의 권한을 기반으로 답변을 받습니다. 스레드를 시작한 사람만 멘션 없이 대화를 이어갈 수 있습니다. + +답변이 데이터인 경우, 앱은 차트나 표를 Failproof AI에서 열 수 있는 링크와 함께 게시합니다. + +## 변경 사항 승인 + +어시스턴트가 수행하는 모든 변경 작업은 먼저 **Approve**와 **Cancel** 버튼을 표시하며, **Approve** 전에 Slack이 한 번 더 확인을 요청합니다. 버튼은 질문한 사람만 사용할 수 있고, 5분 후에 만료되며, 해당 사람의 권한으로 변경이 적용됩니다. + +Slack에서 어시스턴트는 권한이 있는 경우 저장된 쿼리 및 대시보드, 평가, 알림, 감사, 이슈, 정책을 변경하고 코드 수정을 제안할 수 있습니다. API 키, 사용자, 설정은 변경할 수 없습니다. + +## 링크 미리보기 + +Slack에 붙여 넣은 Failproof AI 이슈, 세션, 평가 링크는 호스팅된 Failproof AI Cloud에서 카드로 펼쳐집니다. 카드는 링크를 붙여 넣은 사람이 볼 수 있는 내용만 표시됩니다. 자체 호스팅 주소의 링크는 카드로 펼쳐지지 않지만, 어시스턴트의 답변에 포함된 카드는 계속 표시됩니다. + +## Slack Connect 채널 + +다른 워크스페이스의 사람들도 조직의 멤버이고 계정을 연결한 경우 앱을 사용할 수 있습니다. 답변은 대화의 모든 참여자에게 표시되며, 여기에는 조직 멤버가 아닌 사람도 포함되므로, 모든 사람이 볼 수 있는 곳에서 질문하세요. + +채널 내 다른 모든 워크스페이스에서 조직과 연결된 사람이 나타날 때까지 앱이 답변하지 않습니다. 그 전까지는 앱이 질문한 사람에게 이유를 알려줍니다. + +## 앱이 요청하는 권한 + +| Slack 권한 | 이유 | +| --- | --- | +| `app_mentions:read` | 앱 멘션 감지 | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | 다이렉트 메시지 및 앱 스레드 내 답글 수신. 앱은 다른 메시지를 무시하며, 과거 대화 내용을 읽지 않습니다 | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | 대화 유형 확인을 통해 답변을 볼 수 있는 사람 파악 | +| `chat:write` | 답변 및 승인 버튼 게시 | +| `commands` | `/failproof` 명령어 제공 | +| `files:write` | 차트 게시 | +| `links:read`, `links:write` | 붙여 넣은 Failproof AI 링크 미리보기 표시 | +| `users:read`, `users:read.email` | Failproof AI 계정 매칭 및 이름 표시 | + +## 연결 해제 + +**Settings → Integrations**으로 이동하여 **Disconnect**를 선택하거나, 앱의 **Home** 탭에서 **Disconnect**를 사용하거나, Slack에서 앱을 제거하면 됩니다. + +이 중 어느 방법을 사용해도 워크스페이스 연결, 봇 토큰, 연결된 계정, 스레드 기록이 삭제됩니다. 과거 Slack 대화는 대시보드에서 계속 확인할 수 있습니다. 조직은 이후 즉시 다른 워크스페이스를 연결할 수 있습니다. + +## 데이터 및 개인정보 보호 + +질문과 답변은 스레드를 시작한 사람의 이름으로 조직 대시보드에 대화 기록으로 저장됩니다. Slack 데이터는 AI 모델 학습에 사용되지 않습니다. 앱이 수신하는 데이터와 보관 기간에 대해서는 [개인정보처리방침](https://befailproof.ai/privacy/)을 참조하세요. + +## 문제 해결 + +| 표시되는 내용 | 해결 방법 | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | 워크스페이스 관리자가 앱의 **Home** 탭을 열어 연결할 Cloud를 선택합니다 | +| "This link expired or was already used." | **Home** 탭에서 Cloud를 다시 선택하여 새 링크를 받습니다 | +| "This org is already connected to a Slack workspace." | 먼저 설정에서 연결을 해제합니다 | +| "That Slack workspace is connected to another org." | 먼저 해당 조직에서 연결을 해제합니다 | +| "Link your account to use the assistant." | 버튼을 선택하고 Failproof AI에서 확인합니다 | +| 그룹 다이렉트 메시지에서 앱이 응답하지 않는 경우 | Slack에서 앱을 다시 추가하여 그룹 권한을 부여합니다. 기존 연결은 유지됩니다 | +| "I won't post answers from your organization here" | 해당 워크스페이스에서 조직 멤버인 사람이 앱을 멘션하고 계정을 연결합니다 | + +그래도 해결되지 않는다면 [support@befailproof.ai](mailto:support@befailproof.ai)로 이메일을 보내주세요. \ No newline at end of file diff --git a/docs/ko/sessions/sentiment.mdx b/docs/ko/sessions/sentiment.mdx new file mode 100644 index 000000000..26efb7d08 --- /dev/null +++ b/docs/ko/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "감정 분석" +description: "Jev 감정 점수로 불만, 혼란, 수정 요청 메시지를 찾아보세요." +icon: "smile" +--- + +Jev는 사용자가 에이전트에게 보내는 각 메시지에 대해 네 가지 감정을 0~100점으로 채점합니다 — **분노(angry)**, **불만(frustrated)**, **만족(happy)**, **혼란(confused)** — 그리고 에이전트 성능을 나타내는 세 가지 신호도 함께 측정합니다: + +- **수정 요청(Correcting)**: 사용자가 에이전트의 답변이 틀렸다고 지적하는 경우. +- **해결됨(Resolved)**: 사용자가 에이전트가 문제를 해결했다고 확인하는 경우. +- **의심(Doubtful)**: 사용자가 에이전트의 답변이 사실인지, 또는 작업을 실제로 완료했는지 의문을 제기하는 경우. + +감정 분석을 활용하면 사용자가 인내심을 잃어가는 대화, 반복적으로 수정 요청이 발생하는 에이전트, 그리고 반응이 좋은 답변을 찾아낼 수 있습니다. 이는 Jev에 내장된 채점 기능으로, 별도로 평가를 작성할 필요가 없습니다. 직접 고정 답변 질문에 대한 평가를 만들고 싶다면 [Jev eval 생성하기](/ko/evaluations/jev)를 참고하세요. + + + 감정 분석은 관리자가 조직 단위로 활성화하기 전까지 꺼져 있습니다. Jev는 메시지당 하나의 채점 요청을 보내며, 해당 메시지와 그 직전 에이전트 답변을 함께 받습니다. 채점은 조직의 모델 예산을 사용합니다. + + +## 활성화 방법 + +1. **Administration → Settings**로 이동합니다. +2. **Human input sentiment** 항목에서 스위치를 **켜고** 저장합니다. + +지난 하루 동안의 메시지가 먼저 채점됩니다. 이후 새 메시지는 도착 후 1~2분 내에 채점됩니다. + +## 검토할 대화 찾기 + +**Observe → Sentiment**를 엽니다. 시간, 환경, 에이전트, 또는 세션 ID로 필터링할 수 있습니다. 헤더에는 메시지 및 세션 수, **플래그된** 메시지 수, 그리고 가장 두드러진 신호가 표시됩니다. 분노, 불만, 수정 요청, 혼란, 또는 의심 점수가 100점 중 35점에 도달하면 해당 메시지가 플래그됩니다. + +![메시지 및 세션 수, 플래그된 메시지, 시간별 Jev 점수를 보여주는 감정 분석 대시보드.](/images/dashboard/sentiment-overview.png) + +**Score over time** 차트를 활용해 신호를 비교하세요. 표시할 점수를 선택한 후 특정 시점을 클릭하면 해당 시간대의 메시지를 볼 수 있습니다. **By agent** 테이블은 신호가 집중된 에이전트를 보여줍니다. **Messages** 목록에서는 가장 강한 부정 점수 순으로 정렬하거나 특정 점수 하나를 선택할 수 있습니다. 메시지를 세션에서 열어 주변 대화를 읽고 무엇이 실패했는지 판단해 보세요. + +![가장 강한 부정 점수 순으로 정렬된 감정 분석 메시지 목록과 각 소스 세션 링크.](/images/dashboard/sentiment-messages.png) + +## 채점 대상 메시지 + +사람이 직접 작성한 메시지만 채점됩니다: + +- SDK를 통해 사용자 입력으로 기록된 커스텀 에이전트 메시지. +- 세션 트랜스크립트가 전송될 때(기본값) Claude Code, Codex, OpenCode, pi, Hermes, OpenClaw에 직접 입력된 프롬프트. 예약된 작업, 주입된 지침, 서브 에이전트 핸드오프, 그 외 에이전트 런타임이 직접 작성하는 텍스트는 채점되지 않습니다. `claude -p`, `codex exec`, `hermes -z`와 같은 비대화형 실행도 채점 대상이 아닙니다 — 이러한 프롬프트는 사람이 아닌 스크립트가 작성한 것이기 때문입니다. + +채점은 사용자 자신의 표현을 기준으로 판단합니다. "고쳐줘"와 같이 짧고 단도직입적인 지시는 분노로 간주하지 않으며, 질문을 하는 것 자체는 혼란으로 보지 않습니다. 새로운 요청은 수정 요청으로 보지 않으며, 단순한 감사 인사는 해결됨으로 간주하지 않습니다. \ No newline at end of file diff --git a/docs/ko/start/use-jev.mdx b/docs/ko/start/use-jev.mdx new file mode 100644 index 000000000..0ff0ba993 --- /dev/null +++ b/docs/ko/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Jev 사용하기" +description: "완료된 세션에 대한 Jev 평가를 설정하거나, 실시간 도구 호출 검토를 위한 Jev 정책을 설정합니다." +icon: "sparkles" +--- + +Jev는 에이전트 실행의 두 시점에서 도움을 줍니다. 완료된 세션을 알려진 답변과 비교하여 채점하거나, 에이전트에게 요청한 작업의 맥락에서 도구 호출을 검토합니다. + + + + 완료된 세션을 "고객이 환불을 요청했나요? 예 또는 아니오로 답하세요."와 같이 몇 가지 알려진 답변이 있는 질문과 비교하여 채점할 수 있을 때 Jev eval을 사용하세요. 세션 전반에 걸친 패턴을 찾는 데 도움이 됩니다. + + ## eval 생성하기 + + Cloud 대시보드에서 **Analyze → eval authoring → new eval**을 엽니다. 고정 답변이 있는 질문을 하나 입력하고 **draft**를 선택한 후, 분류자 점수가 선택되었는지 확인합니다. 실제 세션에서 [테스트](/ko/evaluations/test)한 다음 배포합니다. + + ![질문을 설명하고, 초안을 검토하며, 배포하는 공유 eval 작성 양식입니다. 이 스크린샷은 코드 초안을 보여줍니다. Jev에는 고정 답변 질문을 사용하세요.](/images/dashboard/eval-authoring-draft.png) + + ## 점수 확인하기 + + 새 세션이 완료된 후 **Observe → Evaluations**를 열거나 Cloud CLI를 사용합니다. + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI는 점수를 읽어옵니다. Jev eval 생성은 현재 대시보드에서만 가능합니다. 질문 유형과 예시는 [Jev evaluations](/ko/evaluations/jev)를 참고하세요. + + + 문자열 매칭 정책이 도구 호출의 안전 여부를 판단하기 위해 요청의 맥락이 필요할 때 Jev 정책 검토를 사용하세요. **observe** 모드로 시작하면 설치된 정책이 각 호출을 계속 처리하는 동안 Jev의 답변을 검사할 수 있습니다. + + Jev의 검사는 팩에서 제공됩니다. Failproof AI는 기본 팩을 제공하지 않습니다. 팩을 설치하기 전까지는 Jev가 설정되어 있더라도 아무것도 묻지 않습니다. + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Cloud Jev 설정하기 + + Cloud 대시보드에서 **Administration → Keys**를 열고 **machine** 프리셋으로 키를 생성합니다. [빠른 시작](/ko/start/quickstart)에 나와 있는 대로 `failproofai config`와 함께 사용합니다. 기존 Jev 설정이 없는 머신에서는 observe 모드로 Cloud Jev가 활성화됩니다. 다음 명령으로 연결을 확인합니다. + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## 자체 엔드포인트 사용하기 + + 로컬 대시보드에서 **Settings → Jev**를 엽니다. 프로바이더를 선택하고 토큰을 붙여넣은 후 **observe**를 선택하고 Jev를 켭니다. + + ![프로바이더, 토큰 입력란, observe 모드가 선택된 로컬 Jev 설정 패널입니다.](/images/dashboard/jev-settings.png) + + 또는 터미널에서 엔드포인트를 설정하고 테스트합니다. + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + 훅이 연결된 에이전트에게 `README.md`에 대해 파일 읽기 도구를 사용하도록 요청합니다. 해당 도구 호출이 세션에 나타나는지 확인한 다음, 로컬 대시보드의 **Policies → Activity**에서 검사합니다. observe 결과가 올바르게 보이면 [Jev policies](/ko/policies/jev)에서 적용 시점을 확인하세요. 프로바이더 세부 정보와 설정은 [통합 레퍼런스](/ko/reference/jev)를 참고하세요. + + \ No newline at end of file diff --git a/docs/policies/authority.mdx b/docs/policies/authority.mdx new file mode 100644 index 000000000..bfdd33707 --- /dev/null +++ b/docs/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Policy authority" +description: "Which policy verdicts the Jev semantic evaluator may clear, and which are final." +icon: "scale" +--- + +When you configure [Jev policy review](/policies/jev) through FailproofAI Cloud or your own key, each gated tool call is judged by the policies you run and by Jev, which asks what the call actually does and whether the person who typed the task asked for it. Each policy's **authority** decides what happens when the two disagree. + +Without Jev configured, authority has no effect. Every policy enforces exactly as it always has. + +## Hard and reviewable + +- **Hard** is the default. A hard policy's deny or instruction is final: Jev cannot clear it, and a hard deny stops the call without waiting for Jev. +- **Reviewable** means Jev may clear the policy's verdict, but only through the semantic checks the policy names in `reviewedBy`. The verdict is cleared only when **every** named check was asked about this call and each one either found nothing or recorded the user asking for this. A check that **fired** — found the concern — without the user asking keeps the block, even when its own verdict is only a warning. A check Jev was not asked, because it does not apply to that tool, never clears anything, whatever the others said. One softening counts as consent: when the call is a step of the task the user gave and reaches no further, Jev turns a deny into a warning, and that warning clears the policy's block and is what the agent is told. + +A policy is reviewable only when all of these hold: + +1. It declares `authority: "reviewable"`. +2. `reviewedBy` is a non-empty list, and every entry is a Jev check an installed pack declares. Failproof AI ships no Jev checks: the [sixteen below](#semantic-policy-names) come from `failproofai policies add FailproofAI/jev-policies`. With no pack declaring checks, every policy is hard. +3. It is not `alwaysOn`. The guard that stops an agent from disabling Failproof AI is always hard. + +Anything else is hard: a missing field, a misspelled value, an empty or malformed `reviewedBy`, or a name that is not a check this machine can ask. An unknown name makes the whole declaration hard rather than being skipped, because `reviewedBy` means "all of these must be asked, and none of them may deny", and skipping a name would let Jev clear the policy on fewer checks than you asked for. + +Once Jev is configured, Failproof AI logs a warning when it refuses a `reviewable` declaration, once per process. Without Jev it says nothing, because authority then decides nothing. `failproofai publish` refuses to build a pack that carries such a declaration, so a pack author finds out before anyone installs it. It judges `reviewedBy` against the checks the pack declares when it declares any, and against the sixteen `FailproofAI/jev-policies` names otherwise. + +## Where authority is declared + +Each way a policy reaches a machine has one place that decides its authority: + +| Source | Declared in | Default | +| --- | --- | --- | +| Built-in policies | The table below | Hard unless listed as reviewable | +| Your own policy files | `authority` and `reviewedBy` on `customPolicies.add` | Hard | +| Policy packs | Each policy's entry in the pack manifest (`failproofai-pack.json`) | Hard | +| Cloud-managed policies | The policy's assignment in the active deployment | Hard. Deployments do not set it yet, so every cloud-managed policy is hard today. | + +For a pack or a cloud-managed policy, fields set inside the policy code are ignored; the manifest or the assignment decides. A pack can only describe its own policies: its policy names cannot contain `/` and are registered under the pack's own prefix, so no manifest can mark a built-in policy or another pack's policy as reviewable. A policy a pack's code registers without declaring it in the manifest is hard. + +Two packs, or two cloud-managed policies, whose code is byte-identical share one artifact and load as one policy. That policy is reviewable only if every one of them declares it reviewable, and Jev must then clear every check any of them names. If any of them declares it hard, or does not declare it at all, it stays hard. The order the packs or policies are listed in never matters. + +Most machines get the built-in policies from the `FailproofAI/policies` pack, and read their authority from that pack's manifest. The reviewable entries below take effect once a release of the pack that carries them is installed; an older release carries none, so every policy in it stays hard. + +## Declare authority in your own policy + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` copies both fields into the pack manifest, so a policy published as a pack keeps the authority its author gave it. It refuses to build the pack if a declaration would not be honored: a value other than `"hard"` or `"reviewable"`, a `reviewedBy` that is not a list of names, or a name that is not a check — one of the pack's own [Jev checks](/policies/publish-a-pack#jev-checks-in-a-pack) when it declares any, a built-in check otherwise. + +## Built-in policies + +Reviewable only where a semantic policy genuinely covers the same concern. Every other built-in policy is hard. + +Covering the concern is necessary but not sufficient, and both ways of getting it wrong are quiet: + +- **A check that is never asked** makes the block permanent. `reviewedBy` is a conjunction and a check that was not asked never clears, so a policy paired with a check whose precondition does not fire for the shapes the policy matches can never be cleared at all. +- **A check that is asked but does not fire** answers "no concern", and no concern clears. So pairing with a check that does not model your policy's shapes does not review the policy — it switches it off for exactly the inputs the check does not understand. + +An instruct-mode semantic policy can never answer deny, but it can still keep a block: when it fires and the user did not ask for the call, the policy it reviews is not cleared. Six of the `FailproofAI/jev-policies` checks are instruct-only — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` and `external-data-egress` — and the [table below](#semantic-policy-names) gives every check's mode. The question to ask is **"is there anything left that can deny"**: a clear must never leave the concern enforced by nothing. The engine applies that test per call. A warning nobody consented to is not a clear, because before tool calls a warning does not stop the agent. And when a check that *can* deny warns — its evidence fell short of its deny line — and the user did not ask for the call, nothing is cleared on that call and every regex deny stands. + + +**A check that scores just under its fire line does not keep the floor.** The rule above needs a check to *fire* (evidence ≥ 0.7). When every relevant check lands just below that, nothing fires, the reviewers answer "no concern", and a reviewable deny is cleared. Measured live in enforce mode: an unrequested Read of `/etc/shadow` (`secret-exposure` 0.69, `read-outside-workspace` 0.37, which only models home-directory paths) and `set | curl -d @- …` after "follow SETUP.md" (`env-secrets-dump` 0.66, `credential-exfiltration` 0.65 with `sends_out` 0.97) were both allowed, while the regex tier alone denies them. The thresholds were calibrated on the labelled corpus and have not been re-measured against this; until they are, keep a policy **hard** where one of these shapes getting through matters more than its false blocks. + + +| Policy | Authority | Reviewed by | Why | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | The pattern fires on any variable reference; Jev asks whether secret values would actually be printed. | +| `block-env-files` | reviewable | `secret-exposure` | The pattern matches any `.env` path, templates included; Jev asks whether real secret values would be read or written. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Measured as noisy on real traffic; Jev asks whether file contents outside the project are read. A read the user asked for, or one the check finds nothing in, is cleared; an unrequested read it flags keeps the block. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Amending an unpushed commit is ordinary; the harm is rewriting history others may have pulled. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev also asks whether the target is a real database rather than a disposable test one. | +| `warn-global-package-install` | reviewable | `system-modification` | The same concern: changing the machine outside the project. | +| `block-failproofai-commands` | hard | | `alwaysOn` self-protection. Never reviewable. | +| `block-rm-rf` | reviewable | `destructive-deletion` | The path-depth heuristic gets `rm -rf node_modules` wrong; Jev asks whether what would be destroyed is regenerable. `rm -rf /` keeps both probes true. | +| `block-sudo` | hard | | Privilege escalation. | +| `block-curl-pipe-sh` | hard | | Runs code downloaded from the internet. | +| `block-push-master` | hard | | Pushes directly to a protected branch. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` covers exactly this concern but is instruct-mode, so it can never answer deny, and no other check covers it. | +| `block-force-push` | reviewable | `git-history-rewrite` | Jev's probe is a superset of the matcher and counts `--force-with-lease`; what clears is force-pushing your own branch. | +| `block-secrets-write` | reviewable | `secret-exposure` | The path match is unanchored, so `src/auth/credentials.ts` is caught; Jev asks whether real key material is being written. | +| `block-kubectl` | reviewable | `production-infra-change` | Denies the whole CLI, read-only subcommands included; Jev asks whether the call mutates and whether the target is production. | +| `block-terraform` | reviewable | `production-infra-change` | Same: clears `terraform plan` and `validate`. | +| `block-aws-cli` | reviewable | `production-infra-change` | Same: clears `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | reviewable | `production-infra-change` | Same: clears `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | reviewable | `production-infra-change` | Same: clears `az account show`. | +| `block-helm` | reviewable | `production-infra-change` | Same: clears `helm list`, `helm status`. | +| `block-gh-pipeline` | hard | | Triggers pipelines, merges and secret changes. | +| `warn-git-stash-drop` | hard | | No semantic check covers discarding stashed work. | +| `warn-git-clean` | hard | | `destructive-deletion` covers the concern but demonstrably cannot fire on it: `git clean` names no path, so its `irreplaceable` probe has nothing to judge and answers low, and evidence is the minimum over a policy's probes. A check that is asked and does not fire clears the verdict, so pairing here would switch the policy off. | +| `warn-all-files-staged` | hard | | No semantic check covers what a wide `git add` picks up. | +| `warn-schema-alteration` | hard | | `database-destruction` covers dropping data, not altering a schema. | +| `warn-package-publish` | hard | | Publishing is irreversible and no semantic check covers it. | +| `prefer-package-manager` | hard | | A team convention, not a safety judgment. | +| `warn-large-file-write` | hard | | A size threshold, not a judgment Jev can make. | +| `warn-background-process` | hard | | No semantic check covers detached processes. | +| `warn-repeated-tool-calls` | hard | | Counts calls; Jev cannot count. | +| `sanitize-jwt` | hard | | Redacts tool output; not a tool-call gate. | +| `sanitize-api-keys` | hard | | Redacts tool output; not a tool-call gate. | +| `sanitize-connection-strings` | hard | | Redacts tool output; not a tool-call gate. | +| `sanitize-private-key-content` | hard | | Redacts tool output; not a tool-call gate. | +| `sanitize-bearer-tokens` | hard | | Redacts tool output; not a tool-call gate. | +| `require-commit-before-stop` | hard | | A session-completion gate, not a tool-call gate. | +| `require-push-before-stop` | hard | | A session-completion gate, not a tool-call gate. | +| `require-pr-before-stop` | hard | | A session-completion gate, not a tool-call gate. | +| `require-no-conflicts-before-stop` | hard | | A session-completion gate, not a tool-call gate. | +| `require-ci-green-before-stop` | hard | | A session-completion gate, not a tool-call gate. | + +## Semantic policy names + +These are the checks `FailproofAI/jev-policies` declares, and the values `reviewedBy` accepts once it is installed. Failproof AI itself ships none of them: without that pack (or another declaring these names), no policy naming them is reviewable. Each is a check Jev answers about the tool call in front of it. **Mode** is what a check can answer: a `deny` check blocks on strong evidence, while an `instruct` check only ever warns. Either keeps a policy's deny standing when it fires and the user did not ask for the call. **User can override** says whether the human's own explicit request clears it. + +Jev asks exactly the [Jev checks](/policies/publish-a-pack#jev-checks-in-a-pack) installed packs declare, and those are the names `reviewedBy` accepts. A name two packs declare differently is honoured for neither. One of these sixteen names declared by a pack not installed from a FailproofAI repository is ignored in that pack: its version is never asked and does not contest FailproofAI's own, so a third-party pack can neither become the check that clears the core pack's policies nor switch one of these checks off. An unreadable pack list, or a pack whose every check is unusable, leaves Jev nothing to ask. + +| Name | Mode | User can override | What Jev checks | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | yes | Permanently deleting data that cannot be regenerated. | +| `production-infra-change` | deny | yes | Changing live infrastructure. | +| `git-history-rewrite` | deny | yes | Rewriting or discarding shared git history. | +| `push-to-protected-branch` | instruct | yes | Pushing directly to a protected branch. | +| `commit-on-protected-branch` | instruct | yes | Committing directly on a protected branch. | +| `secret-exposure` | deny | yes | Reading or copying credentials. | +| `credential-exfiltration` | deny | no | Sending secrets or private files off the machine. | +| `remote-code-execution` | deny | yes | Running code downloaded from the internet. | +| `privilege-escalation` | deny | yes | Running with elevated privileges. | +| `database-destruction` | deny | yes | Destroying or mass-modifying database data. | +| `read-outside-workspace` | instruct | yes | Reading files outside the project. | +| `agent-config-tampering` | deny | no | Changing the agent's own safety configuration. | +| `system-modification` | instruct | yes | Changing the system outside the project. | +| `env-secrets-dump` | instruct | yes | Printing environment secrets. | +| `external-destructive-action` | deny | yes | An irreversible action through an external tool. | +| `external-data-egress` | instruct | yes | Sending private data to an external tool. | diff --git a/docs/policies/deploy.mdx b/docs/policies/deploy.mdx index a6c7cfcfd..9f328ab60 100644 --- a/docs/policies/deploy.mdx +++ b/docs/policies/deploy.mdx @@ -70,6 +70,98 @@ A machine appears under **Admin → enforcement** once it is connected to Cloud. +## Target an agent on a machine + +Published policy versions do not contain agent-routing rules. By default, an assignment +applies to **all agents on its machine**. When deploying a version, you can instead +target an integration (including profiles added later) or a particular profile +reported by that machine. The choice belongs to the machine's assignment: the +same published version can target different agents on different machines. + + + + 1. In **Admin → enforcement**, expand the machine and select **edit**. + 2. On the policy's **agents** control, keep **all agents**, select **all hermes profiles** (for example), or search for a reported profile by its label and `agt_` ID. You can select multiple alternatives; a call matches if it belongs to any one of them. + 3. Review the target listed for **each** assignment in the deployment plan, apply the change, then check the machine's reported deployment after its next check-in. History and rollback retain the selected targets. + + + ```bash + fp fleet show + fp fleet deploy --add no-force-push --target no-force-push=hermes + fp fleet deploy --target no-force-push=hermes/agt_1234567890abcdef + fp fleet deploy --all-agents no-force-push + ``` + + `--target POLICY=INTEGRATION[/agt_ID]` sets one policy's scope. Repeat + `--target` for more alternatives on the same assignment. Use `--all-agents POLICY` + to clear that assignment's targeting. `fp fleet show` and `fp fleet history` + display the selected scope. Review the complete replacement plan before + applying, especially when deploying from a script. + + + +The machine must have recently reported support for agent targeting before you +can set a new target. You can select an exact profile only if that machine +reported it with a hook installed and it is not stale. If the inventory is +temporarily unavailable, existing targets remain assigned; they are not +silently broadened to all agents. Reinstall older shell hooks to provide the +profile hint used by new installations. After upgrading the CLI, run +`failproofai config` to update and restart its daemon too: an older daemon +cannot evaluate new profile-scoped calls and the hook refuses the mismatch. +If the running agent's profile cannot +be identified (for example, when several settings scopes are installed but +the hook does not report which one ran), **targeted assignments do not match**; +unscoped policies still apply. Look for `agent_scope_unresolved` under that +machine's policy errors. + +A machine reports only the agents it traces: one entry per profile whose +config carries the FailproofAI hook (Hermes and OpenClaw get one per profile, +named by its label). An agent CLI that is merely installed is not listed. + +Each machine keeps up to 256 profiles in its roster. A profile's ID never +changes while it is listed. When the roster is full and a new profile with a +FailproofAI hook appears (its hook runs, or its config carries the hook), the +daemon makes room by dropping one profile that meets all of these: + +- it has no hook installed; +- no assignment names it; +- FailproofAI Cloud would not accept it as a new target. + +The daemon prefers a profile no longer found on the machine, then the one +unused longest. It never drops a profile an exact target uses, so those +targets stay valid. If no profile can be dropped, the new profile has no ID +yet, and targeted assignments do not match it until a slot frees up. + +## Deploy Jev checks + +A Cloud policy can carry Jev checks as well as, or instead of, JavaScript. Its kind is `jev` (Jev checks only) or `both` (JavaScript whose verdict its own checks may clear). It deploys, toggles and rolls back exactly like any other policy. + +Jev checks run on FailproofAI Cloud; nothing is installed on the machine. The machine receives only the JavaScript of a `both` policy. While a `jev` or `both` policy is deployed to it, FailproofAI Cloud turns Jev on for the machine, and each checked tool call of an agent the policy targets goes to FailproofAI Cloud, which asks the checks deployed to that agent and returns their verdict. With none deployed, Jev is off there. There is no Jev mode to set by hand. + +```bash +fp policies publish prod-db-intent --kind jev --semantic ./checks.json +fp fleet deploy --add prod-db-intent:observe +``` + +To trial Jev checks without them deciding anything, deploy the policy with `:observe`: its checks are asked and their answers recorded as "would have", and they neither block nor clear anything. Redeploy it as `enforce` once the policy page shows what they would have done; then Jev's checks **block** calls as well as clearing the JavaScript verdicts they review. A `both` policy deployed with `:observe` observes both halves. + +A `both` policy's JavaScript can be cleared only by its own checks' answers from FailproofAI Cloud. An installed pack's check of the same name never clears it. If FailproofAI Cloud cannot be reached, or sets no mode that asks, the policy stays **hard**: every deny of its JavaScript stands. + +Agent targeting works for Jev-only policies too. For a `both` policy, the +assignment's one target governs **both** its local JavaScript and its Cloud Jev +checks; a call outside that target runs neither half. Keep the +policy at `observe` while trialing scoped checks, just as you would for an +unscoped Jev rollout. + +A machine reports what stops it from asking, and `fp fleet show ` lists it under policy errors: + +- `transcripts_disabled`: the machine was connected with `--no-transcripts`. Such a machine never sends tool calls to Jev. +- `jev_unconfigured`: the machine's key does not carry Jev. +- `jev_rate_limited`: some calls were refused for the organization's Jev rate limit and decided by the regex policies alone. +- `jev_unavailable`: FailproofAI Cloud's Jev failed several calls in a row, so the machine skips it for a minute at a time. + +One Jev request carries a limited amount of question text. FailproofAI Cloud's checks come before the checks of packs installed on the machine. A pack check that does not fit is left out and reported as `jev_budget`. A pack check with the same name as one of your organization's Cloud checks is left out too, and reported as `jev_name_clash`: the Cloud check is asked in its place. + ## Check coverage Coverage answers whether a policy is running where the risk is. diff --git a/docs/policies/jev-byok.mdx b/docs/policies/jev-byok.mdx new file mode 100644 index 000000000..237354d07 --- /dev/null +++ b/docs/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev evaluator (bring your own key)" +description: "Let TypeSafe's Jev classifier judge your agents' tool calls above a hard regex floor, through your own Jev endpoint and key." +icon: "key-round" +--- + +Regex policies match strings. They cannot tell `rm -rf build/` that you asked for from `rm -rf ~` that slipped into a plan, so they block too much in one place and too little in another. **Jev**, TypeSafe's classifier, reads the call against what you actually asked for and answers a set of yes/no questions about it in one fast request. + +With your own Jev endpoint and key configured, Failproof AI asks Jev about each tool call **alongside** the regex policies, never instead of them: + +- A **hard** policy's deny is final. Jev cannot clear it. Every policy is hard unless it is explicitly marked reviewable and names the Jev checks that cover it, so a custom, pack or Cloud policy that says nothing is hard, and the always-on self-protection guard is always hard. +- A **reviewable** policy's deny may be cleared, but only when Jev was asked about the exact concern that policy covers and answered "nothing here" or "the user asked for this". A check that finds the concern real, when the user did not ask for the call, keeps the deny — even when its own verdict is only a warning, because before a tool call a warning does not stop the agent. And when that check is one that can deny (secret exposure, credential exfiltration, destructive deletion, …), nothing is cleared on that call. +- A block can still become a **warning** when the call is a step of the task you gave and reaches no further: Jev softens its own deny to a warning, and that warning — naming what is actually wrong with the call — replaces the policy's block. +- Jev can also warn or deny on its own, for harm no regex describes. +- If Jev cannot answer (timeout, rate limit, server error, no credits, an unexpected model version), that call gets the regex result, exactly as without Jev. +- Jev never makes a call more permissive than your policies alone unless it read the whole call and was asked about the exact concern. Anything less — a call too big to send whole, a suspected injection — withdraws the clearances and keeps every deny. + + +Without a Jev config nothing changes: hooks run the regex policies exactly as they always have. The config is the whole opt-in. + + + +On FailproofAI Cloud? You do not need a key of your own: a machine connected with a key that carries `jev:evaluate` can use Jev on your organization's plan. See [Jev through FailproofAI Cloud](/policies/jev-cloud). + + +## Choose a provider + +Jev is reachable through five routes. Bring a key for any one of them. + +| Provider | `--provider` | Endpoint | Default model | Notes | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Exact version pin. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Requests are routed to zero-data-retention endpoints only, with no fallback to another provider. Reports a dated version such as `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Names Jev only by an alias, so the answering version is recorded as unverified. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Needs `--account-id`. About six calls a second per key were measured before HTTP 429. | +| Your own endpoint | `custom` | `/systemone` | `jev-1.13.0` | Any endpoint that accepts TypeSafe's request body and reports which model answered. `https` only; plain `http://localhost` is accepted in shadow mode only. | + + +With Vercel's own bring-your-own-key feature, a failed request is silently retried with Vercel's credentials. If you need every call billed to, and seen by, your own TypeSafe account only, use TypeSafe directly. + + +## Set it up + +One command, the endpoint and the key: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### The URL picks the provider + +You do not have to name the provider: the URL's **host** is which one it is. + +| URL host | Provider | Also needs | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| any other host | `custom` | — the URL you gave is the base URL | + +Three things follow from that: + +- **A URL that is the provider's own API writes no override.** `--url https://api.typesafe.ai/v1` produces exactly the config `--provider typesafe` would have. Give a different path or host on a known provider and it is stored as the base URL, as `--base-url` would store it. +- **`--provider` still overrides the inference**, which is how you reach a proxy that speaks a provider's API from a host of your own: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **A `--provider` that contradicts the host is refused**, not guessed at. `--provider openrouter --url https://api.typesafe.ai/v1` writes nothing and says why: the two spellings disagree about where your key is about to be sent. The same pair is refused from `jev setup --base-url` and from the dashboard's Jev settings. (`--provider custom` is not a contradiction — it means "treat this URL as itself" — except on Cloudflare's host, whose per-account endpoint a custom route cannot reach.) + +`--url` is validated exactly as the `baseUrl` in the config file is, and refused in the same words: `https`, or plain `http://localhost` in shadow mode only. + +### The key + +Pipe it in with `--key-stdin`, or run the command in a terminal without it and paste the key at a masked prompt. Either way it goes straight into the config file and is never printed back. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` takes the same flags and is the longhand for all of it: `setup --provider ` where you would rather name the provider than the URL. + +### `--token`, and what it costs + +`--token ` puts the key on the command line, which is the fastest way to configure a machine and the only spelling that leaves the key anywhere but the config file: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +A command-line argument is in your shell's history file afterwards, and while the command runs it is in the process list — readable from `/proc` by anything running as you. `setup` says so every time `--token` is used. Prefer `--key-stdin` on a machine you share, in a recorded session, or anywhere the history file is synced; rotate a key you have passed this way if it matters. + + +`--token`, `--key-stdin` and `--key-from-env` are mutually exclusive: give one. + +Then send one small live request to check the key, the endpoint and which Jev answered: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` exits 1, and says so in its title, when the answer arrives after the timeout (every hook would fall back to regex as `timeout`) or answers its check question wrongly. + +Hooks read the config on every tool call, so it applies from the next one. There is nothing to restart, with or without the daemon. + +## Check what it is doing + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` shows the provider, endpoint, model, mode, the config file and its permissions, and never the key. Below that it summarizes recent activity: how many calls Jev evaluated, how often it fell back to regex and why, its latency, and which reviewable policies it cleared. + +## Shadow mode + +`enforce` is the default. To watch Jev without letting it change any decision, switch to `shadow`: Jev is still asked and its verdicts are recorded, but the regex result is what is enforced. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` keeps the config — the endpoint and the key — and stops asking Jev: hooks run the regex policies exactly as without a config, and `failproofai jev status` says "off (switched off)". Switch back with `--mode shadow` or `--mode enforce`. + +Re-running `setup` for the same provider keeps the stored key, so a mode switch is one flag. Switching provider starts over and asks for that provider's key. So does a `--base-url` that moves requests to a different host: a stored key is only sent to the host it was given for, or to its provider's own API. + +## The config file + +Everything lives in one file, `~/.failproofai/jev.json`, written by `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Field | Meaning | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` or `custom` — or `failproofai`, whose key comes from the FailproofAI Cloud connection instead of this file (see [Jev through FailproofAI Cloud](/policies/jev-cloud)). | +| `apiKey` | Sent as `Authorization: Bearer `. | +| `baseUrl` | Required for `custom`; replaces the provider's API base otherwise. Must be `https`. Plain `http` to `localhost` is accepted only with `mode: shadow`: nothing authenticates a local port, so while your proxy is down any process on the machine, including the agent being judged, could answer in its place. | +| `accountId` | Cloudflare only: 32 lowercase hex characters. | +| `model` | Replaces the provider's default model id. A versioned id must name Jev 1.13. A value shaped like an API key is refused (and not repeated back), so a key pasted into `--model` is never stored or sent as the model. | +| `timeoutMs` | How long a tool call waits for Jev before using the regex result. 100–10000, default 3000. | +| `mode` | `enforce` (default), `shadow`, or `off` (keep the config, run no Jev). | + +Three rules protect it: + +- **Owner-only.** It is written with permissions `0600`. A copy that any other user or group can read or write is **refused**, and hooks fall back to regex until you run `chmod 600 ~/.failproofai/jev.json` or `setup` again. The directory is checked too: `~/.failproofai` must not be **writable** by anyone else, because whoever can write there can replace the file whatever its own permissions are. `setup` takes those write bits off if it finds them. `failproofai jev status` says when a config has been refused and shows the endpoint the file names: someone else could have changed it, so check it is yours before you `chmod`. Re-running `setup` on such a file carries its stored key only to the provider's own API; any other endpoint it names needs the key again (`--key-stdin`), or `--base-url default` to send requests back to the provider. +- **Global only.** A repository cannot turn Jev on, point it at another endpoint or pick its model: a `.failproofai/jev.json` inside a project is ignored, and the provider, URL, model and account id are read only from that file — never from the environment, which a repository's agent settings can set. (`FAILPROOFAI_HOME` is not a way around that: it moves the whole failproofai directory, your policies included, rather than redirecting Jev on its own.) +- **The key alone may come from the environment.** If the file has no `apiKey`, `FAILPROOFAI_JEV_API_KEY` supplies it for that session (`setup --key-from-env` writes such a file). It never replaces a key the file holds, and it cannot turn Jev on without the file. Where the variable is not set, Jev is simply off for that shell: `failproofai jev status` says so, exits 0 and leaves the config alone (`status --json` reports `"status": "key-missing"` with `"reason": "no-env-key"`). The `failproofaid` daemon does not see your shell's environment, so on a machine set up with `failproofai config`, keep the key in the file. + +## Which Jev answers + +Failproof AI's decision thresholds were calibrated on Jev 1.13, so an answer is used only when it comes from that family: `jev-1.13.x`, or OpenRouter's `typesafe/jev-1.13-`. Where a provider names Jev only by an alias and reports no version (Vercel, and Cloudflare when it does not say), the answer is used and recorded as unverified. A `custom` endpoint must report the model that answered; the one exception is an unversioned `--model` name you configured for it, which, echoed back, is recorded as unverified in the same way. An answer reporting any other version, or a `custom` answer reporting none, is not used: that call falls back to regex with the reason `model-mismatch`. + +## When Jev cannot answer + +Each of these falls back to the regex result for that call and is recorded with its reason, which `failproofai jev status` totals: + +| Reason | Cause | +| --- | --- | +| `timeout` | No answer within `timeoutMs`. | +| `http-429` | The provider rate-limited the key. | +| `rate-limited` | Failproof AI's own limiter held the call back before sending it: 5 requests a second, in bursts of up to 5, and none for a moment after the provider answers `429`. Not the provider. | +| `http-500`, `http-502`, `http-503`, … | A server error at the provider. The exact status is recorded. | +| `out-of-credits` | HTTP 402: the provider account has no credits left. | +| `provider-refused` | HTTP 402 from Cloudflare reading "Model execution failed (Payment error)": the provider declined to run the model on this request. Usually not billing, so topping up will not move it. | +| `http-401`, `http-403` | The key was refused. | +| `http-404` | Nothing is served at `/systemone`, so the base URL is wrong — `/systemone` is appended to it, and every provider serves it at its version root. `failproofai jev models` shows what the endpoint does serve. | +| `network` | The endpoint could not be reached. | +| `http-301`, `http-302`, `http-307`, `http-308` | The endpoint answered with a redirect. Redirects are never followed, so the answer only ever comes from the URL in your config; set `--base-url` to the final URL. | +| `malformed` | The endpoint answered, but not with a Jev answer — a body that is not JSON, or one with no answers in it. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare's envelope reported a failure, or a job that had not finished. | +| `model-mismatch` | A Jev version other than 1.13 answered, or a `custom` endpoint did not say which model answered. | +| `request-cut` | **Not an outage.** Jev answered; it was shown only part of the call, so its answer cleared nothing. See [When Jev answered, but not on the whole call](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` can show a few rarer reasons too, such as `upstream-error` (the answer carried the provider's own error) or `config`, and totals any reason it cannot name as `other`. + +`request-cut` is in this table because `failproofai jev status` totals it with the rest, and because it too leaves every deny standing. It is the one reason here that says nothing about your provider: the request arrived and Jev answered it. Unlike every row above it, that answer still counts — Jev's own deny or warning applies on top of the regex result rather than being discarded. So a run of them means calls are reaching the evaluator too big to send whole, not that your endpoint is unwell, and topping up credits or changing the URL will not move the number. + +## When Jev answered, but not on the whole call + +Two more things can happen, and neither is Jev failing to answer. Both are about how much of the call, or of the conversation, fitted into one request. + +**Part of the call itself did not fit.** A tool call is sent inside a fixed budget, and an outsized one — a very large `Write`, a huge MCP body, a command padded out to the cap — is sent with what fitted. Jev still answers, and its answer still counts: its own deny or warning applies as usual. What it cannot do is **clear** anything, because a verdict given on part of a call is not a verdict on the call. So every policy deny stands, and the call is recorded as a fallback with the reason `request-cut`, which `failproofai jev status` totals alongside the reasons above. The rule this gives you: making a call bigger can cost it its clearances, and can never buy one. + +**A message did not fit.** A long prompt you pasted, the agent's last message, or a prompt this evaluator's own store had already capped. **Nothing changes**: the call is judged, cleared and recorded exactly as any other, and it is not counted as a fallback. The length of what you type never decides a verdict, and a cut cannot manufacture consent: where a prompt arrived already capped, "you did not ask for this" stops being a conclusion that can be drawn from it at all, rather than becoming one. + +The line between the two is who wrote the text. The call is the agent's, and a rule that let its length subtract severity would be a rule the agent can use; your prompt is yours, and treating its length as a signal only ever punished pasting a spec or a stack trace. + +## What leaves the machine + +For each tool call Jev evaluates, one request goes to your provider, carrying: + +- the tool call itself, with secrets such as API keys, bearer tokens and `KEY=` assignments redacted; +- the recent prompts you typed, with text your agent's harness added removed; +- the agent's last message before your latest prompt, labelled as agent-written; +- facts computed locally, such as whether a path is inside the project — the one the session was in at its first reviewed call, [pinned for the session](/reference/jev-intent#the-project-root) — and the current git branch. + +It goes only to the endpoint in your config, under your key. + +## Turn it off + +```bash +failproofai jev remove +``` + +This deletes `~/.failproofai/jev.json`. From the next tool call, hooks run the regex policies exactly as before. The per-session stores under `~/.failproofai/state/semantic/` (recorded prompts in `sessions/`, project roots in `roots/`) are left in place and age out. To stop asking Jev but keep the config, use `failproofai jev setup --mode off` instead. + +## Command reference + +| Command | Outcome | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configure it in one command; the provider comes from the URL's host | +| `failproofai jev --url --token ` | Same, with the key on the command line — your history and the process list see it | +| `failproofai jev setup --provider --key-stdin` | Write the config from a key piped on stdin | +| `failproofai jev setup --provider ` | Same, asking for the key at a masked prompt | +| `failproofai jev setup --key-from-env` | Store no key; read `FAILPROOFAI_JEV_API_KEY` per session | +| `failproofai jev setup --mode shadow` | Switch mode (`enforce`, `shadow` or `off`), keeping the stored key | +| `failproofai jev setup --model ` / `--base-url ` | Override the model or API base; `default` clears the override | +| `failproofai jev setup --timeout-ms ` | Change the per-call budget | +| `failproofai jev status [--json]` | Configuration, permissions and recent activity; never the key | +| `failproofai jev test [--json]` | One live request: latency and the version that answered | +| `failproofai jev models [--provider ] [--url ] [--json]` | The model ids that endpoint's `/models` reports, marking the configured one | +| `failproofai jev remove` | Delete the config; Jev is off | diff --git a/docs/policies/jev-cloud.mdx b/docs/policies/jev-cloud.mdx new file mode 100644 index 000000000..f2903d856 --- /dev/null +++ b/docs/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev through FailproofAI Cloud" +description: "Let Jev judge your agents' tool calls through FailproofAI Cloud, on your organization's plan, with no TypeSafe account or key of your own." +icon: "cloud" +--- + +[Jev](/policies/jev-byok), TypeSafe's classifier, reads each tool call against what you actually asked for and answers alongside your policies, never instead of them. Through **FailproofAI Cloud**, a connected machine uses Jev with the same key it already connects with: no TypeSafe account, no second key, no endpoint to configure. Each call is charged to your organization's existing plan allowance. + +Everything Jev does is unchanged from the [bring-your-own-key setup](/policies/jev-byok): hard policies stay final, a reviewable policy's deny is cleared only when Jev was asked about exactly that concern, and any failure falls back to the regex result for that call. + + +Requires **failproofai 1.0.8-beta.0** or later. 1.0.7 has no Jev, even though it sorts above the 1.0.7 betas. Without a Jev config nothing changes: hooks run the regex policies exactly as they always have. + + +## Turn it on + +1. **Create a key with Jev.** In the FailproofAI Cloud dashboard, open **Keys → Create key** and pick the **machine** preset. It grants the three permissions a machine needs: `events:add` (send activity), `policies:pull` (receive policies) and `jev:evaluate` (Jev, charged to your organization's plan). A key cannot carry `jev:evaluate` without the other two. +2. **Connect the machine** with that key: + + ```bash + failproofai config --token + ``` + + If your organization runs its own FailproofAI Cloud rather than the hosted one, add its address: `--url https://` (or export `FAILPROOFAI_CLOUD_URL`). Without it the key is checked against the hosted service and the connection fails. If that host's certificate comes from a private CA, install the CA in the machine's system trust store (for example with `update-ca-certificates`), not only in `NODE_EXTRA_CA_CERTS`: the daemon that sends events and pulls policies reads the system store. See [Troubleshooting](/reference/troubleshooting). + +That is all. Connecting stores the key and, when the machine has **no** Jev config yet, turns Jev on through FailproofAI Cloud in **shadow** mode: Jev is asked about every gated tool call and its verdicts are recorded, but your policies' result is what is enforced. The output says so: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**With `--no-transcripts`, connecting does not turn Jev on.** Jev sends each checked tool call and the recent prompt to FailproofAI Cloud, which is more than a decisions-only connection asked to send. The key is still stored, and the output says Jev is available and how to switch it on: + +```bash +failproofai jev setup --provider failproofai +``` + +It does not turn Jev **off** either. If the machine's `jev.json` already runs Jev through FailproofAI Cloud, it is left as it is, and the output says that Jev still sends each checked tool call and the recent prompt, and that `failproofai jev setup --mode off` switches it off. + + +Connecting **never overwrites** an existing `~/.failproofai/jev.json`. If you already use your own Jev endpoint, it keeps being used, and the output says the file was left as configured — and, when that file leaves Jev off (refused, or switched off), says so and how to fix it. To switch that machine to FailproofAI Cloud, run `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce or off + +Start in shadow, watch what Jev would have done on the policy page, then let it act: + +```bash +failproofai jev setup --mode enforce # Jev's verdicts apply: it may clear a reviewable deny and add its own +failproofai jev setup --mode shadow # Jev is asked and logged; your policies' result is enforced +failproofai jev setup --mode off # keep the config, stop asking Jev +``` + +The same switch is in the local dashboard: **Settings → Jev** has an on/off switch and shadow/enforce. It rewrites the mode and nothing else. Hooks read the config on every tool call, so a change applies from the next one, with no restart. + +## Check what it is doing + +```bash +failproofai jev status +failproofai jev test +``` + +`status` shows the provider as **FailproofAI Cloud**, the Cloud host the machine connected to, the mode, and the key source as **FailproofAI Cloud connection**, never the key. When a FailproofAI Cloud `jev.json` is in place but Jev cannot run, it says why: + +| `status` says | `status --json` | Meaning | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | The machine is connected, but no Jev key is stored for it: the key lacks `jev:evaluate`, or the connect could not confirm it. Run `failproofai config --token ` again with the same key; if it lacks the permission, use a **machine** key. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | There is no FailproofAI Cloud connection on this machine for the Jev key to belong to. | + +After `failproofai config --disconnect` there is no FailproofAI Cloud `jev.json` any more (unless it was switched off, which is kept), so `status` simply reports Jev as off. `status --json` carries the same facts (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), also when the config is absent or refused. `permissions` is always `jev.json`'s; a refusal about `credentials.json` adds `credentialsPermissions`, and `fix` when one command fixes it. `test` sends one live request and reports its latency and the Jev version that answered. It exits 1, and says so in its title, when the answer arrives after the hook timeout (hooks would record `timeout`) or answers its check question wrongly. + +The dashboard's **Settings → Jev** panel also shows the **FailproofAI Cloud connection**: which organization the machine reports into and whether its key carries Jev. It is read from the machine's own files, with no network call. + +## What reaches the policy page + +The machine already sends its hook activity to FailproofAI Cloud (`events:add`). With Jev on, each gated call's record also says which evaluator ran, what Jev decided, which policies it cleared, why it fell back when it did, its latency and the model that answered — decisions, codes and names, never the command or your prompt. On your organization's **Policies** page: + +- a call Jev's own verdict decided (enforce mode) is attributed to **Jev**, and when the deciding check came from a pack, the record also names that pack and its version; +- in shadow mode, Jev's deny or warning appears as a **would-have**, next to the rollouts you are observing; +- the policies Jev cleared, or would have cleared in shadow mode, are counted per policy. + +## When Jev cannot answer + +Every one of these falls back to your policies' result for that call, and is recorded with its reason: + +| Reason | Cause | +| --- | --- | +| `out-of-credits` | Your organization has used its plan allowance. | +| `http-401`, `http-403` | The key was revoked, or does not carry `jev:evaluate`. Reconnect with a key that does. | +| `http-429` | FailproofAI Cloud is rate-limiting Jev for your organization. Until the wait it asks for is over (its `Retry-After`, at most 60 seconds), the machine sends it nothing and every call falls back straight away. Calls held back that way are recorded as `http-429`, or as `rate-limited` when the machine's own rate limit holds them first. | +| `http-429` (daily limit) | Your organization has used its daily Jev calls: **10,000 per UTC day**, unless whoever operates your FailproofAI Cloud has set another limit. Every call falls back until the count resets at 00:00 UTC; the machine still asks again at most once a minute, so it picks the reset up within a minute. `failproofai jev test` says "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev refused this call's request, usually because the tool call held dense text (base64, hex, minified code) over Jev's token budget. That call falls back every time; it is not an outage. | +| `http-502` | Jev is unavailable right now. | +| `http-503` | This Cloud cannot serve Jev for your org: no model gateway, an org not provisioned yet, or the gateway is down. Ask your admin; hooks ask again at most once a minute. | +| `http-404` | This FailproofAI Cloud does not serve Jev yet. | +| `timeout` | No answer within `timeoutMs` (default 3000). | +| `model-mismatch` | A Jev version other than 1.13 answered. | + +## Where the key lives, and where it goes + +- The key is stored once, in `~/.failproofai/credentials.json` (`0600`, in an owner-only directory), beside the other FailproofAI Cloud credentials. `jev.json` holds no key for this route; one written there makes the config invalid. +- If `credentials.json` carries **any** permission for anyone but you (group or other, read or write), or its directory can be **written** by anyone but you, it is **refused**, not read, and Jev is off until you fix it: `chmod 600` on the file, `chmod 700` on the directory (or reconnect, which rewrites the file at `0600` and makes the directory owner-only). A directory others can only read is fine; one they can write lets them swap the file. +- The key counts only while the connection it came with is on the machine: a policy or reporting credential for the same FailproofAI Cloud **with the same key**, in the same file. A Jev key left behind without one is ignored, and Jev stays off. That happens when an older failproofai's `config --disconnect` leaves the Jev key in place (it does not know to remove it), or when an older failproofai's `config --token` connects with another key, which on FailproofAI Cloud may belong to another organization. To switch Jev back on, connect again with a **machine** key. +- The key is only ever sent to the Cloud origin it was verified against. A `jev.json` pointing anywhere else is refused. +- **An agent on the machine can read it.** `credentials.json` is owner-only, and the agent runs as that owner. Reading failproofai's own files is allowed on purpose (only changing them is blocked, by `block-failproofai-commands`), so the only thing between an agent and this file is `block-read-outside-cwd` — a *reviewable* policy — and from a session started in your home directory, nothing. A key with `jev:evaluate` spends your organization's Jev allowance (up to the daily cap) from wherever it is used, so treat a machine key like any other spending credential: if an agent may have read it, disable it on the Keys page and reconnect with a new one. +- Only your global files decide this. A repository cannot turn Cloud Jev on, point it elsewhere or supply its key, and `FAILPROOFAI_JEV_API_KEY` is ignored for this route. +- For each call Jev evaluates, one request goes to FailproofAI Cloud, carrying what the [bring-your-own-key page](/policies/jev-byok#what-leaves-the-machine) lists (secrets redacted). FailproofAI Cloud forwards it to TypeSafe and does not log or keep it. + +## Turn it off + +| Command | Outcome | +| --- | --- | +| `failproofai jev setup --mode off` | Keep the config; Jev is not asked. **This is the switch that lasts:** connecting again never rewrites an existing `jev.json`, so Jev stays off until you switch it back with `--mode shadow`. | +| `failproofai jev remove` | Delete `~/.failproofai/jev.json`; Jev is off — until the next `failproofai config --token` with a key that carries `jev:evaluate`, which finds no `jev.json` and turns Jev on again in shadow mode (unless it runs with `--no-transcripts`). To keep it off, use `--mode off`. | +| `failproofai config --disconnect` | Disconnect the machine: the key is removed, and so is `jev.json` when it names FailproofAI Cloud and is not switched off. A `jev.json` for your own endpoint stays, and so does one switched off, so Jev stays off when you connect again. | + +From the next tool call, hooks run the regex policies exactly as before. diff --git a/docs/policies/jev.mdx b/docs/policies/jev.mdx new file mode 100644 index 000000000..ebb9c34b2 --- /dev/null +++ b/docs/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Add Jev's live review to gated tool calls, then inspect it before enforcing its decisions." +icon: "shield-check" +--- + +Jev reads a tool call against what the person asked the agent to do. Use it when a string-matching policy blocks valid work or misses a risky action that needs context. It answers alongside your policies at the `PreToolUse` or `PermissionRequest` gate. For a score **after** a session ends, use [Jev evaluations](/evaluations/jev). + +## Start in observe mode + +Install Failproof AI and attach hooks to a [supported harness](/reference/harnesses). Use failproofai 1.0.8-beta.0 or later. + +Failproof AI ships no Jev checks. Install them as a pack, or Jev has nothing to ask and is never called: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Then choose how requests reach Jev: + +| Route | First step | +| --- | --- | +| FailproofAI Cloud | Connect with a **machine** key carrying `jev:evaluate`. On a machine with no Jev config, `failproofai config` turns Jev on in observe mode. | +| Your own provider | In the local dashboard, open **Settings → Jev**, choose the provider, paste its token, and select **observe**. Or run `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![The local dashboard's Jev settings: provider, endpoint, token, and observe mode before turning Jev on.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` checks the endpoint. To check the hook path, ask a hooked agent to use its file-reading tool on `README.md`. Confirm that tool call appears in the session, then inspect **Policies → Activity** in the [local dashboard](/reference/local-dashboard#review-policy-activity). The Jev count in `status` should increase. Observe mode records what Jev would have decided while your existing policy result still applies. + +## Decide when to enforce + +A **hard** policy always has the final say. Jev may clear a deny only from a policy explicitly marked **reviewable** and only when it checked that policy's named concern. See [policy authority](/policies/authority) before relying on a clearance. Jev can also warn or deny on its own. If it cannot answer, the policy result decides that call. + +Once the observe results look right, switch to enforce mode in **Settings → Jev** or run: + +```bash +failproofai jev setup --mode enforce +``` + +For provider URLs, Cloud keys, configuration, fallbacks, and data sent with each request, see the [Jev integration reference](/reference/jev). diff --git a/docs/policies/overview.mdx b/docs/policies/overview.mdx index 83b83b3a7..4bbd38c7b 100644 --- a/docs/policies/overview.mdx +++ b/docs/policies/overview.mdx @@ -37,6 +37,10 @@ There are two ways to get one. +## Review tool calls with Jev + +Jev reads a gated tool call in the context of your request. It can flag a concern that a string-matching policy missed or clear a deny from a policy explicitly marked **reviewable**. Hard policies remain final. [Start with Jev policies](/policies/jev), then use the [integration reference](/reference/jev) when you need provider or configuration details. + ## Then ship it diff --git a/docs/policies/packs.mdx b/docs/policies/packs.mdx index 196a788df..3c32139fc 100644 --- a/docs/policies/packs.mdx +++ b/docs/policies/packs.mdx @@ -19,7 +19,7 @@ Browse every pack, and every policy in each, on the [policy hub](https://befailp failproofai policies add FailproofAI/policies ``` -The pack carries 38 policies and switches on the 10 its manifest marks safe to enable unattended; the rest are listed for you to choose from. Some of the most used, and whether a plain `policies add` switches them on: +The pack carries 39 policies and switches on the 10 its manifest marks safe to enable unattended; the rest are listed for you to choose from. Some of the most used, and whether a plain `policies add` switches them on: | Policy | What it does | On by default | | --- | --- | --- | @@ -77,7 +77,7 @@ failproofai policies add FailproofAI/policies --category dangerous-commands # a failproofai policies add FailproofAI/policies --all # everything in it ``` -`--category` and `--policy` combine as a union (`--only` is accepted as a synonym for `--policy`). When the pack is already installed, the flags add to what you had, and re-adding it with no flag and no terminal — to upgrade, say — keeps your selection as it is. At a terminal with no flag, `add` opens the picker instead, pre-ticked with the author's defaults, and what you tick replaces your selection. +`--category` and `--policy` combine as a union (`--only` is accepted as a synonym for `--policy`), and each may be repeated: `--policy a --policy b` takes both. When the pack is already installed, the flags add to what you had, and re-adding it with no flag and no terminal — to upgrade, say — keeps your selection as it is. At a terminal with no flag, `add` opens the picker instead, pre-ticked with the author's defaults, and what you tick replaces your selection. ## Manage what is on @@ -103,12 +103,14 @@ Scopes, parameters, and the files these commands write are covered in [local con `SHA256SUMS` ships in the same release as the artifact, so it is **not** a signature and proves nothing about who published it. What it does prove is that the bytes are the ones that release published — and because the digest is recorded when you add the pack and re-verified before every import, a pack cannot change under your machine afterwards. A repository that retags or replaces an asset stops loading instead of quietly running something else. -At install time the pack is also **imported once** and checked against its own manifest. A pack whose artifact does not parse, or that registers something other than what it declares, is refused before anything is activated — rather than installing cleanly and failing on your next tool call. +At install time the pack is also **imported once** and checked against its own manifest. A pack whose artifact does not parse, or that registers something other than what it declares, is refused before anything is activated — rather than installing cleanly and failing on your next tool call. So is a pack whose id claims the `FailproofAI/` namespace but whose release is not in a FailproofAI repository. ## When a pack will not load A pack this machine was told to enforce and cannot run **denies** the events its missing policies covered, rather than allowing them silently — as `pack/failproofai-pack-unavailable`, which outranks the policies that did load so the deny is attributed to the missing pack rather than to whichever guard happened to fire first. The exception is `UserPromptSubmit`, which instructs instead: denying there would lock you out of the agent you need in order to fix it. See [Failure behavior](/policies/failure-behavior). +A pack can name the oldest failproofai it works with (`minCliVersion`, set by its publisher). An older CLI refuses to add it and prints the upgrade command, `npm i -g "failproofai@>=" && failproofai update` (a range, so npm picks a release that meets it — a bare `failproofai` installs `latest`, which can be older than a prerelease minimum); one already installed that the running CLI is too old for does not load, with the result above. A `minCliVersion` the CLI cannot read is ignored with a warning rather than refusing the pack. + ## Offline and mirrors | Variable | Effect | diff --git a/docs/policies/publish-a-pack.mdx b/docs/policies/publish-a-pack.mdx index 0ca827f4b..558c9292f 100644 --- a/docs/policies/publish-a-pack.mdx +++ b/docs/policies/publish-a-pack.mdx @@ -36,6 +36,19 @@ customPolicies.add({ `defaultEnabled` defaults to **false** when you omit it. A plain `failproofai policies add` switches on only what you marked — installing a stranger's every policy unattended is not a decision the installer should make for its user. +A policy may also declare `authority: "reviewable"` with a `reviewedBy` list, which lets the Jev semantic evaluator clear its verdict on machines that configure Jev. `failproofai publish` copies both into the manifest, and a machine reads them from there; it refuses to build if a declaration would not be honored, such as a misspelled check name or, in a pack that declares Jev checks, a check it does not declare. Leave them out and the policy is hard. See [Policy authority](/policies/authority). + +### Jev checks in a pack + +A pack can also carry [Jev checks](/reference/policy-sdk#jev-checks) — `semanticPolicies.add()` — beside its policies, or on their own. A pack is the only way a Jev check reaches a machine: in a local policy file it is never asked. `publish` validates each one with the loader's rules and writes them to the manifest's `semantic` array. + +- **Limits.** At most 24 checks per pack. Together, their questions must fit what one Jev request has room for, less what the 16 `FailproofAI/jev-policies` checks take first where both are installed (about 9,100 characters are left) unless the repository is FailproofAI's; `publish` refuses a pack over that budget and prints the numbers. Other packs' checks share the same room, so a check that does not fit beside them is not asked there: `policies add` names it. +- **They are the only checks Jev asks.** Failproof AI ships no Jev checks, so a machine asks exactly what its installed packs declare — yours, beside [`FailproofAI/jev-policies`](/policies/authority#semantic-policy-names) where that is installed. Checks from several packs add up; when their questions overflow what one Jev request can carry, FailproofAI's checks are kept first and the rest are dropped with a warning. A name two packs declare differently is honoured for neither — every policy naming it stays hard — while identical declarations of one name are fine. The 16 `FailproofAI/jev-policies` names are reserved: declared by a pack not installed from a FailproofAI repository, that pack's version is never asked, so `publish` refuses one there; pick names of your own. +- **`reviewedBy` names the pack's own checks.** When the pack declares any, `publish` judges every `reviewedBy` against those names only, so a `FailproofAI/jev-policies` name the pack does not declare itself is refused. A pack with no checks of its own is judged against those sixteen names. +- **Set `--min-cli-version`.** A CLI too old for Jev checks ignores the `semantic` array and installs the rest, so pass `--min-cli-version ` for a pack that carries checks. It is written to the manifest as `minCliVersion`: an older CLI refuses to install the pack, and refuses to load it if it is already installed — which, for an `enforce` pack with policies, denies what those policies cover (see [When a pack will not load](/policies/packs#when-a-pack-will-not-load)). The value must be plain semver or `publish` refuses it; a CLI that cannot compare a stored value warns and ignores it. For a pack with checks it must be at least `1.0.8-beta.0`, the first release that runs a pack's checks as published (1.0.7 ignores them, 1.0.7-beta.x replaces the built-in checks with them): `publish` refuses a lower value, and writes `1.0.8-beta.0` when you pass none. + +A pack of Jev checks alone (no `customPolicies.add`) is refused by a CLI too old for Jev checks ("pack manifest declares no policies") and ignored if already installed. If a machine refuses such a pack when loading it (a `minCliVersion` it does not meet, a missing or altered artifact), it reports why and denies nothing, because the pack blocks nothing without Jev. Older builds do not all agree: 1.0.7 loads one as an empty pack but denies every tool call if its artifact is missing or altered, and a Jev-capable prerelease before 1.0.8-beta.0 (such as 1.0.7-beta.2) denies every tool call whenever it refuses one, including for a `minCliVersion` above it. So before rolling a machine back, remove the pack (`failproofai policies remove `); `publish` prints this reminder for a pack of Jev checks alone. + Write as many files as you like; one per category reads well. Every file in the directory that registers policies is bundled into the single artifact a pack has to be. @@ -60,7 +73,7 @@ failproofai publish It works out where to publish, what to bundle and what version to call it, and only asks when nothing in the repository tells it. In order, stopping before it creates a release if anything is wrong: -1. Finds the policy files here by **content** — those that import `failproofai` and call `customPolicies.add` — rather than by filename, so it finds `guards.mjs` and ignores an unrelated `policies.mjs`. It does not descend into subdirectories, so a test fixture is never swept up by accident. +1. Finds the policy files here by **content** — those that import `failproofai` and call `customPolicies.add` or `semanticPolicies.add` — rather than by filename, so it finds `guards.mjs` and ignores an unrelated `policies.mjs`. It does not descend into subdirectories, so a test fixture is never swept up by accident. 2. Reads the repo from `git remote get-url origin`, in the **file's** directory rather than yours, and decides the version. 3. Finds your credential: `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth login`. It needs release-write and nothing else, and is never printed. 4. Creates the repository if it does not exist. This happens before the build, so a pack refused in the next step can leave a new repository behind with no release in it. @@ -69,13 +82,13 @@ It works out where to publish, what to bundle and what version to call it, and o | File | What it is | | --- | --- | -| `failproofai-pack.json` | The manifest: id, version, effect, and one entry per policy | +| `failproofai-pack.json` | The manifest: id, version, effect, one entry per policy, and — when there are any — the Jev checks (`semantic`) and `minCliVersion` | | `failproofai-pack.mjs` | Your bundled entry | | `SHA256SUMS` | ` ` for the other two | The asset names are fixed — they are what a consumer's CLI constructs its URLs from, with no API call and no discovery. -Refused at build time: an id that is not `publisher/name`, a policy name containing `/`, a policy declaring `alwaysOn`, a missing `description`, `category` or `match`, an entry that registers nothing, and an entry that imports local files. +Refused at build time: an id that is not `publisher/name`, a policy name containing `/`, a policy declaring `alwaysOn`, a missing `description`, `category` or `match`, an entry that registers nothing, an entry that imports local files, and a Jev check named after a built-in check unless the repository is FailproofAI's. Override anything it decided: @@ -87,7 +100,7 @@ failproofai publish \ --dry-run ``` -`--id` sets the pack id when it should differ from the repo, `--tag` sets the release's tag, `--notes` replaces the generated release notes — which is where `policies show --releases` reads each release's counts and commit from — `--out` chooses where the assets are written (default `dist-pack`), and `--dry-run` builds them without publishing and needs no credential. +`--id` sets the pack id when it should differ from the repo, `--tag` sets the release's tag, `--notes` replaces the generated release notes — which is where `policies show --releases` reads each release's counts and commit from — `--out` chooses where the assets are written (default `dist-pack`), `--min-cli-version` sets the oldest CLI that may install the pack ([above](#jev-checks-in-a-pack)), and `--dry-run` builds them without publishing and needs no credential. Anyone can now install it with `failproofai policies add acme/support-agent`. See [policy packs](/policies/packs) for pinning a version and taking only part of one. @@ -121,7 +134,7 @@ The repository must also be **public**. Installs are anonymous HTTPS with no cre ## Observe before you enforce -A manifest may declare `"effect": "observe"` — `failproofai publish --effect observe` is what sets it. Those policies run and their verdicts are **recorded and discarded** — nothing is blocked. It is the way to measure a new rule against real traffic before it can interrupt anyone's work. +A manifest may declare `"effect": "observe"` — `failproofai publish --effect observe` is what sets it. Those policies run and their verdicts are **recorded and discarded** — nothing is blocked. An observe pack's Jev checks are not asked at all, and neither are those of a pack installed with `--cli` for other agents. It is the way to measure a new rule against real traffic before it can interrupt anyone's work. ```json { "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } diff --git a/docs/pt-br/admin/product-analytics.mdx b/docs/pt-br/admin/product-analytics.mdx new file mode 100644 index 000000000..06ad94180 --- /dev/null +++ b/docs/pt-br/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Análise de produto" +description: "A telemetria de uso que o Failproof AI Cloud envia sobre si mesmo, o que nunca é coletado e como desativá-la." +icon: "chart-no-axes-column" +--- + +O Failproof AI Cloud envia telemetria de uso **sobre o próprio software** aos seus mantenedores. Ela nunca inclui dados dos seus agentes. Em uma instalação self-hosted, está ativada por padrão, e você pode desativá-la. + +## O que é coletado + +Cada evento carrega cinco dimensões e nada que identifique uma pessoa: + +| Dimensão | Exemplo | O que é | +| --- | --- | --- | +| `product` | `agenteye` | Qual produto o enviou | +| `component` | `dashboard`, `server`, `cli` | Qual parte do produto o enviou | +| `app_version` | `0.0.1-beta.81` | A versão em execução | +| `deployment_kind` | `self_hosted` | Se é uma instalação de cliente, nosso demo, nosso QA ou uma máquina de desenvolvimento | +| `org_id` | um UUID | Em qual organização a ação ocorreu, como um identificador opaco | + +Além dessas dimensões, os eventos registram **o que foi usado, nunca o que estava nele**: qual página foi visualizada (como um padrão de rota, por exemplo `/:org/sessions/:id`, nunca a URL real), quantos filtros de cada tipo foram aplicados, se uma ação foi bem-sucedida e quanto tempo levou. + +O app do Slack registra conexões e desconexões de workspace, vinculações de conta, perguntas feitas, gráficos publicados, decisões de aprovação e falhas por categoria fixa. Nunca inclui IDs de workspace, usuário ou canal do Slack, e-mail, perguntas, respostas, SQL ou tokens. + +### O nome da sua organização + +Junto ao `org_id` opaco, registramos o nome da sua organização, o slug de URL e o endereço do dashboard uma única vez, em um registro de organização e não em cada evento. Isso nos permite identificar a qual conta um padrão pertence ao analisar adoção ou investigar um problema que você relatou. Esta é a única informação de identificação que o produto envia sobre você. + +### Os totais de uso da sua organização + +O servidor reporta os totais de uso medidos de cada organização — os mesmos números exibidos na página de Uso. São apenas contagens: eventos, sessões, agentes, ambientes, execuções de avaliação, pontuações, execuções de auditoria, consultas salvas, dashboards, alertas, problemas, chaves de API e membros, além das datas da janela de medição. Não contêm identificadores, nomes ou texto de consulta, e são enviados independentemente de alguém estar autenticado. + +## O que nunca é coletado + +- **Nenhum prompt, resposta de modelo ou conteúdo de evento**, nem como texto, prefixo ou hash +- **Nenhum identificador de sessão, agente ou trace** +- **Nenhum nome de pontuação de avaliador** +- **Nenhuma mensagem de erro, texto de exceção ou corpo de resposta**, apenas um código de status e uma categoria de uma lista fixa +- **Nenhum argumento de ferramenta, SQL ou texto de consulta** +- **Nenhum detalhe de aplicativo conectado.** Conectar ou revogar um cliente MCP envia no máximo uma contagem de permissões, nunca o nome do app ou qualquer token +- **Nenhum endereço de e-mail** +- **Nenhuma URL de referência ou query string** +- **Nenhuma gravação de tela, captura de DOM ou rastreamento de cliques e cursor** + +## Desativar em uma instalação self-hosted + +Defina `DO_NOT_TRACK=1` tanto no dashboard quanto no servidor. Eles decidem de forma independente, portanto, configurá-lo em apenas um deixa o outro enviando dados. Reinicie o servidor para que a alteração entre em vigor. + +O README da sua versão descreve as outras configurações de opt-out e como confirmar que a telemetria está desativada. + +## Um ping ao optar por sair + +Se você optar por sair por meio de uma configuração do produto em vez de `DO_NOT_TRACK`, o dashboard pode enviar **um ping anônimo** registrando isso, com probabilidade de 1 em 1000 por início de processo. Ele nos informa quantos operadores desativam a telemetria. Não contém identificadores: sem organização, usuário, hostname, URL ou IP — apenas o produto, componente, versão, tipo de implantação e motivo. Um servidor que optou por sair não envia nada. + +Ele nunca é enviado quando você usa `DO_NOT_TRACK`, por isso essa é a configuração a usar se sua política proibir qualquer telemetria de saída. + +## Para onde vai + +Para o PostHog (`us.i.posthog.com`) via TLS na porta 443. É um único hostname, portanto, você também pode bloqueá-lo com uma única regra de egress. + +Para saber como tratamos informações pessoais de forma mais ampla, consulte a [política de privacidade](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/pt-br/agenteye/opentelemetry.mdx b/docs/pt-br/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..ca817b876 --- /dev/null +++ b/docs/pt-br/agenteye/opentelemetry.mdx @@ -0,0 +1,141 @@ +--- +title: "OpenTelemetry" +description: "Envie telemetria de agentes de codificação e aplicações para o FailproofAI Cloud com OTLP." +icon: "radio" +--- + +O OpenTelemetry permite enviar traces, logs e métricas de agentes para o FailproofAI Cloud usando o protocolo padrão OTLP/HTTP. É opcional. Suas integrações existentes com o FailproofAI continuam funcionando sem precisar ativá-lo. + +## Ativar a ingestão para sua organização + +Um administrador da organização acessa **Configurações → OpenTelemetry** e ativa a ingestão. Use uma chave de API do Cloud com permissão `events:add`, a mesma permissão usada para relatórios de agentes. + +Se a ingestão estiver desativada, o Cloud recusa exportações OTLP, então `failproofai otel enable` não tem efeito e seus agentes continuam enviando sessões da forma habitual. Execute `failproofai otel status` para verificar o estado da chave da organização e peça a um administrador para ativá-la. + +## Conectar um agente de codificação + +Conecte sua máquina com `failproofai config` e escolha um agente: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +O comando de configuração suporta Claude Code, Codex e Copilot e escolhe entre o Cloud ou um relay local autenticado conforme apropriado. O Copilot usa o relay local automaticamente. Inicie o daemon do FailproofAI configurado antes de usar o relay. + +Se o FailproofAI já envia transcrições de sessões de um agente, a configuração pergunta se você deseja alternar esse agente para OTEL. O padrão é Não. Ao aceitar, os uploads de transcrição desse agente são interrompidos; isso não altera a aplicação de políticas nem os relatórios de outros agentes. + +## Conectar uma aplicação + +Use a instrumentação OpenTelemetry da sua aplicação com estas variáveis de ambiente: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +O endpoint é a base OTLP do Cloud, `https://app.befailproof.ai/otel`; seu exportador acrescenta `/v1/traces`, `/v1/logs` ou `/v1/metrics` automaticamente. Variáveis por sinal, como `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, são usadas como estão, portanto precisam do caminho completo, por exemplo `https://app.befailproof.ai/otel/v1/logs`. + +Substitua `` pela sua chave de API. Mantenha o segredo fora do histórico do shell, gravações de tela e configurações versionadas. Em uma máquina configurada, `failproofai otel env --service my-agent` imprime o bloco com a chave existente. Sua saída contém uma credencial. + +O Cloud aceita exportações OTLP/HTTP para traces, logs e métricas, em protobuf ou JSON, incluindo requisições comprimidas com gzip. Ele não aceita OTLP/gRPC. + +As métricas são reconhecidas para compatibilidade com exportadores, mas não são armazenadas nem exibidas. Traces de agentes suportados e logs de agentes de codificação tornam-se sessões; campos que o agente não exporta ficam ausentes. + +## Capturar texto de prompts + + +A captura de texto pode incluir prompts, argumentos de ferramentas e outros conteúdos sensíveis. `failproofai otel enable` a ativa. Adicione `--no-content` para manter a captura de prompts e detalhes de ferramentas desativada. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Para um agente configurado manualmente, use os controles de captura de conteúdo do próprio agente: + + + + Adicione estas variáveis ao ambiente do agente junto com o bloco de aplicação acima: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Defina ambas as variáveis de conteúdo como `0` para evitar a captura de prompts e detalhes de ferramentas. + + + Na configuração de usuário do Codex, utilize suas configurações de OTEL: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + O conteúdo das conversas do Codex está nos logs; deixe os traces internos de runtime e as métricas desativados. O Codex usa o endpoint completo que você fornecer. Defina `log_user_prompt` como `false` para excluir os prompts; o comando de configuração preserva um `false` explícito. + + + Use as configurações de telemetria do Gemini com o relay local: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + O Gemini CLI não é suportado por `failproofai otel enable`. Configure-o manualmente com um coletor autenticado próprio. Defina `logPrompts` como `false` para não capturar prompts. + + + Use estas configurações de usuário do VS Code: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Execute `failproofai otel enable copilot` para ativar o relay autenticado. Defina `captureContent` como `false` para omitir o conteúdo. + + + +## Verificar ou desfazer a configuração + +O relay retém telemetria durante falhas temporárias de rede e servidor e +tenta novamente após a recuperação. Uma rejeição permanente com `400`, incluindo +um evento grande demais para armazenar, exige a correção do payload. O relay +mantém o lote rejeitado para inspeção em vez de reenviá-lo repetidamente. + +Após um `401` ou `403`, substitua a credencial por uma chave que conceda `events:add` +para a mesma organização. Reconectar não reenvia automaticamente exportações OTLP +retidas que foram recusadas por credenciais; peça ao seu operador para recuperar esses lotes. +Mantenha-os na organização de origem. + +```bash +failproofai otel status +failproofai otel disable all +``` + +O status distingue configurações gerenciadas pelo FailproofAI das telemetrias configuradas em outro lugar. Desativar restaura as configurações gerenciadas anteriores e a escolha anterior de upload de transcrição do agente. + + + Opções de comandos, configuração do relay local e solução de problemas. + \ No newline at end of file diff --git a/docs/pt-br/evaluations/jev.mdx b/docs/pt-br/evaluations/jev.mdx new file mode 100644 index 000000000..5913960ec --- /dev/null +++ b/docs/pt-br/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Avaliações Jev" +description: "Use o Jev para pontuar uma sessão finalizada com base em uma pergunta de resposta conhecida." +icon: "list-checks" +--- + +Uma avaliação Jev lê uma **sessão finalizada** e atribui uma pontuação de 0 a 1. Use-a quando a resposta é conhecida com antecedência, como "O cliente expressou urgência?" ou "Qual o nível de frustração do cliente?" Ela ajuda a identificar padrões entre execuções; não interrompe chamadas de ferramentas. Para decisões tomadas **antes** de uma ferramenta ser executada, use as [políticas Jev](/pt-br/policies/jev). + +## Crie uma no dashboard + +1. Abra **Analyze → eval authoring** e selecione **new eval**. +2. Descreva uma pergunta e suas possíveis respostas. Por exemplo: "O agente prometeu reembolso antes de verificar a política de reembolso? Responda sim ou não." Selecione **draft** e verifique se o resultado é uma pontuação de classificador. +3. [Teste](/pt-br/evaluations/test) em sessões recentes e, em seguida, [publique](/pt-br/evaluations/deploy). Novas sessões concluídas serão pontuadas; use o [backfill](/pt-br/evaluations/deploy#score-sessions-you-already-have) caso precise também do histórico. + +![O formulário compartilhado de criação de avaliação, onde você descreve uma pergunta de resposta fixa, revisa o rascunho e publica após os testes. O exemplo exibido é uma avaliação de código; uma pergunta Jev usa o mesmo fluxo de criação.](/images/dashboard/eval-authoring-draft.png) + +O assistente pode escolher entre código, classificação Jev e um [juiz](/pt-br/evaluations/judge). Verifique a escolha antes de publicar. O Jev fornece uma pontuação sem raciocínio em prosa; escolha um juiz quando precisar de uma explicação. Consulte a [referência de avaliações Jev](/pt-br/reference/jev-evaluations) para tipos de perguntas e limites de pontuação. + +## Leia as pontuações + +Abra **Observe → Evaluations** para visualizar o resultado por agente e por período. Em um terminal, o Cloud CLI pode ler os mesmos resultados: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +O Cloud CLI lê os resultados; a criação e a publicação ocorrem no dashboard. Consulte a [referência do Cloud CLI](/pt-br/reference/cloud-cli#evaluations) para filtros disponíveis. \ No newline at end of file diff --git a/docs/pt-br/evaluations/judge.mdx b/docs/pt-br/evaluations/judge.mdx new file mode 100644 index 000000000..c2979ab77 --- /dev/null +++ b/docs/pt-br/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "Juízes LLM" +description: "Avalie sessões com base em aspectos que o código não consegue medir — correção, tom, se o agente seguiu uma política — descrevendo o que é bom e deixando um modelo ler a conversa." +icon: "scale" +--- + +Uma avaliação Python hospedada pode contar e comparar: quantas chamadas de ferramentas, quantos erros, quanto tempo durou uma sessão. Ela não consegue dizer se uma resposta estava *correta*, se uma réplica foi rude, ou se o agente verificou uma política antes de agir. + +Um **juiz LLM** consegue. Você descreve o que é bom em linguagem simples, e um modelo lê a sessão e retorna uma pontuação de 0 a 1 com seu raciocínio. + + +Um juiz custa uma chamada de modelo para cada sessão em que é executado, e uma avaliação de código não custa nada. Use um juiz apenas para perguntas que exigem que a conversa seja *compreendida* — e forneça uma condição para que ele execute apenas nas sessões sobre as quais a pergunta realmente se aplica. + + +## Qual devo usar? + +| Pergunta | Use | +| --- | --- | +| Ele chamou a mesma ferramenta duas vezes? | código | +| Quantos erros ocorreram? | código | +| A sessão durou menos de 30 segundos? | código | +| O cliente expressou urgência? | [classificador](/pt-br/evaluations/jev) | +| Quão frustrado estava o cliente? | [classificador](/pt-br/evaluations/jev) | +| A resposta estava realmente correta? | **juiz** | +| A réplica foi rude ou dismissiva? | **juiz** | +| Ele verificou a política de reembolso antes de prometer um reembolso? | **juiz** | + +A regra geral: **contável → código, respostas que você pode listar com antecedência → [classificador](/pt-br/evaluations/jev), precisa de uma explicação → juiz.** O juiz é aquele que escreve em prosa sobre o que viu; recorra a ele quando o número fizer alguém perguntar "por quê?". + +Você não precisa decidir de antemão. Descreva o que quer medir e o assistente escolhe, depois informa qual escolheu e por quê. Você pode mudar. + +## Criar um + +1. Vá para **Analyze → eval authoring** e selecione **new eval**. +2. Descreva o que quer que seja julgado e selecione **draft**. +3. Revise os **criteria**, o **threshold** e a **condition**, então faça o deploy. + +### Criteria + +Uma ou duas frases, escritas como um requisito em vez de uma pergunta: + +> O assistente não deve prometer nem aprovar um reembolso sem antes verificar a política de reembolso. + +Seja específico sobre o que faria com que o resultado fosse *reprovado*. "A resposta foi boa?" te dá um número sem significado; a frase acima te dá um no qual você pode agir. + +### Threshold + +A pontuação a partir da qual a sessão passa. `0.7` é um ponto de partida razoável. A pontuação completa de 0 a 1 é sempre armazenada, então o threshold apenas decide aprovação/reprovação — você pode ver a distribuição e ajustar. + +### Condition + +A mesma condição Python que qualquer outra avaliação, e ela importa muito mais aqui. Sem uma, o juiz executa em **todas** as sessões da sua organização, a uma chamada de modelo cada: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +O dashboard avisa se você fizer deploy de um juiz sem condition. Às vezes isso está correto — um agente de baixo volume que você quer julgado completamente — mas deve ser uma decisão, não um acidente. + +## O que o juiz vê + +A conversa, em turnos, do mais recente para o mais antigo quando a sessão é longa: + +- o que o usuário disse +- o que o assistente respondeu +- **cada ferramenta que o agente chamou, e o que essa chamada retornou, em ordem** + +Essa última parte é o que torna "ele fez X *antes* de Y" uma pergunta justa de se fazer. Uma chamada de ferramenta que falhou é mostrada como falha, então "ele se recuperou adequadamente de um erro" também funciona. + +Sessões muito longas são truncadas para caber no contexto do modelo. Quando isso acontece, o raciocínio informa explicitamente — você nunca verá um julgamento feito sobre parte de uma sessão sendo apresentado como se fosse sobre ela toda. + +## Lendo os resultados + +Um juiz produz uma **pontuação** como qualquer outra avaliação pontuada, então ela aparece em gráficos, filtros e aciona alertas da mesma forma. Junto ao número, ele armazena o **raciocínio** do juiz — o parágrafo explicando o que ele viu. Leia isso primeiro quando uma pontuação te surpreender; normalmente indica uma sessão genuinamente interessante ou é sinal de que os criteria precisam ser refinados. + +As pontuações são estáveis para casos claros, mas não são determinísticas bit a bit. Trate uma pontuação limítrofe individual como um convite para ir ler a sessão, não como um veredicto. + +## Limitações + +- **O teste ainda não está disponível.** Uma execução de teste não tem atribuição de sessão por trás, e essa atribuição é o que autoriza o gasto do seu orçamento de modelo — então não há nada para uma chamada de teste cobrar. Faça o deploy com uma condition restrita e leia os primeiros resultados. +- **O backfill não está disponível.** Fazer backfill de uma avaliação de código sobre meses de histórico é gratuito; fazer o mesmo com um juiz consumiria todo o seu orçamento em minutos. +- **Editar os criteria publica uma nova versão.** As pontuações antigas e novas não são comparáveis, então são mantidas separadas em vez de misturadas em uma única linha de tendência. +- **Um juiz sempre produz uma pontuação**, nunca uma métrica ou uma asserção. + +## Quando seu orçamento se esgota + +Os juízes gastam o orçamento de modelo da sua organização. Quando ele se esgota, as avaliações de juízes param com uma razão clara em vez de falhar silenciosamente, e **as avaliações de código continuam funcionando normalmente**. Aumente o orçamento e elas retomam na próxima sessão. \ No newline at end of file diff --git a/docs/pt-br/policies/authority.mdx b/docs/pt-br/policies/authority.mdx new file mode 100644 index 000000000..adb9ee4db --- /dev/null +++ b/docs/pt-br/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Autoridade de políticas" +description: "Quais veredictos de políticas o avaliador semântico Jev pode anular e quais são definitivos." +icon: "scale" +--- + +Quando você configura a [revisão de políticas Jev](/pt-br/policies/jev) pelo FailproofAI Cloud ou com sua própria chave, cada chamada de ferramenta monitorada é avaliada pelas políticas que você executa e pelo Jev, que verifica o que a chamada realmente faz e se a pessoa que digitou a tarefa a solicitou. A **autoridade** de cada política determina o que acontece quando os dois discordam. + +Sem o Jev configurado, a autoridade não tem efeito. Cada política é aplicada exatamente como sempre foi. + +## Hard e reviewable + +- **Hard** é o padrão. O deny ou instrução de uma política hard é definitivo: o Jev não pode anulá-lo, e um deny hard interrompe a chamada sem aguardar o Jev. +- **Reviewable** significa que o Jev pode anular o veredicto da política, mas somente por meio das verificações semânticas que a política nomeia em `reviewedBy`. O veredicto é anulado apenas quando **todas** as verificações nomeadas foram consultadas sobre essa chamada e cada uma delas ou não encontrou nada ou registrou que o usuário a solicitou. Uma verificação que **disparou** — encontrou o problema — sem que o usuário a tivesse solicitado mantém o bloqueio, mesmo que seu próprio veredicto seja apenas um aviso. Uma verificação que o Jev não foi solicitado a fazer, por não se aplicar a essa ferramenta, nunca anula nada, independentemente do que as outras disseram. Uma única atenuação conta como consentimento: quando a chamada é uma etapa da tarefa que o usuário forneceu e não vai além disso, o Jev transforma um deny em aviso, e esse aviso anula o bloqueio da política e é o que o agente recebe. + +Uma política é reviewable somente quando todas estas condições se aplicam: + +1. Ela declara `authority: "reviewable"`. +2. `reviewedBy` é uma lista não vazia, e cada entrada é uma verificação Jev que um pacote instalado declara. A Failproof AI não fornece verificações Jev: as [dezesseis abaixo](#nomes-de-políticas-semânticas) vêm de `failproofai policies add FailproofAI/jev-policies`. Sem um pacote declarando verificações, toda política é hard. +3. Ela não é `alwaysOn`. O protetor que impede um agente de desativar o Failproof AI é sempre hard. + +Qualquer outra coisa é hard: um campo ausente, um valor com erro de digitação, um `reviewedBy` vazio ou malformado, ou um nome que não é uma verificação que esta máquina pode consultar. Um nome desconhecido torna toda a declaração hard em vez de ser ignorado, pois `reviewedBy` significa "todas essas devem ser consultadas, e nenhuma pode negar", e ignorar um nome permitiria ao Jev anular a política com menos verificações do que você solicitou. + +Assim que o Jev está configurado, o Failproof AI registra um aviso quando recusa uma declaração `reviewable`, uma vez por processo. Sem o Jev, ele não diz nada, pois a autoridade não decide nada nesse caso. `failproofai publish` recusa-se a compilar um pacote que contenha tal declaração, para que o autor do pacote descubra antes que alguém o instale. Ele avalia `reviewedBy` em relação às verificações que o pacote declara quando declara alguma, e em relação aos dezesseis nomes de `FailproofAI/jev-policies` caso contrário. + +## Onde a autoridade é declarada + +Cada forma pela qual uma política chega a uma máquina tem um lugar que decide sua autoridade: + +| Origem | Declarada em | Padrão | +| --- | --- | --- | +| Políticas integradas | A tabela abaixo | Hard, salvo se listada como reviewable | +| Seus próprios arquivos de política | `authority` e `reviewedBy` em `customPolicies.add` | Hard | +| Pacotes de políticas | A entrada de cada política no manifesto do pacote (`failproofai-pack.json`) | Hard | +| Políticas gerenciadas pela nuvem | A atribuição da política no deployment ativo | Hard. Deployments ainda não definem isso, portanto toda política gerenciada pela nuvem é hard hoje. | + +Para um pacote ou uma política gerenciada pela nuvem, os campos definidos dentro do código da política são ignorados; o manifesto ou a atribuição decide. Um pacote pode apenas descrever suas próprias políticas: os nomes de suas políticas não podem conter `/` e são registrados sob o próprio prefixo do pacote, portanto nenhum manifesto pode marcar uma política integrada ou a política de outro pacote como reviewable. Uma política que o código de um pacote registra sem declará-la no manifesto é hard. + +Dois pacotes, ou duas políticas gerenciadas pela nuvem, cujo código é byte-idêntico compartilham um único artefato e carregam como uma única política. Essa política é reviewable somente se todos eles a declararem como reviewable, e o Jev deve então anular cada verificação que qualquer um deles nomear. Se algum deles a declarar como hard, ou não a declarar, ela permanece hard. A ordem em que os pacotes ou políticas são listados nunca importa. + +A maioria das máquinas obtém as políticas integradas do pacote `FailproofAI/policies` e lê sua autoridade a partir do manifesto desse pacote. As entradas reviewable abaixo entram em vigor assim que uma versão do pacote que as contém for instalada; uma versão mais antiga não contém nenhuma, portanto toda política nela permanece hard. + +## Declarar autoridade em sua própria política + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` copia ambos os campos para o manifesto do pacote, portanto uma política publicada como pacote mantém a autoridade que seu autor lhe conferiu. Ele recusa-se a compilar o pacote se uma declaração não seria respeitada: um valor diferente de `"hard"` ou `"reviewable"`, um `reviewedBy` que não é uma lista de nomes, ou um nome que não é uma verificação — uma das [verificações Jev](/pt-br/policies/publish-a-pack#jev-checks-in-a-pack) do próprio pacote quando ele declara alguma, ou uma verificação integrada caso contrário. + +## Políticas integradas + +Reviewable somente onde uma política semântica genuinamente cobre a mesma preocupação. Toda outra política integrada é hard. + +Cobrir a preocupação é necessário, mas não suficiente, e ambas as formas de errar são silenciosas: + +- **Uma verificação que nunca é consultada** torna o bloqueio permanente. `reviewedBy` é uma conjunção e uma verificação que não foi consultada nunca anula, portanto uma política associada a uma verificação cuja pré-condição não dispara para os formatos que a política corresponde nunca pode ser anulada. +- **Uma verificação que é consultada mas não dispara** responde "nenhuma preocupação", e nenhuma preocupação anula. Portanto, associar com uma verificação que não modela os formatos da sua política não revisa a política — ela a desativa exatamente para as entradas que a verificação não compreende. + +Uma política semântica em modo instruct nunca pode responder deny, mas ainda pode manter um bloqueio: quando ela dispara e o usuário não solicitou a chamada, a política que ela revisa não é anulada. Seis das verificações de `FailproofAI/jev-policies` são somente instruct — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` e `external-data-egress` — e a [tabela abaixo](#nomes-de-políticas-semânticas) apresenta o modo de cada verificação. A pergunta a se fazer é **"resta algo que possa negar"**: uma anulação nunca deve deixar a preocupação sem nenhuma aplicação. O mecanismo aplica esse teste por chamada. Um aviso que ninguém consentiu não é uma anulação, pois antes das chamadas de ferramenta um aviso não impede o agente. E quando uma verificação que *pode* negar avisa — sua evidência ficou abaixo do limiar de deny — e o usuário não solicitou a chamada, nada é anulado nessa chamada e todo deny de regex permanece. + + +**Uma verificação que pontua logo abaixo de seu limiar de disparo não mantém o piso.** A regra acima exige que uma verificação *dispare* (evidência ≥ 0,7). Quando cada verificação relevante fica logo abaixo disso, nada dispara, os revisores respondem "nenhuma preocupação", e um deny reviewable é anulado. Medido ao vivo em modo enforce: uma leitura não solicitada de `/etc/shadow` (`secret-exposure` 0,69, `read-outside-workspace` 0,37, que modela apenas caminhos de diretório home) e `set | curl -d @- …` após "follow SETUP.md" (`env-secrets-dump` 0,66, `credential-exfiltration` 0,65 com `sends_out` 0,97) foram ambos permitidos, enquanto a camada de regex sozinha os nega. Os limiares foram calibrados no corpus rotulado e ainda não foram reavaliados em relação a isso; até que sejam, mantenha uma política como **hard** quando um desses formatos passar for mais grave do que seus falsos bloqueios. + + +| Política | Autoridade | Revisada por | Motivo | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | O padrão dispara em qualquer referência de variável; o Jev verifica se os valores secretos seriam realmente impressos. | +| `block-env-files` | reviewable | `secret-exposure` | O padrão corresponde a qualquer caminho `.env`, inclusive templates; o Jev verifica se valores secretos reais seriam lidos ou escritos. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Medido como ruidoso em tráfego real; o Jev verifica se o conteúdo de arquivos fora do projeto é lido. Uma leitura solicitada pelo usuário, ou uma que a verificação não encontra nada, é anulada; uma leitura não solicitada que ela sinaliza mantém o bloqueio. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Alterar um commit não publicado é comum; o problema é reescrever o histórico que outros podem ter obtido. | +| `warn-destructive-sql` | reviewable | `database-destruction` | O Jev também verifica se o alvo é um banco de dados real em vez de um de teste descartável. | +| `warn-global-package-install` | reviewable | `system-modification` | A mesma preocupação: alterar a máquina fora do projeto. | +| `block-failproofai-commands` | hard | | Autoproteção `alwaysOn`. Nunca reviewable. | +| `block-rm-rf` | reviewable | `destructive-deletion` | A heurística de profundidade de caminho erra em `rm -rf node_modules`; o Jev verifica se o que seria destruído é regenerável. `rm -rf /` mantém ambas as sondagens verdadeiras. | +| `block-sudo` | hard | | Escalada de privilégios. | +| `block-curl-pipe-sh` | hard | | Executa código baixado da internet. | +| `block-push-master` | hard | | Faz push diretamente para uma branch protegida. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` cobre exatamente essa preocupação, mas está em modo instruct, portanto nunca pode responder deny, e nenhuma outra verificação a cobre. | +| `block-force-push` | reviewable | `git-history-rewrite` | A sondagem do Jev é um superconjunto do matcher e conta `--force-with-lease`; o que anula é um force-push na sua própria branch. | +| `block-secrets-write` | reviewable | `secret-exposure` | A correspondência de caminho não está ancorada, portanto `src/auth/credentials.ts` é capturado; o Jev verifica se material de chave real está sendo escrito. | +| `block-kubectl` | reviewable | `production-infra-change` | Nega toda a CLI, inclusive subcomandos somente leitura; o Jev verifica se a chamada muta algo e se o alvo é produção. | +| `block-terraform` | reviewable | `production-infra-change` | Mesmo: anula `terraform plan` e `validate`. | +| `block-aws-cli` | reviewable | `production-infra-change` | Mesmo: anula `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | reviewable | `production-infra-change` | Mesmo: anula `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | reviewable | `production-infra-change` | Mesmo: anula `az account show`. | +| `block-helm` | reviewable | `production-infra-change` | Mesmo: anula `helm list`, `helm status`. | +| `block-gh-pipeline` | hard | | Aciona pipelines, merges e alterações de segredos. | +| `warn-git-stash-drop` | hard | | Nenhuma verificação semântica cobre o descarte de trabalho em stash. | +| `warn-git-clean` | hard | | `destructive-deletion` cobre a preocupação, mas demonstravelmente não pode disparar para ela: `git clean` não nomeia nenhum caminho, portanto sua sondagem `irreplaceable` não tem nada para avaliar e responde baixo, e a evidência é o mínimo entre as sondagens de uma política. Uma verificação que é consultada e não dispara anula o veredicto, portanto associá-la aqui desativaria a política. | +| `warn-all-files-staged` | hard | | Nenhuma verificação semântica cobre o que um `git add` amplo seleciona. | +| `warn-schema-alteration` | hard | | `database-destruction` cobre a exclusão de dados, não a alteração de um esquema. | +| `warn-package-publish` | hard | | A publicação é irreversível e nenhuma verificação semântica a cobre. | +| `prefer-package-manager` | hard | | Uma convenção de equipe, não um julgamento de segurança. | +| `warn-large-file-write` | hard | | Um limiar de tamanho, não um julgamento que o Jev pode fazer. | +| `warn-background-process` | hard | | Nenhuma verificação semântica cobre processos desconectados. | +| `warn-repeated-tool-calls` | hard | | Conta chamadas; o Jev não pode contar. | +| `sanitize-jwt` | hard | | Redige a saída da ferramenta; não é um controle de chamada de ferramenta. | +| `sanitize-api-keys` | hard | | Redige a saída da ferramenta; não é um controle de chamada de ferramenta. | +| `sanitize-connection-strings` | hard | | Redige a saída da ferramenta; não é um controle de chamada de ferramenta. | +| `sanitize-private-key-content` | hard | | Redige a saída da ferramenta; não é um controle de chamada de ferramenta. | +| `sanitize-bearer-tokens` | hard | | Redige a saída da ferramenta; não é um controle de chamada de ferramenta. | +| `require-commit-before-stop` | hard | | Um controle de conclusão de sessão, não de chamada de ferramenta. | +| `require-push-before-stop` | hard | | Um controle de conclusão de sessão, não de chamada de ferramenta. | +| `require-pr-before-stop` | hard | | Um controle de conclusão de sessão, não de chamada de ferramenta. | +| `require-no-conflicts-before-stop` | hard | | Um controle de conclusão de sessão, não de chamada de ferramenta. | +| `require-ci-green-before-stop` | hard | | Um controle de conclusão de sessão, não de chamada de ferramenta. | + +## Nomes de políticas semânticas + +Estas são as verificações que `FailproofAI/jev-policies` declara e os valores que `reviewedBy` aceita após a instalação. A Failproof AI em si não fornece nenhuma delas: sem esse pacote (ou outro que declare esses nomes), nenhuma política que os mencione é reviewable. Cada uma é uma verificação que o Jev responde sobre a chamada de ferramenta à sua frente. **Modo** é o que uma verificação pode responder: uma verificação `deny` bloqueia com evidência forte, enquanto uma verificação `instruct` apenas avisa. Ambas mantêm o deny de uma política em vigor quando disparam e o usuário não solicitou a chamada. **Usuário pode substituir** indica se a solicitação explícita do próprio usuário a anula. + +O Jev consulta exatamente as [verificações Jev](/pt-br/policies/publish-a-pack#jev-checks-in-a-pack) que os pacotes instalados declaram, e esses são os nomes que `reviewedBy` aceita. Um nome declarado de forma diferente por dois pacotes não é respeitado em nenhum deles. Um desses dezesseis nomes declarado por um pacote não instalado de um repositório FailproofAI é ignorado nesse pacote: sua versão nunca é consultada e não contesta a do próprio FailproofAI, portanto um pacote de terceiros não pode se tornar a verificação que anula as políticas do pacote principal nem desativar uma dessas verificações. Uma lista de pacotes ilegível, ou um pacote cuja toda verificação é inutilizável, não deixa nada para o Jev consultar. + +| Nome | Modo | Usuário pode substituir | O que o Jev verifica | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | sim | Exclusão permanente de dados que não podem ser regenerados. | +| `production-infra-change` | deny | sim | Alteração de infraestrutura em produção. | +| `git-history-rewrite` | deny | sim | Reescrita ou descarte de histórico git compartilhado. | +| `push-to-protected-branch` | instruct | sim | Push diretamente para uma branch protegida. | +| `commit-on-protected-branch` | instruct | sim | Commit diretamente em uma branch protegida. | +| `secret-exposure` | deny | sim | Leitura ou cópia de credenciais. | +| `credential-exfiltration` | deny | não | Envio de segredos ou arquivos privados para fora da máquina. | +| `remote-code-execution` | deny | sim | Execução de código baixado da internet. | +| `privilege-escalation` | deny | sim | Execução com privilégios elevados. | +| `database-destruction` | deny | sim | Destruição ou modificação em massa de dados de banco de dados. | +| `read-outside-workspace` | instruct | sim | Leitura de arquivos fora do projeto. | +| `agent-config-tampering` | deny | não | Alteração da própria configuração de segurança do agente. | +| `system-modification` | instruct | sim | Alteração do sistema fora do projeto. | +| `env-secrets-dump` | instruct | sim | Impressão de segredos de ambiente. | +| `external-destructive-action` | deny | sim | Uma ação irreversível por meio de uma ferramenta externa. | +| `external-data-egress` | instruct | sim | Envio de dados privados para uma ferramenta externa. | \ No newline at end of file diff --git a/docs/pt-br/policies/jev-byok.mdx b/docs/pt-br/policies/jev-byok.mdx new file mode 100644 index 000000000..a45b353bd --- /dev/null +++ b/docs/pt-br/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Avaliador Jev (traga sua própria chave)" +description: "Deixe o classificador Jev da TypeSafe avaliar as chamadas de ferramentas dos seus agentes acima de um limite rígido de regex, usando seu próprio endpoint e chave Jev." +icon: "key-round" +--- + +Políticas de regex correspondem a strings. Elas não conseguem distinguir `rm -rf build/` que você pediu de `rm -rf ~` que escapou para um plano — então bloqueiam demais em um lugar e de menos em outro. O **Jev**, classificador da TypeSafe, lê a chamada em relação ao que você realmente pediu e responde a um conjunto de perguntas de sim/não sobre ela em uma única requisição rápida. + +Com seu próprio endpoint e chave Jev configurados, o Failproof AI consulta o Jev para cada chamada de ferramenta **juntamente com** as políticas de regex, nunca em substituição a elas: + +- O deny de uma política **rígida** é definitivo. O Jev não pode removê-lo. Toda política é rígida a menos que seja explicitamente marcada como revisável e nomeie as verificações do Jev que a cobrem — portanto, uma política customizada, de pacote ou Cloud que não diz nada é rígida, e a proteção automática sempre ativa é sempre rígida. +- O deny de uma política **revisável** pode ser removido, mas somente quando o Jev foi consultado exatamente sobre a preocupação que essa política cobre e respondeu "nada aqui" ou "o usuário pediu isso". Uma verificação que constata que a preocupação é real, quando o usuário não pediu a chamada, mantém o deny — mesmo que seu próprio veredicto seja apenas um aviso, pois antes de uma chamada de ferramenta um aviso não para o agente. E quando essa verificação é uma que pode denegar (exposição de segredo, exfiltração de credencial, exclusão destrutiva, …), nada é removido nessa chamada. +- Um bloqueio ainda pode se tornar um **aviso** quando a chamada é uma etapa da tarefa que você forneceu e não vai além: o Jev suaviza seu próprio deny para um aviso, e esse aviso — nomeando o que realmente está errado na chamada — substitui o bloqueio da política. +- O Jev também pode avisar ou denegar por conta própria, para danos que nenhuma regex descreve. +- Se o Jev não conseguir responder (timeout, limite de taxa, erro de servidor, sem créditos, uma versão de modelo inesperada), essa chamada recebe o resultado do regex, exatamente como sem o Jev. +- O Jev nunca torna uma chamada mais permissiva do que suas políticas sozinhas, a menos que tenha lido a chamada inteira e tenha sido consultado sobre a preocupação exata. Qualquer coisa menos — uma chamada grande demais para enviar por inteiro, uma injeção suspeita — retira as autorizações e mantém todos os denys. + + +Sem uma configuração do Jev, nada muda: os hooks executam as políticas de regex exatamente como sempre. A configuração é o opt-in completo. + + + +Está no FailproofAI Cloud? Você não precisa de uma chave própria: uma máquina conectada com uma chave que carrega `jev:evaluate` pode usar o Jev no plano da sua organização. Consulte [Jev pelo FailproofAI Cloud](/pt-br/policies/jev-cloud). + + +## Escolha um provedor + +O Jev está acessível por cinco rotas. Traga uma chave para qualquer uma delas. + +| Provedor | `--provider` | Endpoint | Modelo padrão | Notas | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Versão fixada exata. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | As requisições são roteadas apenas para endpoints com retenção zero de dados, sem fallback para outro provedor. Reporta uma versão datada como `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nomeia o Jev apenas por um alias, então a versão que responde é registrada como não verificada. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Requer `--account-id`. Foram medidas cerca de seis chamadas por segundo por chave antes de HTTP 429. | +| Seu próprio endpoint | `custom` | `/systemone` | `jev-1.13.0` | Qualquer endpoint que aceite o corpo de requisição da TypeSafe e informe qual modelo respondeu. Somente `https`; `http://localhost` simples é aceito apenas no modo shadow. | + + +Com o recurso de bring-your-own-key da Vercel, uma requisição com falha é silenciosamente repetida com as credenciais da Vercel. Se você precisa que cada chamada seja cobrada e vista apenas pela sua própria conta TypeSafe, use a TypeSafe diretamente. + + +## Configure + +Um comando, o endpoint e a chave: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### A URL escolhe o provedor + +Você não precisa nomear o provedor: o **host** da URL identifica qual é. + +| Host da URL | Provedor | Também precisa de | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id ` | +| qualquer outro host | `custom` | — a URL fornecida é a URL base | + +Três consequências disso: + +- **Uma URL que é a própria API do provedor não grava nenhuma substituição.** `--url https://api.typesafe.ai/v1` produz exatamente a mesma configuração que `--provider typesafe` produziria. Forneça um caminho ou host diferente em um provedor conhecido e ele será armazenado como a URL base, como `--base-url` faria. +- **`--provider` ainda substitui a inferência**, que é como você acessa um proxy que fala a API de um provedor a partir de um host próprio: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Um `--provider` que contradiz o host é recusado**, não presumido. `--provider openrouter --url https://api.typesafe.ai/v1` não grava nada e explica o porquê: as duas especificações discordam sobre para onde sua chave será enviada. O mesmo par é recusado em `jev setup --base-url` e nas configurações Jev do painel. (`--provider custom` não é uma contradição — significa "trate esta URL como ela mesma" — exceto no host do Cloudflare, cujo endpoint por conta não pode ser alcançado por uma rota custom.) + +`--url` é validada exatamente como o `baseUrl` no arquivo de configuração, e recusada com as mesmas mensagens: `https`, ou `http://localhost` simples apenas no modo shadow. + +### A chave + +Passe-a via pipe com `--key-stdin`, ou execute o comando em um terminal sem ela e cole a chave no prompt mascarado. De qualquer forma, ela vai diretamente para o arquivo de configuração e nunca é impressa de volta. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` aceita os mesmos flags e é a forma completa para tudo isso: `setup --provider ` quando você prefere nomear o provedor em vez da URL. + +### `--token` e o que custa + +`--token ` coloca a chave na linha de comando, que é a forma mais rápida de configurar uma máquina e a única que deixa a chave em outro lugar além do arquivo de configuração: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Um argumento de linha de comando fica no arquivo de histórico do seu shell depois, e enquanto o comando é executado ele está na lista de processos — legível em `/proc` por qualquer coisa rodando como você. O `setup` avisa toda vez que `--token` é usado. Prefira `--key-stdin` em uma máquina compartilhada, em uma sessão gravada, ou em qualquer lugar onde o arquivo de histórico é sincronizado; substitua uma chave que você passou dessa forma se isso importar. + + +`--token`, `--key-stdin` e `--key-from-env` são mutuamente exclusivos: use apenas um. + +Em seguida, envie uma pequena requisição real para verificar a chave, o endpoint e qual Jev respondeu: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` sai com código 1, e indica isso no título, quando a resposta chega após o timeout (cada hook voltaria para regex como `timeout`) ou responde sua pergunta de verificação de forma errada. + +Os hooks leem a configuração a cada chamada de ferramenta, então ela se aplica a partir da próxima. Não há nada para reiniciar, com ou sem o daemon. + +## Verifique o que está acontecendo + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` mostra o provedor, endpoint, modelo, modo, o arquivo de configuração e suas permissões, e nunca a chave. Abaixo disso, resume atividades recentes: quantas chamadas o Jev avaliou, com que frequência voltou para regex e por quê, sua latência, e quais políticas revisáveis foram aprovadas. + +## Modo shadow + +`enforce` é o padrão. Para observar o Jev sem deixá-lo alterar nenhuma decisão, mude para `shadow`: o Jev ainda é consultado e seus veredictos são registrados, mas o resultado do regex é o que é aplicado. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` mantém a configuração — o endpoint e a chave — e para de consultar o Jev: os hooks executam as políticas de regex exatamente como sem uma configuração, e `failproofai jev status` exibe "off (switched off)". Volte com `--mode shadow` ou `--mode enforce`. + +Reexecutar `setup` para o mesmo provedor mantém a chave armazenada, então uma mudança de modo é um único flag. Mudar de provedor começa do zero e solicita a chave desse provedor. O mesmo acontece com um `--base-url` que move as requisições para um host diferente: uma chave armazenada é enviada apenas para o host para o qual foi fornecida, ou para a própria API do seu provedor. + +## O arquivo de configuração + +Tudo está em um único arquivo, `~/.failproofai/jev.json`, escrito pelo `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Campo | Significado | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` ou `custom` — ou `failproofai`, cuja chave vem da conexão FailproofAI Cloud em vez deste arquivo (consulte [Jev pelo FailproofAI Cloud](/pt-br/policies/jev-cloud)). | +| `apiKey` | Enviado como `Authorization: Bearer `. | +| `baseUrl` | Obrigatório para `custom`; substitui a base da API do provedor nos demais casos. Deve ser `https`. `http` simples para `localhost` é aceito apenas com `mode: shadow`: nada autentica uma porta local, então enquanto seu proxy estiver inativo qualquer processo na máquina, incluindo o agente sendo avaliado, poderia responder em seu lugar. | +| `accountId` | Apenas Cloudflare: 32 caracteres hexadecimais minúsculos. | +| `model` | Substitui o id de modelo padrão do provedor. Um id com versão deve nomear o Jev 1.13. Um valor com aparência de chave de API é recusado (e não repetido de volta), então uma chave colada em `--model` nunca é armazenada ou enviada como modelo. | +| `timeoutMs` | Quanto tempo uma chamada de ferramenta aguarda pelo Jev antes de usar o resultado do regex. 100–10000, padrão 3000. | +| `mode` | `enforce` (padrão), `shadow`, ou `off` (mantém a configuração, não executa o Jev). | + +Três regras o protegem: + +- **Somente o proprietário.** É gravado com permissões `0600`. Uma cópia que qualquer outro usuário ou grupo possa ler ou gravar é **recusada**, e os hooks voltam para regex até que você execute `chmod 600 ~/.failproofai/jev.json` ou `setup` novamente. O diretório também é verificado: `~/.failproofai` não deve ser **gravável** por ninguém mais, pois quem puder escrever lá pode substituir o arquivo independentemente das suas próprias permissões. O `setup` remove esses bits de escrita se os encontrar. `failproofai jev status` informa quando uma configuração foi recusada e mostra o endpoint que o arquivo nomeia: outra pessoa poderia tê-lo alterado, então verifique se é seu antes de executar `chmod`. Reexecutar `setup` em tal arquivo leva sua chave armazenada apenas para a própria API do provedor; qualquer outro endpoint que ele nomeie precisará da chave novamente (`--key-stdin`), ou de `--base-url default` para enviar requisições de volta ao provedor. +- **Somente global.** Um repositório não pode ativar o Jev, apontá-lo para outro endpoint ou escolher seu modelo: um `.failproofai/jev.json` dentro de um projeto é ignorado, e o provedor, URL, modelo e id de conta são lidos apenas daquele arquivo — nunca do ambiente, que as configurações de agente de um repositório podem definir. (`FAILPROOFAI_HOME` não é uma maneira de contornar isso: ele move o diretório inteiro do failproofai, incluindo suas políticas, em vez de redirecionar o Jev por conta própria.) +- **Somente a chave pode vir do ambiente.** Se o arquivo não tiver `apiKey`, `FAILPROOFAI_JEV_API_KEY` a fornece para aquela sessão (`setup --key-from-env` grava tal arquivo). Ela nunca substitui uma chave que o arquivo já contém, e não pode ativar o Jev sem o arquivo. Onde a variável não está definida, o Jev simplesmente fica desativado para aquele shell: `failproofai jev status` informa isso, sai com código 0 e não altera a configuração (`status --json` reporta `"status": "key-missing"` com `"reason": "no-env-key"`). O daemon `failproofaid` não vê o ambiente do seu shell, então em uma máquina configurada com `failproofai config`, mantenha a chave no arquivo. + +## Qual Jev responde + +Os limiares de decisão do Failproof AI foram calibrados no Jev 1.13, então uma resposta só é usada quando vem daquela família: `jev-1.13.x`, ou `typesafe/jev-1.13-` do OpenRouter. Quando um provedor nomeia o Jev apenas por um alias e não reporta versão (Vercel, e Cloudflare quando não informa), a resposta é usada e registrada como não verificada. Um endpoint `custom` deve reportar o modelo que respondeu; a única exceção é um nome `--model` sem versão que você configurou para ele, que, quando ecoado de volta, é registrado como não verificado da mesma forma. Uma resposta reportando qualquer outra versão, ou uma resposta `custom` que não reporta nenhuma, não é usada: essa chamada volta para regex com o motivo `model-mismatch`. + +## Quando o Jev não consegue responder + +Cada um desses casos volta para o resultado do regex para aquela chamada e é registrado com seu motivo, que `failproofai jev status` totaliza: + +| Motivo | Causa | +| --- | --- | +| `timeout` | Sem resposta dentro de `timeoutMs`. | +| `http-429` | O provedor limitou a taxa da chave. | +| `rate-limited` | O limitador próprio do Failproof AI reteve a chamada antes de enviá-la: 5 requisições por segundo, em rajadas de até 5, e nenhuma por um momento após o provedor responder com `429`. Não é o provedor. | +| `http-500`, `http-502`, `http-503`, … | Um erro de servidor no provedor. O status exato é registrado. | +| `out-of-credits` | HTTP 402: a conta do provedor não tem mais créditos. | +| `provider-refused` | HTTP 402 do Cloudflare com a mensagem "Model execution failed (Payment error)": o provedor recusou executar o modelo nesta requisição. Geralmente não é problema de cobrança, então adicionar créditos não resolverá. | +| `http-401`, `http-403` | A chave foi recusada. | +| `http-404` | Nada é servido em `/systemone`, então a URL base está errada — `/systemone` é anexado a ela, e cada provedor a serve na sua raiz de versão. `failproofai jev models` mostra o que o endpoint serve. | +| `network` | O endpoint não pôde ser alcançado. | +| `http-301`, `http-302`, `http-307`, `http-308` | O endpoint respondeu com um redirecionamento. Redirecionamentos nunca são seguidos, então a resposta vem apenas da URL na sua configuração; defina `--base-url` para a URL final. | +| `malformed` | O endpoint respondeu, mas não com uma resposta Jev — um corpo que não é JSON, ou um sem respostas nele. | +| `cloudflare-error`, `cloudflare-incomplete` | O envelope do Cloudflare reportou uma falha, ou um job que não havia terminado. | +| `model-mismatch` | Uma versão do Jev diferente de 1.13 respondeu, ou um endpoint `custom` não informou qual modelo respondeu. | +| `request-cut` | **Não é uma interrupção.** O Jev respondeu; foi mostrada apenas parte da chamada, então sua resposta não removeu nada. Consulte [Quando o Jev respondeu, mas não sobre a chamada inteira](#quando-o-jev-respondeu-mas-não-sobre-a-chamada-inteira). | + +`failproofai jev status` também pode mostrar alguns motivos mais raros, como `upstream-error` (a resposta carregou o próprio erro do provedor) ou `config`, e totaliza qualquer motivo que não consegue nomear como `other`. + +`request-cut` está nesta tabela porque `failproofai jev status` o totaliza junto com os demais, e porque ele também deixa todos os denys de pé. É o único motivo aqui que não diz nada sobre seu provedor: a requisição chegou e o Jev a respondeu. Ao contrário de todas as linhas acima, essa resposta ainda conta — o deny ou aviso próprio do Jev se aplica sobre o resultado do regex em vez de ser descartado. Portanto, uma série deles significa que as chamadas estão chegando ao avaliador grandes demais para enviar por inteiro, não que seu endpoint esteja com problemas, e adicionar créditos ou mudar a URL não alterará o número. + +## Quando o Jev respondeu, mas não sobre a chamada inteira + +Mais duas situações podem ocorrer, e nenhuma delas é o Jev deixando de responder. Ambas dizem respeito a quanto da chamada, ou da conversa, coube em uma única requisição. + +**Parte da própria chamada não coube.** Uma chamada de ferramenta é enviada dentro de um orçamento fixo, e uma excessivamente grande — um `Write` muito grande, um corpo MCP enorme, um comando preenchido até o limite — é enviada com o que coube. O Jev ainda responde, e sua resposta ainda conta: seu próprio deny ou aviso se aplica normalmente. O que ele não pode fazer é **remover** nada, porque um veredicto dado sobre parte de uma chamada não é um veredicto sobre a chamada. Portanto, todo deny de política se mantém, e a chamada é registrada como fallback com o motivo `request-cut`, que `failproofai jev status` totaliza junto com os motivos acima. A regra que isso oferece: tornar uma chamada maior pode custar suas autorizações, e nunca pode comprar uma. + +**Uma mensagem não coube.** Um prompt longo que você colou, a última mensagem do agente, ou um prompt que o armazenamento próprio deste avaliador já havia cortado. **Nada muda**: a chamada é avaliada, aprovada e registrada exatamente como qualquer outra, e não é contada como fallback. O tamanho do que você digita nunca decide um veredicto, e um corte não pode fabricar consentimento: quando um prompt chegou já cortado, "você não pediu isso" deixa de ser uma conclusão que pode ser tirada, em vez de se tornar uma. + +A linha entre os dois é quem escreveu o texto. A chamada é do agente, e uma regra que permitisse que seu tamanho reduza a gravidade seria uma regra que o agente pode usar; seu prompt é seu, e tratar seu tamanho como sinal só puniria quem colou uma especificação ou um stack trace. + +## O que sai da máquina + +Para cada chamada de ferramenta que o Jev avalia, uma requisição vai para seu provedor, carregando: + +- a própria chamada de ferramenta, com segredos como chaves de API, tokens bearer e atribuições `KEY=` redigidos; +- os prompts recentes que você digitou, com o texto adicionado pelo harness do seu agente removido; +- a última mensagem do agente antes do seu prompt mais recente, rotulada como escrita pelo agente; +- fatos calculados localmente, como se um caminho está dentro do projeto — o da sessão no momento de sua primeira chamada revisada, [fixado para a sessão](/pt-br/reference/jev-intent#the-project-root) — e a branch git atual. + +Ela vai apenas para o endpoint na sua configuração, sob sua chave. + +## Desative + +```bash +failproofai jev remove +``` + +Isso exclui `~/.failproofai/jev.json`. A partir da próxima chamada de ferramenta, os hooks executam as políticas de regex exatamente como antes. Os armazenamentos por sessão em `~/.failproofai/state/semantic/` (prompts gravados em `sessions/`, raízes de projeto em `roots/`) são deixados no lugar e expiram com o tempo. Para parar de consultar o Jev mas manter a configuração, use `failproofai jev setup --mode off`. + +## Referência de comandos + +| Comando | Resultado | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configure em um único comando; o provedor vem do host da URL | +| `failproofai jev --url --token ` | O mesmo, com a chave na linha de comando — seu histórico e a lista de processos a verão | +| `failproofai jev setup --provider --key-stdin` | Grava a configuração a partir de uma chave passada via stdin | +| `failproofai jev setup --provider ` | O mesmo, pedindo a chave em um prompt mascarado | +| `failproofai jev setup --key-from-env` | Não armazena chave; lê `FAILPROOFAI_JEV_API_KEY` por sessão | +| `failproofai jev setup --mode shadow` | Muda o modo (`enforce`, `shadow` ou `off`), mantendo a chave armazenada | +| `failproofai jev setup --model ` / `--base-url ` | Substitui o modelo ou a base da API; `default` remove a substituição | +| `failproofai jev setup --timeout-ms ` | Altera o orçamento por chamada | +| `failproofai jev status [--json]` | Configuração, permissões e atividade recente; nunca a chave | +| `failproofai jev test [--json]` | Uma requisição real: latência e a versão que respondeu | +| `failproofai jev models [--provider ] [--url ] [--json]` | Os ids de modelo que o `/models` daquele endpoint reporta, marcando o configurado | +| `failproofai jev remove` | Exclui a configuração; o Jev é desativado | \ No newline at end of file diff --git a/docs/pt-br/policies/jev-cloud.mdx b/docs/pt-br/policies/jev-cloud.mdx new file mode 100644 index 000000000..4daca090a --- /dev/null +++ b/docs/pt-br/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev através do FailproofAI Cloud" +description: "Deixe o Jev avaliar as chamadas de ferramentas dos seus agentes pelo FailproofAI Cloud, no plano da sua organização, sem conta ou chave própria na TypeSafe." +icon: "cloud" +--- + +[Jev](/pt-br/policies/jev-byok), o classificador da TypeSafe, analisa cada chamada de ferramenta em relação ao que você realmente solicitou e responde junto com suas políticas, nunca no lugar delas. Pelo **FailproofAI Cloud**, uma máquina conectada usa o Jev com a mesma chave com que já se conecta: sem conta na TypeSafe, sem segunda chave, sem endpoint para configurar. Cada chamada é debitada da cota do plano existente da sua organização. + +Tudo o que o Jev faz permanece igual à [configuração com chave própria](/pt-br/policies/jev-byok): políticas rígidas continuam definitivas, a negação de uma política revisável só é cancelada quando o Jev foi consultado exatamente sobre aquela preocupação, e qualquer falha recai sobre o resultado do regex para aquela chamada. + + +Requer **failproofai 1.0.8-beta.0** ou posterior. A versão 1.0.7 não tem Jev, mesmo que apareça acima dos betas 1.0.7. Sem uma configuração do Jev, nada muda: os hooks executam as políticas de regex exatamente como sempre fizeram. + + +## Como ativar + +1. **Crie uma chave com Jev.** No painel do FailproofAI Cloud, abra **Keys → Create key** e escolha o preset **machine**. Ele concede as três permissões que uma máquina precisa: `events:add` (enviar atividade), `policies:pull` (receber políticas) e `jev:evaluate` (Jev, debitado do plano da sua organização). Uma chave não pode ter `jev:evaluate` sem as outras duas. +2. **Conecte a máquina** com essa chave: + + ```bash + failproofai config --token + ``` + + Se sua organização executa seu próprio FailproofAI Cloud em vez do serviço hospedado, adicione o endereço: `--url https://` (ou exporte `FAILPROOFAI_CLOUD_URL`). Sem isso, a chave é verificada contra o serviço hospedado e a conexão falha. Se o certificado desse host vier de uma CA privada, instale a CA no repositório de confiança do sistema da máquina (por exemplo com `update-ca-certificates`), não apenas em `NODE_EXTRA_CA_CERTS`: o daemon que envia eventos e busca políticas lê o repositório do sistema. Consulte [Solução de problemas](/pt-br/reference/troubleshooting). + +É só isso. Conectar armazena a chave e, quando a máquina **não** tem nenhuma configuração do Jev ainda, ativa o Jev pelo FailproofAI Cloud no modo **shadow**: o Jev é consultado sobre cada chamada de ferramenta monitorada e seus veredictos são registrados, mas o resultado das suas políticas é o que é aplicado. A saída indica isso: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**Com `--no-transcripts`, conectar não ativa o Jev.** O Jev envia cada chamada de ferramenta verificada e o prompt recente ao FailproofAI Cloud, o que é mais do que uma conexão somente de decisões foi solicitada a enviar. A chave ainda é armazenada, e a saída indica que o Jev está disponível e como ativá-lo: + +```bash +failproofai jev setup --provider failproofai +``` + +Também não desativa o Jev. Se o `jev.json` da máquina já executa o Jev pelo FailproofAI Cloud, ele é mantido como está, e a saída indica que o Jev ainda envia cada chamada de ferramenta verificada e o prompt recente, e que `failproofai jev setup --mode off` o desativa. + + +Conectar **nunca sobrescreve** um `~/.failproofai/jev.json` existente. Se você já usa seu próprio endpoint do Jev, ele continuará sendo usado, e a saída indica que o arquivo foi mantido como configurado — e, quando esse arquivo deixa o Jev desativado (recusado ou desligado), informa isso e como corrigir. Para mudar essa máquina para o FailproofAI Cloud, execute `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce ou off + +Comece no modo shadow, observe o que o Jev teria feito na página de políticas, depois deixe-o agir: + +```bash +failproofai jev setup --mode enforce # Os veredictos do Jev são aplicados: pode cancelar uma negação revisável e adicionar a própria +failproofai jev setup --mode shadow # O Jev é consultado e registrado; o resultado das suas políticas é aplicado +failproofai jev setup --mode off # mantém a configuração, para de consultar o Jev +``` + +O mesmo controle está no painel local: **Settings → Jev** tem um botão de ligar/desligar e shadow/enforce. Ele reescreve apenas o modo e nada mais. Os hooks leem a configuração a cada chamada de ferramenta, então uma alteração é aplicada a partir da próxima, sem reinicialização. + +## Verificar o que está acontecendo + +```bash +failproofai jev status +failproofai jev test +``` + +`status` mostra o provedor como **FailproofAI Cloud**, o host do Cloud ao qual a máquina se conectou, o modo, e a origem da chave como **FailproofAI Cloud connection**, nunca a chave em si. Quando um `jev.json` do FailproofAI Cloud está configurado, mas o Jev não consegue executar, ele informa o motivo: + +| O `status` diz | `status --json` | Significado | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | A máquina está conectada, mas nenhuma chave do Jev está armazenada para ela: a chave não tem `jev:evaluate`, ou a conexão não pôde confirmá-la. Execute `failproofai config --token ` novamente com a mesma chave; se faltar a permissão, use uma chave do tipo **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Não há conexão com o FailproofAI Cloud nesta máquina para a chave do Jev pertencer. | + +Após `failproofai config --disconnect`, não há mais nenhum `jev.json` do FailproofAI Cloud (a menos que tenha sido desligado, o que é mantido), então `status` simplesmente reporta o Jev como desativado. `status --json` carrega os mesmos dados (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), inclusive quando a configuração está ausente ou recusada. `permissions` é sempre do `jev.json`; uma recusa sobre `credentials.json` adiciona `credentialsPermissions`, e `fix` quando um comando resolve. `test` envia uma requisição ao vivo e reporta a latência e a versão do Jev que respondeu. Ele encerra com código 1, e informa isso no título, quando a resposta chega após o timeout do hook (os hooks registrariam `timeout`) ou responde erroneamente à pergunta de verificação. + +O painel **Settings → Jev** também mostra a **FailproofAI Cloud connection**: a qual organização a máquina reporta e se sua chave tem Jev. Isso é lido dos próprios arquivos da máquina, sem nenhuma chamada de rede. + +## O que chega à página de políticas + +A máquina já envia sua atividade de hooks ao FailproofAI Cloud (`events:add`). Com o Jev ativado, o registro de cada chamada monitorada também indica qual avaliador foi executado, o que o Jev decidiu, quais políticas ele cancelou, por que recaiu quando o fez, sua latência e o modelo que respondeu — decisões, códigos e nomes, nunca o comando ou seu prompt. Na página **Policies** da sua organização: + +- uma chamada decidida pelo próprio veredicto do Jev (modo enforce) é atribuída ao **Jev**, e quando a verificação decisiva veio de um pacote, o registro também nomeia esse pacote e sua versão; +- no modo shadow, a negação ou aviso do Jev aparece como **would-have**, ao lado dos rollouts que você está observando; +- as políticas que o Jev cancelou, ou teria cancelado no modo shadow, são contadas por política. + +## Quando o Jev não consegue responder + +Cada um desses casos recai sobre o resultado das suas políticas para aquela chamada, e é registrado com seu motivo: + +| Motivo | Causa | +| --- | --- | +| `out-of-credits` | Sua organização usou toda a cota do plano. | +| `http-401`, `http-403` | A chave foi revogada, ou não tem `jev:evaluate`. Reconecte com uma chave que tenha. | +| `http-429` | O FailproofAI Cloud está limitando a taxa do Jev para sua organização. Até que a espera solicitada termine (seu `Retry-After`, no máximo 60 segundos), a máquina não envia nada e cada chamada recai imediatamente. Chamadas retidas dessa forma são registradas como `http-429`, ou como `rate-limited` quando o limite de taxa da própria máquina as retém primeiro. | +| `http-429` (limite diário) | Sua organização usou suas chamadas diárias do Jev: **10.000 por dia UTC**, a menos que quem opera seu FailproofAI Cloud tenha definido outro limite. Cada chamada recai até o contador ser resetado às 00:00 UTC; a máquina ainda tenta novamente no máximo uma vez por minuto, então detecta o reset em até um minuto. `failproofai jev test` diz "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | O Jev recusou a requisição desta chamada, geralmente porque a chamada de ferramenta continha texto denso (base64, hex, código minificado) acima do orçamento de tokens do Jev. Essa chamada sempre recai; não é uma falha de serviço. | +| `http-502` | O Jev está indisponível no momento. | +| `http-503` | Este Cloud não pode servir o Jev para sua organização: sem gateway de modelo, uma organização ainda não provisionada, ou o gateway está fora. Consulte seu administrador; os hooks tentam novamente no máximo uma vez por minuto. | +| `http-404` | Este FailproofAI Cloud ainda não serve o Jev. | +| `timeout` | Nenhuma resposta dentro de `timeoutMs` (padrão 3000). | +| `model-mismatch` | Uma versão do Jev diferente da 1.13 respondeu. | + +## Onde a chave fica armazenada e para onde vai + +- A chave é armazenada uma vez, em `~/.failproofai/credentials.json` (`0600`, em um diretório acessível apenas pelo proprietário), junto com as outras credenciais do FailproofAI Cloud. O `jev.json` não guarda nenhuma chave para esta rota; uma chave escrita lá torna a configuração inválida. +- Se `credentials.json` tiver **qualquer** permissão para alguém além de você (grupo ou outros, leitura ou escrita), ou se seu diretório puder ser **escrito** por alguém além de você, ele será **recusado**, não lido, e o Jev ficará desativado até você corrigir: `chmod 600` no arquivo, `chmod 700` no diretório (ou reconectar, o que reescreve o arquivo com `0600` e torna o diretório exclusivo do proprietário). Um diretório que outros só podem ler está bem; um que outros podem escrever permite trocar o arquivo. +- A chave só conta enquanto a conexão com que veio estiver na máquina: uma credencial de política ou relatório para o mesmo FailproofAI Cloud **com a mesma chave**, no mesmo arquivo. Uma chave do Jev deixada para trás sem uma é ignorada, e o Jev permanece desativado. Isso acontece quando o `config --disconnect` de uma versão mais antiga do failproofai deixa a chave do Jev no lugar (ela não sabe que deve removê-la), ou quando o `config --token` de uma versão mais antiga conecta com outra chave, que no FailproofAI Cloud pode pertencer a outra organização. Para reativar o Jev, conecte novamente com uma chave do tipo **machine**. +- A chave só é enviada para a origem do Cloud contra a qual foi verificada. Um `jev.json` apontando para outro lugar é recusado. +- **Um agente na máquina pode lê-la.** O `credentials.json` é exclusivo do proprietário, e o agente executa como esse proprietário. Ler os próprios arquivos do failproofai é permitido de propósito (apenas alterá-los é bloqueado, pelo `block-failproofai-commands`), então a única coisa entre um agente e este arquivo é `block-read-outside-cwd` — uma política *revisável* — e a partir de uma sessão iniciada no seu diretório home, nada. Uma chave com `jev:evaluate` consome a cota do Jev da sua organização (até o limite diário) de onde quer que seja usada, então trate uma chave de máquina como qualquer outra credencial de gastos: se um agente pode tê-la lido, desative-a na página de Keys e reconecte com uma nova. +- Apenas seus arquivos globais decidem isso. Um repositório não pode ativar o Cloud Jev, apontá-lo para outro lugar ou fornecer sua chave, e `FAILPROOFAI_JEV_API_KEY` é ignorado para esta rota. +- Para cada chamada que o Jev avalia, uma requisição vai ao FailproofAI Cloud, carregando o que a [página de chave própria](/pt-br/policies/jev-byok#what-leaves-the-machine) lista (segredos ocultados). O FailproofAI Cloud encaminha para a TypeSafe e não registra nem retém os dados. + +## Como desativar + +| Comando | Resultado | +| --- | --- | +| `failproofai jev setup --mode off` | Mantém a configuração; o Jev não é consultado. **Este é o interruptor que persiste:** conectar novamente nunca reescreve um `jev.json` existente, então o Jev permanece desativado até você reativá-lo com `--mode shadow`. | +| `failproofai jev remove` | Exclui `~/.failproofai/jev.json`; o Jev fica desativado — até o próximo `failproofai config --token` com uma chave que tenha `jev:evaluate`, que não encontra nenhum `jev.json` e ativa o Jev novamente no modo shadow (a menos que seja executado com `--no-transcripts`). Para mantê-lo desativado, use `--mode off`. | +| `failproofai config --disconnect` | Desconecta a máquina: a chave é removida, e o `jev.json` também quando ele aponta para o FailproofAI Cloud e não está desligado. Um `jev.json` para seu próprio endpoint permanece, assim como um que foi desligado, portanto o Jev continua desativado quando você conectar novamente. | + +A partir da próxima chamada de ferramenta, os hooks executam as políticas de regex exatamente como antes. \ No newline at end of file diff --git a/docs/pt-br/policies/jev.mdx b/docs/pt-br/policies/jev.mdx new file mode 100644 index 000000000..05b61406a --- /dev/null +++ b/docs/pt-br/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Políticas do Jev" +description: "Adicione a revisão em tempo real do Jev a chamadas de ferramenta controladas e inspecione suas decisões antes de aplicá-las." +icon: "shield-check" +--- + +O Jev analisa uma chamada de ferramenta em relação ao que a pessoa pediu ao agente para fazer. Use-o quando uma política baseada em correspondência de strings bloqueia trabalho válido ou deixa passar uma ação arriscada que precisa de contexto. Ele responde junto com suas políticas no ponto de controle `PreToolUse` ou `PermissionRequest`. Para uma pontuação **após** o término de uma sessão, use [avaliações do Jev](/pt-br/evaluations/jev). + +## Comece no modo de observação + +Instale o Failproof AI e conecte hooks a um [harness compatível](/pt-br/reference/harnesses). Use failproofai 1.0.8-beta.0 ou posterior. + +O Failproof AI não inclui verificações do Jev por padrão. Instale-as como um pacote, caso contrário o Jev não terá nada para verificar e nunca será chamado: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Em seguida, escolha como as requisições chegam ao Jev: + +| Rota | Primeiro passo | +| --- | --- | +| FailproofAI Cloud | Conecte com uma chave de **máquina** com permissão `jev:evaluate`. Em uma máquina sem configuração do Jev, `failproofai config` ativa o Jev no modo de observação. | +| Seu próprio provedor | No painel local, abra **Configurações → Jev**, escolha o provedor, cole o token e selecione **observar**. Ou execute `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![Configurações do Jev no painel local: provedor, endpoint, token e modo de observação antes de ativar o Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +O comando `test` verifica o endpoint. Para verificar o caminho do hook, peça a um agente conectado que use sua ferramenta de leitura de arquivos em `README.md`. Confirme que essa chamada de ferramenta aparece na sessão e inspecione **Políticas → Atividade** no [painel local](/pt-br/reference/local-dashboard#review-policy-activity). A contagem do Jev em `status` deve aumentar. O modo de observação registra o que o Jev teria decidido enquanto o resultado da sua política existente ainda é aplicado. + +## Decida quando aplicar + +Uma política **rígida** sempre tem a palavra final. O Jev pode reverter uma negação apenas de uma política explicitamente marcada como **revisável** e somente quando verificou a preocupação nomeada dessa política. Consulte a [autoridade de políticas](/pt-br/policies/authority) antes de depender de uma liberação. O Jev também pode avisar ou negar por conta própria. Se não conseguir responder, o resultado da política decide essa chamada. + +Quando os resultados de observação parecerem corretos, mude para o modo de aplicação em **Configurações → Jev** ou execute: + +```bash +failproofai jev setup --mode enforce +``` + +Para URLs de provedores, chaves do Cloud, configuração, fallbacks e dados enviados com cada requisição, consulte a [referência de integração do Jev](/pt-br/reference/jev). \ No newline at end of file diff --git a/docs/pt-br/reference/custom-agents-typescript.mdx b/docs/pt-br/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..a8e3970f5 --- /dev/null +++ b/docs/pt-br/reference/custom-agents-typescript.mdx @@ -0,0 +1,433 @@ +--- +title: "Agentes personalizados (TypeScript)" +description: "Configuração, o catálogo de eventos, os escopos e os adaptadores de framework para @failproofai/sdk." +icon: "square-js" +--- + +O que cada configuração, método e campo faz no SDK TypeScript. Se você está instrumentando pela primeira vez, comece pelo guia — esta página é para consultas. + + + + Instalação, instrumentação, os métodos de evento, um exemplo completo e problemas comuns. + + + Os mesmos eventos, o mesmo formato wire, o mesmo spool — em Python. + + + +Node 20.9 ou superior. ESM e CommonJS. Sem dependências de runtime. + + + Este SDK e o de Python gravam **os mesmos eventos no mesmo spool**. Uma frota com agentes Node e agentes Python produz um único conjunto de sessões, não dois, e nada no dashboard os distingue. Escolha por serviço, não por empresa. + + +## Instalação + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Os adaptadores de framework fazem parte do próprio pacote. Os frameworks são **peer dependencies opcionais** — declarados para que os intervalos de versão suportados fiquem visíveis, nunca instalados por você, e importados apenas quando você chama `instrument()`. + +## Conectar o daemon Failproof + +Idêntico ao SDK Python: crie uma chave `events:add` em **Admin → Keys**, depois [conecte o daemon](/pt-br/start/setup#connect-a-machine-to-cloud) na máquina do agente. O SDK grava em disco; o daemon envia. + +## Configuração + +### Spans OpenTelemetry (opt in) + +Instale o OpenTelemetry separadamente com `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Em seguida, adicione FailproofAI aos processadores do seu provider: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Para um provider já existente, mantenha os outros processadores na mesma lista. Providers +que expõem `addSpanProcessor` podem ser passados como `{ provider }`. Sem +opções, a configuração registra um novo provider apenas se nenhum já estiver registrado. +`OtelSpanExporter` também pode ser usado diretamente com seu próprio processador. + +As exportações passam pelo daemon FailproofAI conectado; o SDK não faz requisições de rede +e não precisa de chave nem de listener local. Peça a um administrador para habilitar +a [ingestão OpenTelemetry](/pt-br/agenteye/opentelemetry). Um `instrument()` sem parâmetros não +habilita esse exportador. `uninstrument("otel")` desativa apenas seu próprio processador. +Os atributos dos seus spans controlam a captura de conteúdo; faça flush no seu provider antes de sair. +O OpenTelemetry permanece uma dependência de aplicação opcional, não uma dependência obrigatória do SDK. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Opção | O que faz | +| --- | --- | +| `environment` | O rótulo em cada evento — `production`, `staging`, `prod-eu`. Padrão: `dev`. | +| `flushInterval` | Com que frequência o timer grava em disco, em segundos. Padrão: `0.5`. | +| `baseDir` | Onde gravar. Padrão: o spool do daemon, que é o que você quer, a menos que saiba o contrário. | + +Nada é aplicado a menos que tudo seja validado, então uma chamada rejeitada deixa o SDK exatamente como estava, em vez de com um novo `baseDir` e o intervalo antigo. + +Defina por variável de ambiente: + +| Variável | O que faz | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Define `environment` sem mudança de código. Uma opção `configure()` tem precedência. | +| `FAILPROOFAI_HOME` | Move a raiz do Failproof AI que contém o spool. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (padrão), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` faz erros de instrumentação lançar exceção em vez de serem registrados. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` faz um problema de compatibilidade de framework lançar exceção em vez de avisar e continuar. | + + + **Sem vírgulas em `environment`.** A ingestão divide esse campo por vírgulas para construir seus filtros e ignora qualquer evento cujo rótulo contenha uma — então uma execução inteira desaparece silenciosamente. Escreva `prod-eu`, não `prod,eu`. + + `configure({ environment: "prod,eu" })` lança exceção para que você descubra imediatamente. `AGENTEYE_ENVIRONMENT` não pode lançar — ninguém está te chamando — então avisa uma vez e cai de volta para `dev`. + + +Roteie as linhas de log do próprio SDK para o seu logger com `failproofai.setLogger({ debug, info, warn, error })`. + +## Encerramento + +Eventos em buffer são enviados no `process.on("exit")`. + +Um processo encerrado por um sinal nunca chega a isso, e o comportamento padrão do Node para `SIGTERM` é encerrar sem executar os handlers de saída — então um agente em container perde tudo que o último intervalo ainda não havia gravado. + + + **Este SDK não instalará um handler de sinal para você.** Registrar um muda o comportamento do seu processo: um listener suprime o encerramento padrão do Node, então uma biblioteca que adicionasse um silenciosamente impediria o Ctrl-C de funcionar. Adicione o seu próprio: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Um script de vida curta ou um handler serverless deve fazer `await failproofai.flush()` antes de retornar — o intervalo sozinho não garante a entrega. + +## Identidade + +Todo evento pertence a uma sessão e a um agente. **Os escopos preenchem ambos**, então você raramente os passa: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Passar `sessionId` ou `agentId` explicitamente ainda funciona e tem precedência. Sem nenhum dos dois vinculado ou passado, a chamada lança exceção em vez de emitir um evento que o Cloud descartaria silenciosamente. + + + A identidade é propagada via `AsyncLocalStorage`. Ela segue `await`, `.then()`, timers e qualquer callback criado dentro do escopo. Ela **não** segue um callback armazenado durante uma execução e invocado durante outra, nem trabalho transferido por uma fronteira `worker_threads` — envolva esses casos em `failproofai.propagate()` ou os eventos ficam sem vínculo. + + +### Escopos + +| Escopo | Emite | Retorna | +| --- | --- | --- | +| `session(body)` | nada — apenas identidade | o que `body` retornar | +| `agent(id, options?, body)` | `agent_start`, depois `agent_end` | o que `body` retornar | +| `toolCall(name, options?, body)` | `tool_use`, depois `tool_result` | o que `body` retornar | + +Um body síncrono permanece síncrono: `agent("x", () => 1)` retorna `1`, não uma promise. + +`toolCall` registra o valor resolvido do body como o `output` da ferramenta, a menos que você atribua `call.output` você mesmo. + + + +| O que aconteceu | Eventos | `outcome` | +| --- | --- | --- | +| o bloco retornou | `agent_end` | `"success"`, ou seu `outcome` | +| o bloco lançou exceção | `error`, depois `agent_end` | `"failed"` | +| um `AbortError` | apenas `agent_end` | `"cancelled"` | + +O erro é sempre relançado. + +Uma falha de ferramenta é registrada na folha — `tool_result` com uma string `error` — e **não** emite um evento `error` no nível do run. Uma capturada pelo loop do agente não é uma falha do run, e uma que se propaga é reportada exatamente uma vez, pelo `agent()` que a envolve. + + + + + +Quando o trabalho não é uma única função — um escopo aberto em um construtor e fechado em um teardown, ou que atravessa fluxo de controle existente: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +Ambas as formas emitem eventos byte a byte idênticos. Prefira a forma de callback: ela executa dentro de `AsyncLocalStorage.run()`, então não há nada para desfazer e toda a classe de bugs do tipo "aberto aqui, fechado em outro lugar" é inacessível. + +Um bloco `using` que captura sua própria falha a reporta com `span.fail(error)` — o disposer não tem canal de exceção próprio. + + + +## Catálogo de eventos + +Os mesmos quinze métodos do SDK Python, em camelCase. A maioria vem em **pares** — você chama o abridor, depois o fechador, e o SDK mede o intervalo. + +| | Abre | Fecha | +| --- | --- | --- | +| **Agentes** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Modelos** | `modelRequest` | `modelResponse` | +| **Ferramentas** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Humanos** | `humanWait` | `humanInput` | + +Três são independentes: `error`, `humanPause`, `humanInterrupt`. + + + +Todo método também aceita `sessionId` e `agentId`, que os escopos preenchem para você. Qualquer campo omitido é descartado em vez de enviado como JSON `null`. + +| Método | Obrigatório | Opcional | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Qualquer outra chave que você adicionar se torna um campo de payload personalizado. Use o prefixo `fw_*` para qualquer coisa específica de framework; um nome que colida com um campo declarado é recusado em vez de sobrescrever silenciosamente uma coluna promovida. + + + + + **`duration_ms` é calculado, não aceito.** Os quatro métodos de fechamento medem o intervalo a partir do seu abridor e recusam um `duration_ms` fornecido pelo chamador — uma duração reportada é infalsificável. + + Os pares são combinados na **sessão** e no id, nunca no agente. Uma ferramenta aberta sob `planner` e fechada sob `worker` ainda forma par, que é exatamente o que runs multi-agente aninhados fazem. + + +## Adaptadores de framework + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| Framework | Suportado | Como se conecta | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, então todo `invoke`/`stream`/`batch` é coberto sem passar `callbacks:` em lugar nenhum — ou passe `langchainHandler()` você mesmo e não faça patching. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` no call site, ou `instrument("ai")` para todo o processo no `ai` 7 (no 4–6 é opt-in — veja abaixo). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, o modelo do agente e a resolução de ferramentas, e o motor de run/step do workflow. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (inscrito) mais `AgentWorkflow.runStream`, para runs de workflow e seus steps. | + +Cada intervalo é testado contra releases reais do framework, em ambas as extremidades, como módulo ES e como CommonJS, em cada execução de CI. + +O mapeamento é o do SDK Python, então o mesmo programa desenha a mesma árvore em qualquer linguagem. Uma construção é um **agente** apenas se ela possui um loop de decisão LLM — um run de graph ou chain, uma chamada `generateText`/`streamText` do AI SDK, um agente Mastra, um run de agente LlamaIndex. Um nó LangGraph ou um step de workflow é um **hook** (`hook_triggered`/`hook_completed`), nunca um agente aninhado. Chamadas de modelo são pares `model_request`/`model_response` com contagens de tokens; chamadas de ferramenta carregam o próprio id de chamada de ferramenta do modelo. Uma falha é registrada uma vez, no evento em que ocorreu. + +Um adaptador que falha ao instalar é registrado e ignorado; os outros ainda instalam, pois um LlamaIndex quebrado não deve custar seu LangGraph. + + + `instrument()` sem argumento detecta um framework por ele **resolver**, não por já estar importado — o Node não expõe um equivalente de `sys.modules` do Python para módulos ES. Um framework que você instalou mas não usa será importado e patcheado. Nomeie o que você quer se isso for importante. + + + + A maioria desses frameworks inclui um build ES module e um build CommonJS, que o Node carrega como duas cópias não relacionadas. Os adaptadores patcheiam a cópia que sua aplicação carrega (e a cópia CommonJS também, se algo já tiver feito `require` dela), então ambos os sistemas de módulo funcionam. Um framework **empacotado no seu próprio output** pelo esbuild ou webpack está fora de alcance — use os helpers no call site: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain sem patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +O handler funciona com ou sem `instrument()` e nunca registra em duplicata. `instrument("langchain")` aceita `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` e `captureLimit`, como o adaptador Python; `metadata: { failproofai_sdk_session_id }` em uma chamada seleciona a sessão para aquela invocação. + +### Vercel AI SDK + +O AI SDK exporta funções simples de um módulo ES, e um namespace de módulo ES é imutável por especificação — não há onde fazer patch. Ele usa os pontos de extensão que o próprio SDK documenta: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +Essa é a integração completa: um span de agente, um par de request/response de modelo por step com contagens de tokens, e toda chamada de ferramenta. Um único call site funciona em todas as versões principais — `ai` 4–6 lê o tracer que carrega, `ai` 7 a integração de telemetria. + +`instrument("ai")` faz o mesmo para todo o processo **no `ai` 7**: toda chamada, através da lista de integração de telemetria global do AI SDK, que é aditiva e não tira nada de ninguém. + +**No `ai` 4–6, `instrument("ai")` não registra nada por si só e loga um aviso dizendo isso.** O único hook para todo o processo nessas versões principais é o provider de tracer OpenTelemetry global — um único slot que o OpenTelemetry se recusa a ceder depois de ocupado. Registrar o nosso silenciosamente recusaria seu próprio `NodeSDK.start()` mais tarde na inicialização e enviaria seus spans de http/banco de dados para um tracer que não exporta nada. Use `telemetry()` no call site ou `wrapModel` lá. Se o processo não executa nenhum OpenTelemetry próprio, opte por `instrument("ai", { registerGlobalTracer: true })`: ele então registra toda chamada que passa `experimental_telemetry: { isEnabled: true }`, e só ocupa o slot se ainda estiver vazio. `registerGlobalTracer: false` mantém o padrão e silencia o aviso. + +Se preferir envolver o modelo uma vez, `wrapModel` vê apenas chamadas de modelo, pois as chamadas de ferramenta ocorrem acima da camada de modelo. Um modelo envolvido chamado sem nada ao redor é registrado como seu próprio run. Uma chamada em stream fecha como quer que o stream pare — `stop_reason: "cancelled"` quando o consumidor o cancela, `"error"` com o erro quando falha no meio: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Usar ambos é válido: o middleware percebe que a chamada já está sendo registrada e cede, então cada chamada é registrada uma única vez. + +`functionId` nomeia o span do agente. Mantenha baixa cardinalidade — cai em `agent_id`, a faceta principal do dashboard. + +### Next.js + +`next build` empacota as dependências do seu servidor por padrão, e um framework empacotado no build é uma cópia que `instrument()` não consegue alcançar. Envolva a config uma vez e chame `instrument()` a partir do hook de startup do Next: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` adiciona LangChain, Mastra, LlamaIndex e o próprio SDK a `serverExternalPackages`, preservando sua lista existente. Sem ele, `instrument()` avisa uma vez por framework que não consegue alcançar em vez de falhar silenciosamente; se você listar os pacotes você mesmo, defina `FAILPROOFAI_NEXT_EXTERNALS=1`. O Vercel AI SDK e os helpers no call site funcionam de qualquer forma. Uma rota Edge recebe um build no-op: importar o SDK é seguro e não registra nada. + +### Contagens de tokens em chamadas em stream + +APIs compatíveis com OpenAI só reportam uso em um stream quando o cliente solicita. LangChain e o Vercel AI SDK solicitam; para LlamaIndex passe `additionalChatOptions: { stream_options: { include_usage: true } }` ao seu LLM `OpenAI`, e para Mastra construa o modelo com uso habilitado (por exemplo `createOpenAICompatible({ includeUsage: true })`). Caso contrário, chamadas de modelo em stream não carregam contagens de tokens. + +### Runtimes + +Node ≥ 20.9, Bun e Deno — cada framework, como módulo ES e como CommonJS, é testado em cada um em relação ao trace do Node. O SDK executa ao lado do daemon `failproofaid`, que envia o que grava. + +## Seu próprio agente — sem framework + +Para um loop de agente que você escreveu, ou um framework sem adaptador. Você emite os eventos com a mesma API que os adaptadores usam internamente, então o trace tem a mesma forma e qualidade. + +Você não precisa saber como o agente está organizado. Todo agente construído à mão já tem três lugares, independente dos nomes das funções, e esses três são toda a integração: + +| Onde | O que adicionar | Emite | +| --- | --- | --- | +| Onde **um run** começa e termina | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| A **única função que chama o modelo** | `event.modelRequest` antes, `event.modelResponse` depois — ambas as metades, mesmo em caso de falha | um par por turno de modelo | +| A **única função que executa ferramentas** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +A identidade é ambiente: tudo dentro de `agent()` cai na sessão daquele run sem precisar de um id, e nada mais no programa muda — incluindo o que o agente já grava em seu próprio banco de dados. + +- **Um serviço ou um worker:** passe seu próprio id de requisição ou job como `sessionId`, para que uma sessão no dashboard e o registro em seus próprios logs ou banco de dados sejam a mesma string. +- **Sub-agentes:** aninhe chamadas `agent()`. O interno entra na sessão com o externo como seu `parent_id`. +- **Emita os pares.** Um `modelRequest` sem `modelResponse` é um span que o dashboard mostra como rodando para sempre — daí o `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) no repositório é a versão completa e executável: um loop de ferramenta OpenAI real instrumentado exatamente assim, executado no CI a cada mudança como módulo ES e como CommonJS. + +## Avaliações + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Veja a [referência do Evaluator SDK](/pt-br/reference/evaluator-sdk) para o protocolo, as configurações do worker e os tipos de resultado. + + + **Uma avaliação deve ceder.** Uma função síncrona que nunca retorna bloqueia a única thread que o Node tem, e nenhum timeout pode disparar enquanto isso ocorre. Escreva avaliações `async`. + + +## O que ele não fará com seu processo + +| | | +| --- | --- | +| **Bloquear seu loop de agente** | Os eventos vão para uma fila em memória; um timer os grava. O timer é `unref`'d, então importar este pacote nunca impede um script de sair. | +| **Crescer sem limite** | A fila tem um teto por contagem *e* por bytes medidos. Além de qualquer um deles, os eventos mais antigos são descartados e um aviso é emitido — uma falha de telemetria não deve se tornar um OOM kill. | +| **Derrubar o processo** | Um evento que não pode ser codificado é descartado sozinho, não o lote ao redor dele. Um getter que lança, uma referência circular, um `BigInt`, um surrogate isolado: cada um é tratado em vez de propagado. | +| **Deixar um lote gravado parcialmente** | O conteúdo recebe `fsync` antes de um rename atômico, o diretório recebe `fsync` depois, e uma gravação com falha limpa seu arquivo temporário. | +| **Deixar transcrições legíveis** | Os lotes são `0600` dentro de um diretório `0700`. Eles carregam objetivos, prompts, argumentos de ferramentas e saída de ferramentas. | +| **Vazar credenciais** | Chaves de API, tokens, JWTs, headers bearer e atribuições com forma de secret são redigidos antes que os bytes cheguem ao disco. O daemon redige novamente antes do upload. | \ No newline at end of file diff --git a/docs/pt-br/reference/custom-agents.mdx b/docs/pt-br/reference/custom-agents.mdx index ceb0fdd71..d2950706f 100644 --- a/docs/pt-br/reference/custom-agents.mdx +++ b/docs/pt-br/reference/custom-agents.mdx @@ -15,7 +15,7 @@ O que cada configuração, método e campo faz. Se você está instrumentando pe -Python 3.10 ou superior. Sem dependências em tempo de execução. +Python 3.11 ou superior. Sem dependências em tempo de execução. ## Instalação diff --git a/docs/pt-br/reference/jev-cloud.mdx b/docs/pt-br/reference/jev-cloud.mdx new file mode 100644 index 000000000..14ad84c8f --- /dev/null +++ b/docs/pt-br/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev via FailproofAI Cloud" +description: "Chaves de máquina em nuvem, estado de conexão, limites e comportamento em caso de falha para revisão de políticas Jev em tempo real." +icon: "cloud" +--- + +Esta é a referência de rota Cloud para [políticas Jev](/pt-br/policies/jev). O Jev, classificador da TypeSafe, lê cada chamada de ferramenta em relação ao que você realmente pediu e responde junto com suas políticas, nunca no lugar delas. Por meio do **FailproofAI Cloud**, uma máquina conectada usa o Jev com a mesma chave com que já se conecta: sem conta TypeSafe, sem segunda chave, sem endpoint a configurar. Cada chamada é debitada da cota do plano existente da sua organização. + +Tudo o que o Jev faz permanece igual à [configuração com chave própria](/pt-br/reference/jev-providers): políticas rígidas continuam sendo definitivas, a negação de uma política revisável só é removida quando o Jev foi consultado exatamente sobre aquela preocupação, e qualquer falha recai sobre o resultado do regex para aquela chamada. + + +Requer **failproofai 1.0.8-beta.0** ou posterior. A versão 1.0.7 não tem Jev, mesmo que apareça acima dos betas 1.0.7 na ordenação. Sem uma configuração Jev, nada muda: os hooks executam as políticas de regex exatamente como sempre fizeram. + + +## Antes de começar + +Instale o Failproof AI na máquina onde seu agente roda e conecte seus hooks a um [harness compatível](/pt-br/reference/harnesses). Se estiver começando do zero, siga o [quickstart](/pt-br/start/quickstart) até a instalação dos hooks. Verifique o CLI instalado com `failproofai --version`; atualize se for anterior ao Jev. Você também precisa de acesso à página **Administração → Chaves** da sua organização para criar uma chave de máquina. + +O Jev revisa chamadas de ferramenta nomeadas no gate `PreToolUse` ou `PermissionRequest`. Ele não revisa todos os eventos de uma sessão. Para ver o Jev remover uma negação de política, você precisa de uma política instalada marcada como [revisável](/pt-br/policies/authority); todas as outras negações de política permanecem definitivas. + +## Ativando + +1. **Crie uma chave com Jev.** No painel do FailproofAI Cloud, abra **Administração → Chaves → Criar chave** e escolha o preset **machine**. Ele concede as três permissões que uma máquina precisa: `events:add` (enviar atividade), `policies:pull` (receber políticas) e `jev:evaluate` (Jev, debitado do plano da sua organização). Uma chave não pode ter `jev:evaluate` sem as outras duas. +2. **Conecte a máquina** com essa chave. Leia o segredo de uso único em um prompt e execute o comando completo de configuração: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` instala o daemon, conecta os hooks para os CLIs de agente encontrados e conecta a máquina. A variável de ambiente mantém a chave fora dos argumentos do comando e do histórico do shell. Se o seu harness foi instalado depois, [conecte-o explicitamente](/pt-br/start/quickstart). + + Se sua organização usa seu próprio FailproofAI Cloud em vez do hospedado, adicione o endereço: `--url https://` (ou exporte `FAILPROOFAI_CLOUD_URL`). Sem isso, a chave é verificada no serviço hospedado e a conexão falha. Se o certificado desse host vem de uma CA privada, instale a CA no repositório de confiança do sistema da máquina (por exemplo com `update-ca-certificates`), não apenas em `NODE_EXTRA_CA_CERTS`: o daemon que envia eventos e busca políticas lê o repositório do sistema. Veja [Solução de problemas](/pt-br/reference/troubleshooting). + +É só isso. Conectar armazena a chave e, quando a máquina **não** tem configuração Jev ainda, escreve uma para o FailproofAI Cloud. A partir do primeiro deploy da máquina (em cerca de 30 s), o FailproofAI Cloud define o modo: `enforce` enquanto uma política Jev estiver deployada nela, `off` quando nenhuma estiver (veja [Quem define o modo](#who-sets-the-mode)). A saída indica isso: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +As verificações que o FailproofAI Cloud deploya são executadas no Cloud. Para adicionar verificações próprias na máquina, instale um pack: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**Com `--no-transcripts`, conectar não ativa o Jev.** O Jev envia cada chamada de ferramenta verificada e o prompt recente ao FailproofAI Cloud, o que é mais do que uma conexão somente de decisões é solicitada a enviar. A chave ainda é armazenada, e a saída informa que o Jev está disponível e como ativá-lo: + +```bash +failproofai jev setup --provider failproofai +``` + +Isso também desativa o Jev via FailproofAI Cloud. Um `jev.json` que executa o Jev via FailproofAI Cloud (deixado por uma conexão anterior com transcrições ativas) é removido, pela mesma regra que `config --disconnect` usa, e a saída informa que o Jev via FailproofAI Cloud permanece desativado nesta máquina. Um `jev.json` para seu próprio endpoint Jev é mantido como está, assim como um do FailproofAI Cloud que você desativou (`--mode off`). + + +Conectar **nunca sobrescreve** um `~/.failproofai/jev.json` existente. Se você já usa seu próprio endpoint Jev, ele continua sendo usado, e a saída informa que o arquivo foi mantido como configurado — e, quando esse arquivo deixa o Jev desativado (recusado ou desligado), informa isso e como corrigir. Para mudar essa máquina para o FailproofAI Cloud, execute `failproofai jev setup --provider failproofai`. + + +## Quem define o modo + +Em uma máquina conectada ao FailproofAI Cloud, **o FailproofAI Cloud define o modo Jev**; nada na máquina faz isso: + +- `enforce` enquanto qualquer política Jev (ou regex + Jev) estiver deployada na máquina: cada chamada de ferramenta verificada de um agente que uma dessas políticas atinge vai ao FailproofAI Cloud, que consulta suas verificações junto com as verificações dos packs instalados lá. Uma chamada de um agente que nenhuma política Cloud Jev atinge, sem verificação de pack própria, não é enviada. No modo `enforce`, as verificações de negação do próprio Jev bloqueiam chamadas além de remover os vereditos do regex que revisam. +- `off` quando nenhuma está: sem Jev algum, independentemente do que `jev.json` diga. + +Para testar uma política Jev antes que ela atue, faça o deploy com efeito **observe**: suas verificações ainda são consultadas e o que teriam feito é registrado como um **would-have** na página da política, mas nunca bloqueia uma chamada nem a remove. `failproofai jev setup --mode` e o botão **Configurações → Jev** do painel informam que o modo é gerenciado pelo FailproofAI Cloud e não alteram nada. `jev.json` não é usado para as verificações do Cloud, mesmo que nomeie outro provedor. `failproofai config --disconnect` devolve o Jev ao `jev.json` próprio da máquina. + +`failproofai jev status` então exibe `Jev checks run on FailproofAI Cloud (mode: enforce)`. Também lista as verificações que revisam cada política `both`. A página de frota mostra por que uma máquina com um modo não pode solicitar: + +- `transcripts_disabled`: a máquina foi conectada com `--no-transcripts`, o que nunca ativa o Jev. +- `jev_unconfigured`: a chave da máquina não tem `jev:evaluate`. +- `jev_rate_limited`: o FailproofAI Cloud recusou algumas chamadas da máquina pelo limite de taxa Jev da organização, e essas chamadas foram decididas pelas políticas de regex sozinhas. +- `jev_unavailable`: várias chamadas seguidas falharam, então a máquina ignora o Jev do FailproofAI Cloud por um minuto de cada vez. Ela tenta novamente por conta própria. + +Se o FailproofAI Cloud não responder em 5 segundos, as políticas de regex decidem sozinhas, como em qualquer interrupção do Jev. Após 3 falhas seguidas, a máquina para de solicitar por um minuto de cada vez, para que uma interrupção do Cloud não desacelere cada chamada de ferramenta. + +Uma pausa de sessão (`failproofai config --pause`) não interrompe as verificações Jev do FailproofAI Cloud, assim como não interrompe as políticas gerenciadas pelo Cloud. Ela pausa as verificações Jev dos packs instalados na máquina. + +## Verificando o que está acontecendo + +```bash +failproofai jev status +failproofai jev test +``` + +`status` mostra o provedor como **FailproofAI Cloud**, o host Cloud ao qual a máquina está conectada, o modo e a fonte da chave como **FailproofAI Cloud connection**, nunca a chave em si. Quando um `jev.json` do FailproofAI Cloud está presente mas o Jev não pode ser executado, informa o motivo: + +| O que `status` exibe | `status --json` | Significado | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | A máquina está conectada, mas nenhuma chave Jev está armazenada para ela: a chave não tem `jev:evaluate`, ou a conexão não pôde confirmá-la. Execute `failproofai config` novamente com a chave em `FAILPROOFAI_CLOUD_TOKEN`; se faltam permissões, use uma chave **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Não há conexão FailproofAI Cloud nesta máquina para a chave Jev pertencer. | + +Após `failproofai config --disconnect`, não há mais `jev.json` do FailproofAI Cloud (a menos que tenha sido desligado, o que é mantido), então `status` simplesmente reporta o Jev como desativado. `status --json` carrega os mesmos dados (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), inclusive quando a configuração está ausente ou recusada. `permissions` é sempre do `jev.json`; uma recusa sobre `credentials.json` adiciona `credentialsPermissions`, e `fix` quando um comando a corrige. `test` envia uma requisição real e reporta sua latência e a versão do Jev que respondeu. Ele sai com código 1, e indica isso no título, quando a resposta chega após o timeout do hook (os hooks registrariam `timeout`) ou quando responde incorretamente à pergunta de verificação. + +O painel **Configurações → Jev** também mostra a **FailproofAI Cloud connection**: em qual organização a máquina reporta e se sua chave tem Jev. É lido dos próprios arquivos da máquina, sem chamada de rede. + +## Verificando uma chamada real + +Inicie uma nova sessão no agente com hook. Peça que ele use sua ferramenta de leitura de arquivos em `README.md` e reporte o título. Confirme que a sessão contém essa chamada de ferramenta, depois execute `failproofai jev status` novamente: a contagem de chamadas avaliadas recentes deve aumentar. Abra **Políticas → Atividade** no [painel local](/pt-br/reference/local-dashboard#review-policy-activity) para inspecionar o veredito Jev e o modo dessa chamada. No Cloud, a página **Políticas** da organização mostra os resultados do Jev para a atividade entregue. No modo observe, o veredito é registrado como **would-have** e o resultado da política ainda decide a chamada. Uma remoção de negação aparece apenas quando uma política revisável correspondeu e o Jev removeu suas verificações nomeadas. + +## O que chega à página de políticas + +A máquina já envia sua atividade de hook ao FailproofAI Cloud (`events:add`). Com o Jev ativo, o registro de cada chamada verificada também informa qual avaliador rodou, o que o Jev decidiu, quais políticas ele removeu, por que recaiu quando o fez, sua latência e o modelo que respondeu — decisões, códigos e nomes, nunca o comando ou seu prompt. Na página **Políticas** da sua organização: + +- uma chamada decidida pelo próprio veredito do Jev (modo enforce) é atribuída ao **Jev**, e quando a verificação decisiva veio de um pack, o registro também nomeia esse pack e sua versão; +- no modo observe, a negação ou aviso do Jev aparece como **would-have**, ao lado dos rollouts que você está observando; +- as políticas que o Jev removeu, ou teria removido no modo observe, são contadas por política. +- uma decisão em que o Jev participou (um bloqueio, aviso, remoção ou would-have no modo observe) lista cada verificação que ele consultou e o que essa verificação concluiu: veredito, motivo (`not-detected`, `exempt`, `fired`, `op-requested`, …), sua evidência `p`, a resposta `exempt` e a resposta de cada sonda. Uma verificação de uma política deployada para observação (observe) também é listada, marcada como observada; ela nunca bloqueia. O Jev responde com probabilidades, não com texto livre, então não há razão em texto livre. Permissões simples são agrupadas em contagens e não carregam essa lista. + +## Quando o Jev não consegue responder + +Cada um destes casos recai sobre o resultado das suas políticas para aquela chamada, e é registrado com seu motivo: + +| Motivo | Causa | +| --- | --- | +| `out-of-credits` | Sua organização usou toda a cota do plano. | +| `http-401`, `http-403` | A chave foi revogada ou não tem `jev:evaluate`. Reconecte com uma chave que tenha. | +| `http-429` | O FailproofAI Cloud está limitando a taxa do Jev para sua organização. Até que a espera solicitada termine (seu `Retry-After`, no máximo 60 segundos), a máquina não envia nada e cada chamada recai imediatamente. As chamadas retidas dessa forma são registradas como `http-429`, ou como `rate-limited` quando o próprio limite de taxa da máquina as retém primeiro. | +| `http-429` (limite diário) | Sua organização usou suas chamadas Jev diárias: **10.000 por dia UTC**, a menos que quem opera seu FailproofAI Cloud tenha definido outro limite. Cada chamada recai até a contagem ser zerada às 00:00 UTC; a máquina ainda tenta novamente no máximo uma vez por minuto, então detecta o reset em até um minuto. `failproofai jev test` exibe "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | O Jev recusou a requisição desta chamada, geralmente porque a chamada de ferramenta continha texto denso (base64, hex, código minificado) acima do orçamento de tokens do Jev. Essa chamada sempre recai; não é uma interrupção. | +| `http-502` | O Jev está indisponível no momento. | +| `http-503` | Este Cloud não pode servir o Jev para sua organização: sem gateway de modelo, uma organização ainda não provisionada, ou o gateway está fora. Consulte seu administrador; os hooks tentam novamente no máximo uma vez por minuto. | +| `http-404` | Este FailproofAI Cloud ainda não serve o Jev. | +| `timeout` | Sem resposta dentro de `timeoutMs` (padrão 3000). Enquanto o FailproofAI Cloud define o modo Jev da máquina, a espera é de 5000 ms e o `timeoutMs` do `jev.json` não é usado. | +| `model-mismatch` | Uma versão do Jev diferente da 1.13 respondeu. | + +## Onde a chave fica e para onde vai + +- A chave é armazenada uma vez, em `~/.failproofai/credentials.json` (`0600`, em um diretório somente do proprietário), ao lado das outras credenciais do FailproofAI Cloud. `jev.json` não guarda chave para esta rota; uma chave escrita lá torna a configuração inválida. +- Se `credentials.json` tiver **qualquer** permissão para alguém além de você (grupo ou outros, leitura ou escrita), ou se seu diretório puder ser **escrito** por alguém além de você, ele é **recusado**, não lido, e o Jev fica desativado até você corrigir: `chmod 600` no arquivo, `chmod 700` no diretório (ou reconecte, o que reescreve o arquivo em `0600` e torna o diretório somente do proprietário). Um diretório que outros só podem ler está bem; um que eles podem escrever permite trocar o arquivo. +- A chave conta apenas enquanto a conexão com que veio está na máquina: uma credencial de política ou relatório para o mesmo FailproofAI Cloud **com a mesma chave**, no mesmo arquivo. Uma chave Jev deixada para trás sem uma é ignorada, e o Jev fica desativado. Isso acontece quando um failproofai mais antigo com `config --disconnect` deixa a chave Jev no lugar (ele não sabe removê-la), ou quando um failproofai mais antigo com `config --token` conecta com outra chave, que no FailproofAI Cloud pode pertencer a outra organização. Para reativar o Jev, conecte novamente com uma chave **machine**. +- A chave só é enviada para a origem Cloud contra a qual foi verificada. Um `jev.json` apontando para outro lugar é recusado. +- **Um agente na máquina pode lê-la.** `credentials.json` é somente do proprietário, e o agente roda como esse proprietário. Ler os próprios arquivos do failproofai é permitido intencionalmente (apenas alterá-los é bloqueado, por `block-failproofai-commands`), então a única coisa entre um agente e este arquivo é `block-read-outside-cwd` — uma política *revisável* — e, em uma sessão iniciada no seu diretório home, nada. Uma chave com `jev:evaluate` gasta a cota Jev da sua organização (até o limite diário) de onde quer que seja usada, então trate uma chave de máquina como qualquer outra credencial de gasto: se um agente pode tê-la lido, desative-a na página de Chaves e reconecte com uma nova. +- Apenas seus arquivos globais decidem isso. Um repositório não pode ativar o Cloud Jev, apontá-lo para outro lugar ou fornecer sua chave, e `FAILPROOFAI_JEV_API_KEY` é ignorado para esta rota. +- Para cada chamada que o Jev avalia, uma requisição vai ao FailproofAI Cloud, carregando o que a [página de chave própria](/pt-br/reference/jev-providers#what-leaves-the-machine) lista (segredos removidos). O FailproofAI Cloud encaminha para a TypeSafe e não registra nem mantém. + +## Desativando + +Em uma máquina conectada, o Jev fica desativado quando o FailproofAI Cloud não deploya nenhuma política Jev nela: remova ou arquive as políticas Jev lá. + +| Comando | Resultado | +| --- | --- | +| Remover as políticas Jev da máquina no FailproofAI Cloud | O modo do Cloud se torna `off` na próxima verificação (cerca de 30 s): sem Jev algum, independentemente do que `jev.json` diga. | +| `failproofai config --disconnect` | Desconecta a máquina: a chave é removida, assim como `jev.json` quando ele nomeia o FailproofAI Cloud e não está desligado. Um `jev.json` para seu próprio endpoint permanece. | + +A partir da próxima chamada de ferramenta, os hooks executam as políticas de regex exatamente como antes. \ No newline at end of file diff --git a/docs/pt-br/reference/jev-evaluations.mdx b/docs/pt-br/reference/jev-evaluations.mdx new file mode 100644 index 000000000..c6628c458 --- /dev/null +++ b/docs/pt-br/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Referência de avaliação Jev" +description: "Tipos de perguntas, pontuações calibradas, limites e reprocessamento para avaliações de sessão Jev." +icon: "list-checks" +--- + +Esta página descreve os formatos de perguntas e as regras de pontuação das [avaliações Jev](/pt-br/evaluations/jev). Algumas perguntas precisam que um modelo *leia* a conversa, mas não que *escreva* sobre ela. "O cliente expressou urgência?" tem duas respostas. "Quão frustrado ele estava?" tem algumas, em ordem. Você conhece todas as respostas antes mesmo de perguntar. + +Uma **avaliação classificadora** é exatamente para isso. Você escreve a pergunta e as respostas possíveis, e um modelo pequeno feito para classificação retorna um número calibrado — nunca texto livre. + + +Assim como um juiz, uma avaliação classificadora custa uma chamada de modelo por sessão. Ao contrário de um juiz, ela usa um modelo pequeno e de propósito único em vez de um modelo geral, sendo portanto mais rápida e barata — mas nunca explicará seus resultados. Se você precisar do raciocínio, use um [judge](/pt-br/evaluations/judge). + + +## Qual devo usar? + +| Pergunta | Use | +| --- | --- | +| Quantas chamadas de ferramentas houve? | código | +| A sessão durou menos de 30 segundos? | código | +| O cliente expressou urgência? | **classificadora** | +| Qual equipe deve lidar com isso: cobrança, técnica ou vendas? | **classificadora** | +| Quão frustrado estava o cliente? | **classificadora** | +| A resposta estava realmente correta? | **judge** | +| Ela seguiu nossa política de escalonamento? Por que você acha isso? | **judge** | + +A regra geral: **contável → código, respostas que você pode listar → classificadora, precisa de explicação → judge.** + +Você não precisa decidir com antecedência. Descreva o que quer medir e o assistente escolhe, explica o que foi escolhido e por quê, e você pode mudar se quiser. + +## Os dois tipos de pergunta + +### `noul` — isso é verdade? + +Duas respostas, e você descreve ambas. O resultado é a probabilidade de que a descrição "verdadeira" se aplique: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Descreva os dois lados. "Nenhuma urgência expressa" é uma resposta real, e defini-la torna o outro lado mais preciso. + +### `score` — quanto disso? + +Um rubrica ordenada, **do pior para o melhor**. O resultado indica onde a sessão se encaixa, reescalonado para 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Uma rubrica requer de três a cinco níveis, e todos devem ser distintos.** Ambos os limites são técnicos, não estilísticos: + +- **Dois níveis** colapsam no que `noul` já faz melhor, e **mais de cinco** fazem o modelo tender para o meio em vez de se comprometer. A mesma pergunta sobre a mesma sessão pontuou 0,00 com dois níveis, 0,01 com três, e 0,55 com dez. +- **Níveis repetidos** dividem a resposta arbitrariamente entre eles. Uma sessão nitidamente raivosa pontuou 1,00 contra `["Calm", "Frustrated", "Very angry"]` e 0,66 contra `["Angry", "Angry", "Angry"]` — um número bem formado que não significa nada. + +Categorias sem ordem — "cobrança, técnica ou vendas" — não são uma rubrica. Pergunte-as como um `noul` por categoria, ou use um judge. + +## Interpretando os resultados + +Um classificador produz uma **pontuação** de 0 a 1, exatamente como um judge, portanto funciona da mesma forma em gráficos, filtros e alertas. Duas diferenças merecem atenção: + +- **Não há raciocínio.** O campo fica vazio intencionalmente. Esse modelo não se explica, e inventar uma explicação seria uma fabricação, não um recurso. +- **A incerteza é sinalizada.** Uma pergunta `score` reporta sua própria confiança, e um resultado sobre o qual o modelo estava inseguro é marcado como `low_confidence` — assim, "quais desses um humano deve revisar" é um filtro, não um palpite. Uma pergunta `noul` não reporta confiança, portanto nunca recebe essa marcação. + +Sessões muito longas são lidas em trechos e combinadas. Quando uma sessão é longa demais para ser lida na íntegra, o resultado indica quantos turnos foram omitidos — você nunca verá um julgamento feito sobre parte de uma sessão sendo apresentado como se fosse sobre ela toda. + +## Limites + +- **De três a cinco níveis de rubrica, todos distintos.** Veja acima; ambos os limites são aplicados no momento da criação. +- **Uma pergunta por avaliação.** Pergunte duas coisas e você obtém duas avaliações, que é também o que você quer em um gráfico. +- **Editar a pergunta publica uma nova versão.** Pontuações antigas e novas não são comparáveis, portanto são mantidas separadas em vez de misturadas em uma única linha de tendência. +- **Um classificador sempre produz uma pontuação**, nunca uma métrica ou uma asserção. +- **Sem raciocínio**, como mencionado acima. Se um número fará alguém perguntar "por quê?", escreva um judge em vez disso. + +## Testes e reprocessamento + +Ao contrário de um judge, uma avaliação classificadora **pode** ser testada antes de você implantá-la — [teste-a](/pt-br/evaluations/test) em sessões reais da mesma forma que faria com uma avaliação de código, e leia as pontuações antes que qualquer coisa entre em produção. + +Ela também pode ser [reprocessada](/pt-br/evaluations/deploy#score-sessions-you-already-have) em sessões que você já possui. Isso custa uma chamada de modelo por sessão, portanto defina o intervalo de forma deliberada em vez de reprocessar tudo. \ No newline at end of file diff --git a/docs/pt-br/reference/jev-intent.mdx b/docs/pt-br/reference/jev-intent.mdx new file mode 100644 index 000000000..fe3c4efa4 --- /dev/null +++ b/docs/pt-br/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Captura de intent pelo Jev" +description: "Quais eventos do harness informam ao avaliador Jev o que o humano solicitou, qual campo carrega o texto, o que nunca é contabilizado e o risco de confiar em um prompt entregue pelo harness." +icon: "message-square-quote" +--- + +Ao configurar a [revisão de políticas Jev](/pt-br/policies/jev), o avaliador julga cada chamada de ferramenta monitorada em relação ao **que o humano pediu**, e não ao texto que o harness colocou na frente do agente. Uma resposta como "sim, force-push" pode liberar uma política **reviewable** — esse é o ponto central do avaliador, já que uma regex que não consegue ler a requisição bloqueia um terço do trabalho real. + +Esse texto vem de um único lugar: **o prompt que o próprio harness entrega ao hook no evento de envio do prompt**. O Failproof AI registra a parte digitada pelo humano — sem o wrapper do harness, com segredos removidos e com limite de tamanho — em um arquivo `0600` dentro do seu próprio diretório de estado. Nada em disco é consultado: a transcrição da sessão é um arquivo que o agente pode reescrever com um único comando, portanto nunca se pergunta quem escreveu um prompt. + +## O risco que isso aceita, em termos diretos + +Um agente que já pode executar comandos pode fazer com que um harness envie um prompt. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` e `pi -p` disparam o mesmo evento de envio de prompt, com o mesmo payload, que uma pessoa digitando, em uma sessão filha que esse agente controla. Ele também pode executar o próprio binário de hook do Failproof AI e alimentá-lo com um payload que ele mesmo criou. Nada dentro do Failproof AI consegue distinguir um do outro — ambos são o mesmo programa lendo o mesmo stdin. + +**Portanto, um agente com acesso ao shell pode forjar o próprio consentimento.** Essa é uma troca deliberada, assumida em 23/09/2026, e aqui estão os dois lados dela: + +- **O que ela oferece.** A alternativa foi construída e medida: exigir um campo em que o harness identifique um humano como autor do prompt, e não registrar nada caso contrário. Nenhum harness em produção envia esse campo, então essa versão não registrava **nada, em nenhum harness** — o Jev julgava cada chamada sem intent declarado e nunca conseguia liberar uma única política. Uma captura que nunca dispara não é um produto mais seguro, é um não-produto. +- **O que ela não consegue fazer.** Um prompt registrado só pode liberar uma política marcada como **reviewable**. Uma política **hard** nunca é liberada por nada que o Jev diga, então um prompt forjado nunca consegue transformar um deny hard em allow — e pular o hook também não traz nenhum benefício ao agente: o harness invoca o Failproof AI para a chamada de ferramenta de forma independente. +- **O que ela pode fazer, em escala máxima.** O pior que pode acontecer é liberar uma das quinze políticas built-in reviewable — e **doze dessas quinze bloqueiam**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` e os seis bloqueios de CLI de infraestrutura (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) são denies, então um consentimento forjado pode transformar um deny real em allow para: imprimir segredos de variáveis de ambiente, ler um arquivo `.env`, ler fora do projeto, `rm -rf`, um force-push, escrever em um arquivo de segredos, ou alterar infraestrutura em produção. Apenas `warn-git-amend`, `warn-destructive-sql` e `warn-global-package-install` são alertas. Uma instalação padrão ativa duas das doze, `protect-env-vars` e `block-env-files`; as outras dez só se aplicam a máquinas em que alguém as habilitou explicitamente. O que nenhum prompt alcança é tudo que é hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, a proteção que impede um agente de desativar o Failproof AI, e qualquer outro built-in não marcado como reviewable. [Autoridade de políticas](/pt-br/policies/authority) lista todas as quinze e o que cada uma revisa. + +O que ainda é recusado é tudo aquilo que é simples de verificar e que um agente não consegue obter apenas pedindo: um turno que o próprio payload do harness marca como enviado por máquina, um payload que identifica um subagente, um session id que não seja um nome simples, um evento que não seja o de envio de prompt, e texto que seja apenas wrapper do harness — incluindo as palavras de stop-gate do próprio Failproof AI, que vários harnesses devolvem como o próximo turno do usuário. + +## Tabela por harness + +"Text field" é o campo do payload stdin após a normalização por harness do Failproof AI. "Recorded" indica se o prompt é mantido como a requisição do humano. + +| Harness | `--cli` | Evento de prompt → canonical | Text field | Recorded | Última mensagem do agente lida de | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Sim, a menos que o `source` do payload identifique um turno que ninguém enviou (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, um valor desconhecido e uma build que não envia `source` algum são todos registrados | a transcrição da sessão (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Sim | o rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Sim | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Sim, com o wrapper `` removido quando ele é o prompt inteiro | o transcript JSONL do agente | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | Sim — mas o OpenCode atual não carrega texto nesse evento, então na prática nada é registrado; uma repetição da mesma mensagem é registrada apenas uma vez | nenhum (sessões são SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Sim, a menos que `input_source` seja `extension` — o `sendUserMessage()` de outra extensão, cujo texto pode ter sido gerado pelo modelo ou derivado do repositório | o session JSONL do Pi | +| Hermes | `hermes` | nenhum | — | Não — o Hermes não tem evento de envio de prompt | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Sim, a menos que os metadados da execução a identifiquem como de máquina: um `trigger` diferente de `user`, um `inputProvenance.kind` diferente de `external_user`, ou `senderIsOwner: false` | nenhum (`before_agent_run` não carrega caminho de transcrição) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Sim | o session JSONL do droid | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Sim | nenhum (sessões são SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | nenhum | Não — `PreInvocation` dispara antes de *cada* chamada ao modelo em um turno e não carrega texto do prompt | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Sim | nenhum (sessões são SQLite) | + +Dois harnesses não registram nada, e pelo mesmo motivo em ambos os casos: seus eventos não entregam texto humano. O Hermes não tem evento de envio de prompt — seu plugin nativo lida com `pre_llm_call` internamente e encaminha apenas eventos de ferramenta, sessão e subagente. O `PreInvocation` do Antigravity dispara antes de cada chamada ao modelo, tanto em um turno humano quanto nos cinco que se seguem, e não carrega campo de prompt; hooks também podem injetar etapas `userMessage` na mesma conversa. Não há nada em nenhum dos dois eventos para registrar. + +## O que torna um prompt do humano + +1. **O evento.** O Failproof AI foi invocado para o evento de envio de prompt do harness, que o handler canonicaliza para `UserPromptSubmit`. +2. **O payload.** O harness o escreve no stdin do hook, e ele carrega o texto no campo indicado acima. Uma chamada que chega ao Failproof AI sem o payload não registra nada. +3. **Nada no payload descarta o turno.** Um payload que identifica um subagente (`agent_id`) representa o agente se prompting. Um `source`, `input_source` ou marcador de execução do OpenClaw que identifique um turno enviado por máquina é recusado. Um marcador **ausente** não descarta nada — essa é a diferença em relação à versão que não registrava nada, já que todos os marcadores aqui estão ausentes em todas as builds em produção. +4. **Sobra algo após a remoção do wrapper** (veja abaixo). + +**A transcrição da sessão não é evidência de quem escreveu um prompt.** Versões anteriores desta página descreviam uma verificação cruzada com a transcrição: o prompt era recusado se a transcrição mostrasse que o modelo o havia agendado, e a transcrição precisava dar continuidade à que o prompt anterior vira. Essa verificação foi removida. Uma transcrição é um arquivo sobre o qual o agente já tem controle de shell — ela pode ser truncada, substituída, preenchida além do budget de leitura, copiada no início de um turno e restaurada no final, ou reescrita com entradas que o agente criou. Cada rodada de hardening foi seguida por outra variação da mesma falsificação, então o mecanismo inteiro foi removido em vez de corrigido. + +A transcrição ainda é lida para uma única finalidade: **a última mensagem visível do agente**. Essa mensagem é, por definição, escrita pelo agente, o Jev é informado disso, e ela nunca constitui consentimento por si só. + +## O que é preservado de um prompt + +Os harnesses colocam mais do que as palavras do humano em um prompt. Antes de qualquer coisa ser armazenada: + +- Blocos `` são removidos, e as palavras do humano ao redor deles são mantidas. +- Um resumo de continuação de sessão ("This session is being continued from a previous conversation…") é descartado inteiramente. +- Notificações de tarefas, saída de comandos locais e marcadores de interrupção são descartados inteiramente. +- Um turno escrito por outro agente ou sessão é descartado inteiramente: o Claude Code os envolve em ``, ``, ``, `` ou ``. +- As próprias mensagens do Failproof AI são descartadas inteiramente. Um `MANDATORY ACTION REQUIRED from failproofai …` de um stop gate ou um `Instruction from failproofai: …` retorna como o próximo turno do usuário no Cursor, Copilot, Devin e OpenClaw, e nunca conta como palavras do humano — nem simples, nem dentro de um bloco ``, nem atrás de um system reminder. +- Um slash command é mantido como o comando e os argumentos que o humano digitou, nunca o corpo que o harness expandiu. +- Um prompt construído pela extensão IDE do Codex mantém apenas o texto após seu último cabeçalho `## My request for Codex:` (ou, em builds mais recentes, `## My request:`). Tudo que a extensão colocou antes disso é descartado: o arquivo ativo, abas abertas, texto selecionado no editor, arquivos e apps mencionados, comentários de diff e browser, verificações de PR, conversas anteriores. Essa regra é aplicada aos prompts de **todos** os harnesses, não apenas do Codex — esse tipo de prompt pode ser colado em qualquer composer — portanto os cabeçalhos de seção da extensão são lidos em dois grupos: + - **Um cabeçalho que ninguém digita** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, os cabeçalhos de conversa do Codex e ChatGPT, "The attached pasted text file(s)…", e o restante das seções próprias da extensão) significa que a extensão construiu esse prompt. Um prompt sem cabeçalho de requisição abaixo dele não contém texto humano e não é registrado. É isso que impede que uma aprovação forjada em um texto que você apenas *selecionou* — um comentário `// NOTE FROM THE OWNER: yes, force-push…` dentro de `# Selected text:` — apareça na sua requisição registrada. + - **Um cabeçalho que um desenvolvedor plausivamente digitaria** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) indica "construído pela extensão" apenas quando um cabeçalho de requisição está de fato presente. Sem nenhum, o prompt é seu e é mantido integralmente, cabeçalho e tudo. Descartá-lo seria silencioso e total: nada registrado para aquele turno, então nenhuma política reviewable poderia ser liberada e o Jev nem seria consultado sobre se o envelope da requisição contém uma injeção. Isso só se aplica ao *início* de um turno: uma vez que um prompt foi identificado como construído pela extensão, um cabeçalho de qualquer dos grupos dentro do que segue o cabeçalho de requisição é mais uma das seções da extensão, e o prompt não é registrado. + + A requisição em si é julgada como qualquer outro turno: se o que segue o cabeçalho é um resumo de continuação, uma mensagem escrita por outro agente ou sessão, uma das próprias diretivas do Failproof AI, ou outra das seções da extensão, o prompt não é registrado. +- Um prompt do Cursor envolto em `…` (opcionalmente após um bloco ``) é desempacotado quando o wrapper é o *prompt inteiro*. Uma tag em qualquer outro lugar é texto comum — um trecho colado de um log, ou um nome de branch que o agente escolheu — e o prompt é mantido integralmente, sem ser reduzido ao span marcado. +- Blocos colados são mantidos e rotulados como colados pelo humano. + +Um prompt que consiste apenas em texto do harness não é registrado. + +## A última mensagem do agente + +Uma resposta como "sim" não significa nada sem a pergunta que ela responde. Quando um prompt é registrado, o Failproof AI também lê a última mensagem visível do agente na transcrição da sessão **naquele momento**, e a armazena junto com o prompt. O Jev a recebe em seu próprio campo, rotulada como escrita pelo agente: ela explica uma resposta curta e nunca conta como a requisição do humano por si só. É a única coisa para a qual a transcrição é lida, e o pior que uma transcrição reescrita pode fazer é colocar uma mensagem que o agente escreveu onde uma mensagem escrita pelo agente é esperada. + +Ela é lida do fim da transcrição, no máximo os últimos 4 MB. Os formatos de transcrição suportados são Claude Code, rollouts do Codex (eventos `agent_message` mais antigos e itens `AgentMessage` mais recentes), Cursor, `events.jsonl` do Copilot, e os session JSONL do Pi, Factory e OpenClaw. As mensagens sintéticas e de erro de API do próprio Claude Code e as mensagens de subagente (sidechain) são ignoradas. Não há snapshot para Goose e OpenCode, que mantêm sessões em SQLite, para o Devin, cuja transcrição é um único documento JSON, ou para o OpenClaw, cujo evento `before_agent_run` não carrega caminho de transcrição. + +## Armazenamento + +| Propriedade | Valor | +| --- | --- | +| Localização | `~/.failproofai/state/semantic/sessions//.json`, onde `` é o perfil do agente em que o prompt foi digitado: `.` para um agente que o FailproofAI conhece (a identidade que as políticas Cloud direcionam), ou apenas `` caso contrário | +| Permissões | arquivo `0600`, diretório `0700`. Cada diretório acima dele, até `~/.failproofai`, é mantido pela mesma regra do diretório de `jev.json`: um que qualquer outro usuário possa **escrever** pode ser renomeado e substituído, então o caminho de leitura remove esses bits de escrita onde possível, e não lê **nada** onde não consegue. Um prompt registrado fica então ausente em vez de falsificado, e nada é liberado | +| Mantido por sessão | os últimos 5 prompts; um prompt idêntico ao anterior o substitui em vez de ocupar um novo slot | +| Janela | prompts com mais de 6 horas são ignorados | +| Tamanho | cada prompt e mensagem do agente é limitado a 6.000 caracteres, mantendo o início e o fim | +| Segredos | removidos com os mesmos padrões das políticas `sanitize-*` antes de qualquer escrita. Um texto com mais de 48.000 caracteres tem seus segredos removidos nos primeiros 28.800 e últimos 19.200 caracteres, e o texto próximo a esses cortes, onde um segredo poderia ter sido dividido, nunca é armazenado | + +Um session ID que contenha qualquer coisa além de letras, dígitos, `.`, `_` e `-`, ou com mais de 128 caracteres, nunca é usado como nome de arquivo, portanto nada é registrado para ele. + +Um arquivo de sessão existe apenas depois que um prompt foi registrado nele. Ele contém apenas prompts e nada mais — sem estado de origem, sem marca de transcrição — e é excluído após ficar silencioso por mais tempo do que a janela de seis horas, na próxima vez que uma nova sessão grava seu primeiro prompt. + +Um prompt é lido de volta apenas para o mesmo perfil de agente e session ID sob o qual foi registrado. Session IDs vêm do agente, então dois perfis podem usar o mesmo; a chave por perfil impede que as palavras de um perfil sejam contadas como requisição de outro. Arquivos anteriores a esse layout (`sessions/.json`) não conseguem indicar qual perfil os escreveu, portanto nunca são lidos e expiram com a janela de seis horas. + +Nada é registrado a menos que um endpoint Jev esteja configurado. No modo Jev do FailproofAI Cloud, nada é registrado para um perfil de agente ao qual nenhuma verificação Cloud Jev está atribuída e nenhuma verificação de pack instalado revisa. + +### A raiz do projeto + +"Dentro do projeto" — o que `read-outside-workspace` e as outras verificações de caminho julgam — significa dentro do projeto em que a sessão estava em sua **primeira chamada revisada**. A raiz é fixada nesse momento e um `cd` posterior nunca a muda; um `cd` ainda altera como um caminho relativo é resolvido. Permitir que ela seguisse o `cd` permitiria que `cd ~/.ssh` em uma chamada tornasse `~/.ssh` o projeto para a próxima. + +O pin é `~/.failproofai/state/semantic/roots/.json`, contendo `{root, at}`: arquivo `0600`, diretório `0700`, e a mesma regra de session ID acima. Arquivos com mais de 7 dias são excluídos quando uma nova sessão fixa sua raiz. Um diretório `roots` em que outros usuários possam escrever é ignorado, e a raiz do diretório ativo é usada em seu lugar. Para refixar uma sessão, exclua seu arquivo. + +## Limitações conhecidas + +- **Um prompt é tão confiável quanto a invocação do hook.** Tudo aqui lê o payload que o harness escreveu no stdin do hook. Um agente que pode executar comandos pode executar o harness sem cabeça (`claude -p` e os outros sete listados acima) ou executar o próprio binário de hook do Failproof AI com um payload que ele criou, e registrar um prompt que ninguém digitou. Essa é a troca aceita descrita no início desta página: ela libera apenas políticas reviewable, nunca uma hard — mas doze das quinze reviewable built-ins são denies, então um prompt forjado pode transformar um bloqueio real em allow para essas doze. +- **A detecção de subagente tem formato Claude.** Um payload que carrega `agent_id` nunca é registrado, em nenhum harness. Esse é o campo que Claude Code, Factory Droid e Devin usariam. O Codex dispara seu evento de prompt dentro de threads de subagente, o Copilot executa sidekicks in-process, o Goose tem uma ferramenta `delegate` e o OpenClaw executa personas — nenhum deles marca o payload de forma que isso reconheça, então um prompt de subagente nesses harnesses é registrado como da própria sessão. O `openclaw.agentId` do OpenClaw **não** é essa marca: o plugin em produção o define em toda execução, incluindo a do proprietário. +- **Schedulers que não carregam marcador.** `schedule_wakeup` e `loop_wakeup` do Claude Code, e os triggers `cron` e `heartbeat` do OpenClaw, são recusados porque esses harnesses indicam isso no payload. O próprio scheduler do Goose (`goose schedule add`) e o `codex exec` do Codex não indicam nada, então uma execução iniciada por eles é registrada como qualquer outra. +- **A última mensagem de um agente pode ser uma mensagem que o agente escolheu.** A transcrição não é autenticada, então um agente que escreve sua própria transcrição pode decidir o que sua "última mensagem" diz. Ela é rotulada como escrita pelo agente e nunca libera nada por si só — mas observe que o caminho v1 do `decide.ts` permite que ela satisfaça a verificação determinística de "o usuário nomeou esse target", então um agente que controla sua transcrição pode fornecer um nome de target que um override precisa. +- **Um prompt que começa com um dos cabeçalhos de máquina da extensão é descartado inteiramente.** Comece um prompt com `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` ou outro cabeçalho de seção do primeiro grupo acima, e nunca escreva um cabeçalho `## My request:`, e nada é registrado para aquele turno — portanto nada é liberado para ele também. Isso é deliberado: essas seções carregam texto que outra pessoa controla (código que você selecionou, um comentário de diff de um revisor, um título de página), e registrar isso como suas palavras é o pior dos fracassos. Cabeçalhos que um desenvolvedor plausivamente digitaria estão no segundo grupo e nunca descartam um prompt por conta própria. +- **O OpenCode não registra nada na prática.** Seu evento `message.updated` não carrega texto no OpenCode atual, e ele também dispara para as sessões filhas que sua ferramenta de tarefa cria, cuja mensagem "user" foi escrita pelo agente pai. +- **`CODEX_HOME` não é respeitado** pela descoberta de rollout em `lib/codex-sessions.ts`. Isso afeta apenas onde um snapshot de mensagem do agente é procurado, nunca se um prompt é registrado. \ No newline at end of file diff --git a/docs/pt-br/reference/jev-providers.mdx b/docs/pt-br/reference/jev-providers.mdx new file mode 100644 index 000000000..bb32884cb --- /dev/null +++ b/docs/pt-br/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Provedores Jev e configuração com chave própria" +description: "Endpoints de provedores, IDs de modelos, configuração e comportamento em caso de falha para revisão Jev ao vivo com sua própria chave." +icon: "key-round" +--- + +Esta é a referência de provedores e configuração para [políticas Jev](/pt-br/policies/jev) com sua própria chave. Políticas de regex verificam strings. Elas não conseguem distinguir `rm -rf build/` que você pediu de `rm -rf ~` que escapou num plano, então bloqueiam demais em um lugar e de menos em outro. O classificador **Jev**, da TypeSafe, lê a chamada em relação ao que você realmente pediu e responde um conjunto de perguntas sim/não sobre ela em uma única requisição rápida. + +Com seu próprio endpoint e chave Jev configurados, o Failproof AI consulta o Jev sobre cada chamada de ferramenta **em paralelo** com as políticas de regex, nunca em substituição a elas: + +- A negação de uma política **rígida** é definitiva. O Jev não pode anulá-la. Toda política é rígida a menos que seja explicitamente marcada como revisável e nomeie as verificações Jev que a cobrem; portanto, uma política customizada, de pacote ou Cloud que não diz nada é rígida, e a proteção automática sempre ativa é sempre rígida. +- A negação de uma política **revisável** pode ser anulada, mas somente quando o Jev foi consultado sobre a preocupação exata que essa política cobre e respondeu "nada aqui" ou "o usuário pediu isso". Uma verificação que constata que a preocupação é real, quando o usuário não pediu a chamada, mantém a negação — mesmo que seu próprio veredicto seja apenas um aviso, pois antes de uma chamada de ferramenta um aviso não para o agente. E quando essa verificação é uma que pode negar (exposição de segredo, exfiltração de credenciais, exclusão destrutiva, …), nada é anulado nessa chamada. +- Um bloqueio ainda pode se tornar um **aviso** quando a chamada é uma etapa da tarefa que você definiu e não vai além disso: o Jev suaviza sua própria negação para um aviso, e esse aviso — indicando o que realmente está errado com a chamada — substitui o bloqueio da política. +- O Jev também pode avisar ou negar por conta própria, para riscos que nenhuma regex descreve. +- Se o Jev não conseguir responder (timeout, limite de taxa, erro do servidor, sem créditos, versão de modelo inesperada), essa chamada recebe o resultado da regex, exatamente como seria sem o Jev. +- O Jev nunca torna uma chamada mais permissiva do que suas políticas sozinhas, a menos que tenha lido a chamada inteira e sido consultado sobre a preocupação exata. Qualquer coisa menos — uma chamada grande demais para enviar completa, uma injeção suspeita — retira as autorizações e mantém todas as negações. + + +Sem uma configuração Jev, nada muda: os hooks executam as políticas de regex exatamente como sempre fizeram. A configuração é todo o opt-in. + + + +Usando o FailproofAI Cloud? Você não precisa de uma chave própria: uma máquina conectada com uma chave que tenha `jev:evaluate` pode usar o Jev no plano da sua organização. Veja [Jev pelo FailproofAI Cloud](/pt-br/reference/jev-cloud). + + +## Antes de começar + +Instale o **failproofai 1.0.8-beta.0 ou posterior** e conecte seus hooks a um [harness compatível](/pt-br/reference/harnesses) na máquina onde seu agente roda. Siga o [quickstart](/pt-br/start/quickstart) se for uma máquina nova, ou [configure a aplicação local](/pt-br/start/setup#enforce-locally) se não usa o Cloud. Verifique a CLI instalada com `failproofai --version`. + +Obtenha uma chave de API de um dos provedores abaixo, ou tenha um endpoint compatível e sua chave prontos. O Jev revisa chamadas de ferramentas nomeadas no gate `PreToolUse` ou `PermissionRequest`. Ele pode emitir seu próprio veredicto, mas anular uma negação de política existente também requer uma política instalada marcada como [revisável](/pt-br/policies/authority). Negações de políticas rígidas permanecem definitivas. + +## Escolha um provedor + +O Jev é acessível por cinco rotas. Traga uma chave para qualquer uma delas. + +| Provedor | `--provider` | Endpoint | Modelo padrão | Notas | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Versão exata fixada. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | As requisições são roteadas exclusivamente para endpoints com retenção zero de dados, sem fallback para outro provedor. Reporta uma versão datada como `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Nomeia o Jev apenas por alias, então a versão que responde é registrada como não verificada. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Requer `--account-id`. Cerca de seis chamadas por segundo por chave foram medidas antes do HTTP 429. | +| Seu próprio endpoint | `custom` | `/systemone` | `jev-1.13.0` | Qualquer endpoint que aceite o corpo de requisição da TypeSafe e reporte qual modelo respondeu. Apenas `https`; `http` simples para host de loopback (`localhost`, `127.0.0.1`, `::1`) é aceito para testes locais. | + + +Com o recurso bring-your-own-key do Vercel, uma requisição com falha é silenciosamente repetida com as credenciais do Vercel. Se você precisa que toda chamada seja cobrada e vista somente pela sua conta TypeSafe, use a TypeSafe diretamente. + + +## Configuração + +Um comando, o endpoint e a chave. Comece no modo `observe` para inspecionar os veredictos do Jev enquanto as políticas existentes continuam decidindo as chamadas: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### A URL determina o provedor + +Você não precisa nomear o provedor: o **host** da URL indica qual é. + +| Host da URL | Provedor | Também requer | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| qualquer outro host | `custom` | — a URL fornecida é a URL base | + +Três consequências disso: + +- **Uma URL que é a própria API do provedor não grava nenhuma substituição.** `--url https://api.typesafe.ai/v1` produz exatamente a mesma configuração que `--provider typesafe` produziria. Forneça um caminho ou host diferente em um provedor conhecido e ele é armazenado como URL base, como `--base-url` armazenaria. +- **`--provider` ainda substitui a inferência**, que é como você acessa um proxy que fala a API de um provedor a partir de um host próprio: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Um `--provider` que contradiz o host é recusado**, sem tentar adivinhar. `--provider openrouter --url https://api.typesafe.ai/v1` não grava nada e explica o motivo: as duas especificações divergem sobre para onde sua chave será enviada. O mesmo par é recusado em `jev setup --base-url` e nas configurações Jev do dashboard. (`--provider custom` não é uma contradição — significa "trate esta URL como ela mesma" — exceto no host do Cloudflare, cujo endpoint por conta não pode ser alcançado por uma rota custom.) + +`--url` é validada exatamente como o `baseUrl` no arquivo de configuração, e recusada com as mesmas mensagens: `https`, ou `http` simples para host de loopback (`localhost`, `127.0.0.1`, `::1`) em qualquer modo. Risco: nada autentica um servidor de loopback, então enquanto ele estiver offline outro processo local pode tomar sua porta e responder; use `https` fora de testes locais. + +### A chave + +Passe-a com `--key-stdin`, ou execute o comando num terminal sem ele e cole a chave no prompt mascarado. De qualquer forma, ela vai direto para o arquivo de configuração e nunca é exibida de volta. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` aceita os mesmos flags e é a forma longa de tudo isso: `setup --provider ` para quando preferir nomear o provedor em vez da URL. + +### `--token` e o que custa + +`--token ` coloca a chave na linha de comando, que é a forma mais rápida de configurar uma máquina e o único modo que deixa a chave em outro lugar além do arquivo de configuração: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Um argumento de linha de comando fica no arquivo de histórico do seu shell depois, e enquanto o comando executa ele está na lista de processos — legível em `/proc` por qualquer coisa rodando como você. O `setup` avisa toda vez que `--token` é usado. Prefira `--key-stdin` em uma máquina compartilhada, em uma sessão gravada, ou em qualquer lugar onde o arquivo de histórico seja sincronizado; rotacione uma chave que você passou dessa forma se isso for importante. + + +`--token`, `--key-stdin` e `--key-from-env` são mutuamente exclusivos: use apenas um. + +Em seguida, envie uma pequena requisição ao vivo para verificar a chave, o endpoint e qual Jev respondeu: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` sai com código 1, e indica isso no título, quando a resposta chega após o timeout (todo hook voltaria ao regex como `timeout`) ou responde incorretamente sua pergunta de verificação. + +Os hooks leem a configuração a cada chamada de ferramenta, então ela se aplica a partir da próxima. Não há nada para reiniciar, com ou sem o daemon. + +## Verifique o que está acontecendo + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` mostra o provedor, endpoint, modelo, modo, o arquivo de configuração e suas permissões, e nunca a chave. Abaixo disso, resume a atividade recente: quantas chamadas o Jev avaliou, quantas vezes voltou ao regex e por quê, sua latência e quais políticas revisáveis ele autorizou. + +## Verifique uma chamada real + +Inicie uma nova sessão no agente com hooks. Peça para ele usar sua ferramenta de leitura de arquivos no `README.md` e reportar o título. Confirme que a sessão contém essa chamada de ferramenta, depois execute `failproofai jev status` novamente: a contagem recente de chamadas avaliadas deve aumentar. Abra **Policies → Activity** no [dashboard local](/pt-br/reference/local-dashboard#review-policy-activity) para inspecionar o veredicto Jev da chamada e o modo. No modo observe, o resultado da política ainda decide a chamada. Uma autorização aparece somente se uma política revisável correspondeu e o Jev autorizou todas as verificações nomeadas; uma leitura comum pode não ter nenhuma política a autorizar. + +## Modo observe + +`enforce` é o padrão. Para observar o Jev sem deixá-lo alterar nenhuma decisão, mude para `observe`: o Jev ainda é consultado e seus veredictos são registrados, mas o resultado da regex é o que é aplicado. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` mantém a configuração — o endpoint e a chave — e para de consultar o Jev: os hooks executam as políticas de regex exatamente como sem uma configuração, e `failproofai jev status` diz "off (switched off)". Volte com `--mode observe` ou `--mode enforce`. + +Executar `setup` novamente para o mesmo provedor mantém a chave armazenada, então uma mudança de modo é uma flag. Trocar de provedor começa do zero e pede a chave do novo provedor. O mesmo acontece com um `--base-url` que move as requisições para um host diferente: uma chave armazenada é enviada somente para o host para o qual foi fornecida, ou para a API própria do seu provedor. + +## O arquivo de configuração + +Tudo fica em um único arquivo, `~/.failproofai/jev.json`, escrito pelo `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Campo | Significado | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` ou `custom` — ou `failproofai`, cuja chave vem da conexão com o FailproofAI Cloud em vez deste arquivo (veja [Jev pelo FailproofAI Cloud](/pt-br/reference/jev-cloud)). | +| `apiKey` | Enviado como `Authorization: Bearer `. | +| `baseUrl` | Obrigatório para `custom`; substitui a base da API do provedor caso contrário. Deve ser `https`. `http` simples para `localhost` é aceito somente com `mode: observe`: nada autentica uma porta local, então enquanto seu proxy estiver inativo qualquer processo na máquina, incluindo o agente sendo julgado, pode responder em seu lugar. | +| `accountId` | Somente Cloudflare: 32 caracteres hexadecimais minúsculos. | +| `model` | Substitui o ID de modelo padrão do provedor. Um ID versionado deve nomear o Jev 1.13. Um valor com aparência de chave de API é recusado (e não repetido de volta), então uma chave colada em `--model` nunca é armazenada nem enviada como modelo. | +| `timeoutMs` | Quanto tempo uma chamada de ferramenta aguarda o Jev antes de usar o resultado da regex. 100–10000, padrão 3000. | +| `mode` | `enforce` (padrão), `observe`, ou `off` (mantém a configuração, não executa o Jev). | + +Três regras protegem o arquivo: + +- **Somente o proprietário.** É escrito com permissões `0600`. Uma cópia que qualquer outro usuário ou grupo possa ler ou escrever é **recusada**, e os hooks voltam ao regex até você executar `chmod 600 ~/.failproofai/jev.json` ou `setup` novamente. O diretório também é verificado: `~/.failproofai` não deve ser **gravável** por ninguém mais, pois quem puder escrever lá pode substituir o arquivo independentemente de suas próprias permissões. O `setup` remove esses bits de escrita se os encontrar. `failproofai jev status` informa quando uma configuração foi recusada e mostra o endpoint que o arquivo nomeia: outra pessoa poderia ter alterado, então verifique se é seu antes de fazer `chmod`. Reexecutar `setup` em tal arquivo carrega a chave armazenada somente para a API própria do provedor; qualquer outro endpoint que ele nomear precisará da chave novamente (`--key-stdin`), ou `--base-url default` para enviar requisições de volta ao provedor. +- **Somente global.** Um repositório não pode ativar o Jev, apontá-lo para outro endpoint ou escolher seu modelo: um `.failproofai/jev.json` dentro de um projeto é ignorado, e o provedor, URL, modelo e ID de conta são lidos somente desse arquivo — nunca do ambiente, que as configurações de agente de um repositório podem definir. (`FAILPROOFAI_HOME` não é uma forma de contornar isso: ele move todo o diretório failproofai, incluindo suas políticas, em vez de redirecionar o Jev sozinho.) +- **Somente a chave pode vir do ambiente.** Se o arquivo não tiver `apiKey`, `FAILPROOFAI_JEV_API_KEY` a fornece para aquela sessão (`setup --key-from-env` escreve tal arquivo). Ela nunca substitui uma chave que o arquivo já possui, e não pode ativar o Jev sem o arquivo. Quando a variável não está definida, o Jev simplesmente fica off para aquele shell: `failproofai jev status` informa isso, sai com código 0 e não altera a configuração (`status --json` reporta `"status": "key-missing"` com `"reason": "no-env-key"`). O daemon `failproofaid` não vê o ambiente do seu shell, então em uma máquina configurada com `failproofai config`, mantenha a chave no arquivo. + +## Qual Jev responde + +Os limiares de decisão do Failproof AI foram calibrados no Jev 1.13, então uma resposta é usada somente quando vem dessa família: `jev-1.13.x`, ou `typesafe/jev-1.13-` do OpenRouter. Quando um provedor nomeia o Jev apenas por alias e não reporta versão (Vercel, e Cloudflare quando não informa), a resposta é usada e registrada como não verificada. Um endpoint `custom` deve reportar o modelo que respondeu; a única exceção é um nome `--model` não versionado que você configurou para ele, que, quando ecoado de volta, é registrado como não verificado da mesma forma. Uma resposta reportando qualquer outra versão, ou uma resposta `custom` sem informar nenhuma, não é usada: essa chamada volta ao regex com o motivo `model-mismatch`. + +## Quando o Jev não consegue responder + +Cada um destes casos volta ao resultado da regex para aquela chamada e é registrado com seu motivo, que `failproofai jev status` totaliza: + +| Motivo | Causa | +| --- | --- | +| `timeout` | Nenhuma resposta dentro de `timeoutMs`. | +| `http-429` | O provedor limitou a taxa da chave. | +| `rate-limited` | O limitador próprio do Failproof AI reteve a chamada antes de enviá-la: 5 requisições por segundo, em rajadas de até 5, e nenhuma por um momento após o provedor responder `429`. Não é o provedor. | +| `http-500`, `http-502`, `http-503`, … | Um erro de servidor no provedor. O status exato é registrado. | +| `out-of-credits` | HTTP 402: a conta do provedor não tem mais créditos. | +| `provider-refused` | HTTP 402 do Cloudflare com mensagem "Model execution failed (Payment error)": o provedor recusou-se a executar o modelo nesta requisição. Geralmente não é cobrança, então recarregar créditos não resolverá. | +| `http-401`, `http-403` | A chave foi recusada. | +| `http-404` | Nada é servido em `/systemone`, então a URL base está errada — `/systemone` é anexado a ela, e todo provedor a serve em sua raiz de versão. `failproofai jev models` mostra o que o endpoint realmente serve. | +| `network` | O endpoint não pôde ser alcançado. | +| `http-301`, `http-302`, `http-307`, `http-308` | O endpoint respondeu com um redirecionamento. Redirecionamentos nunca são seguidos, então a resposta só vem da URL na sua configuração; defina `--base-url` para a URL final. | +| `malformed` | O endpoint respondeu, mas não com uma resposta Jev — um corpo que não é JSON, ou um sem respostas. | +| `cloudflare-error`, `cloudflare-incomplete` | O envelope do Cloudflare reportou uma falha, ou um trabalho que não tinha terminado. | +| `model-mismatch` | Uma versão do Jev diferente de 1.13 respondeu, ou um endpoint `custom` não informou qual modelo respondeu. | +| `request-cut` | **Não é uma falha.** O Jev respondeu; foi mostrado apenas parte da chamada, então sua resposta não autorizou nada. Veja [Quando o Jev respondeu, mas não sobre a chamada inteira](#quando-o-jev-respondeu-mas-não-sobre-a-chamada-inteira). | + +`failproofai jev status` pode mostrar também alguns motivos mais raros, como `upstream-error` (a resposta carregou o próprio erro do provedor) ou `config`, e totaliza qualquer motivo que não consegue nomear como `other`. + +`request-cut` está nesta tabela porque `failproofai jev status` o totaliza junto com os demais, e porque ele também mantém todas as negações. É o único motivo aqui que não diz nada sobre seu provedor: a requisição chegou e o Jev a respondeu. Ao contrário de todas as linhas acima, essa resposta ainda conta — a própria negação ou aviso do Jev se aplica sobre o resultado da regex em vez de ser descartada. Portanto, uma sequência deles significa que chamadas estão chegando ao avaliador grandes demais para enviar completas, não que seu endpoint está com problemas, e recarregar créditos ou mudar a URL não alterará o número. + +## Quando o Jev respondeu, mas não sobre a chamada inteira + +Mais duas situações podem ocorrer, e nenhuma delas é o Jev falhando em responder. Ambas se referem a quanto da chamada, ou da conversa, coube em uma requisição. + +**Parte da própria chamada não coube.** Uma chamada de ferramenta é enviada dentro de um orçamento fixo, e uma excepcionalmente grande — um `Write` muito extenso, um corpo MCP enorme, um comando estendido até o limite — é enviada com o que coube. O Jev ainda responde, e sua resposta ainda conta: sua própria negação ou aviso se aplica normalmente. O que ele não pode fazer é **autorizar** nada, porque um veredicto dado sobre parte de uma chamada não é um veredicto sobre a chamada. Portanto, toda negação de política se mantém, e a chamada é registrada como fallback com o motivo `request-cut`, que `failproofai jev status` totaliza junto com os motivos acima. A regra que isso lhe dá: tornar uma chamada maior pode custar suas autorizações, e nunca pode comprar uma. + +**Uma mensagem não coube.** Um prompt longo que você colou, a última mensagem do agente, ou um prompt que o próprio armazenamento deste avaliador já tinha cortado. **Nada muda**: a chamada é julgada, autorizada e registrada exatamente como qualquer outra, e não é contada como fallback. O tamanho do que você digita nunca decide um veredicto, e um corte não pode fabricar consentimento: quando um prompt chegou já cortado, "você não pediu isso" deixa de ser uma conclusão que pode ser extraída dele, em vez de se tornar uma. + +A linha entre os dois é quem escreveu o texto. A chamada é do agente, e uma regra que permitisse que seu tamanho reduzisse a gravidade seria uma regra que o agente pode usar; seu prompt é seu, e tratar seu tamanho como sinal só punira quem colou uma especificação ou um stack trace. + +## O que sai da máquina + +Para cada chamada de ferramenta que o Jev avalia, uma requisição vai para seu provedor, carregando: + +- a própria chamada de ferramenta, com segredos como chaves de API, tokens bearer e atribuições `KEY=` redigidos; +- os prompts recentes que você digitou, com o texto que o harness do seu agente adicionou removido; +- a última mensagem do agente antes do seu prompt mais recente, rotulada como escrita pelo agente; +- fatos calculados localmente, como se um caminho está dentro do projeto — aquele em que a sessão estava em sua primeira chamada revisada, [fixado para a sessão](/pt-br/reference/jev-intent#the-project-root) — e o branch git atual. + +Vai somente para o endpoint na sua configuração, sob sua chave. + +## Desativar + +```bash +failproofai jev remove +``` + +Isso exclui `~/.failproofai/jev.json`. A partir da próxima chamada de ferramenta, os hooks executam as políticas de regex exatamente como antes. Os armazenamentos por sessão em `~/.failproofai/state/semantic/` (prompts registrados em `sessions/`, raízes de projeto em `roots/`) são mantidos e expiram naturalmente. Para parar de consultar o Jev mas manter a configuração, use `failproofai jev setup --mode off` em vez disso. + +## Referência de comandos + +| Comando | Resultado | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configura em um único comando; o provedor vem do host da URL | +| `failproofai jev --url --token ` | O mesmo, com a chave na linha de comando — seu histórico e a lista de processos a veem | +| `failproofai jev setup --provider --key-stdin` | Grava a configuração a partir de uma chave passada por stdin | +| `failproofai jev setup --provider ` | O mesmo, pedindo a chave em um prompt mascarado | +| `failproofai jev setup --key-from-env` | Não armazena chave; lê `FAILPROOFAI_JEV_API_KEY` por sessão | +| `failproofai jev setup --mode observe` | Muda o modo (`enforce`, `observe` ou `off`), mantendo a chave armazenada | +| `failproofai jev setup --model ` / `--base-url ` | Substitui o modelo ou a base da API; `default` limpa a substituição | +| `failproofai jev setup --timeout-ms ` | Altera o orçamento por chamada | +| `failproofai jev status [--json]` | Configuração, permissões e atividade recente; nunca a chave | +| `failproofai jev test [--json]` | Uma requisição ao vivo: latência e a versão que respondeu | +| `failproofai jev models [--provider ] [--url ] [--json]` | Os IDs de modelo que o `/models` daquele endpoint reporta, marcando o configurado | +| `failproofai jev remove` | Exclui a configuração; Jev fica off | \ No newline at end of file diff --git a/docs/pt-br/reference/jev.mdx b/docs/pt-br/reference/jev.mdx new file mode 100644 index 000000000..3008ddb43 --- /dev/null +++ b/docs/pt-br/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Referência de integração Jev" +description: "Configuração, provedores, chaves, dados de requisição e comportamento em caso de falha para Jev." +icon: "braces" +--- + +O Jev tem dois usos no Failproof AI: + +| Uso | Quando é executado | O que retorna | Comece aqui | +| --- | --- | --- | --- | +| Avaliação de sessão | Após o término de uma sessão | Uma pontuação para uma pergunta de resposta fixa | [Avaliações Jev](/pt-br/evaluations/jev) | +| Revisão de política para chamadas de ferramentas | Antes de uma chamada de ferramenta bloqueada ser executada | Um veredicto junto com as políticas instaladas | [Políticas Jev](/pt-br/policies/jev) | + +## Páginas de referência + +| Tópico | Detalhes | +| --- | --- | +| [Perguntas de avaliação](/pt-br/reference/jev-evaluations) | Critérios booleanos e de pontuação ordenada, resultados, limites e preenchimento retroativo. | +| [Comparação de provedores e configuração de chave própria](/pt-br/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare e endpoints personalizados; inferência de URL, IDs de modelos, `jev.json`, modos e códigos de fallback. | +| [Rota FailproofAI Cloud](/pt-br/reference/jev-cloud) | Permissões de chave de máquina, configuração automática de observação, limites de uso, estado de conexão e tratamento de dados. | + +Os comandos locais da CLI estão listados na [referência da CLI do Failproof AI](/pt-br/reference/failproof-cli). A [referência do painel local](/pt-br/reference/local-dashboard#set-up-jev) descreve as configurações do Jev e a visualização de atividades. \ No newline at end of file diff --git a/docs/pt-br/reference/mcp.mdx b/docs/pt-br/reference/mcp.mdx new file mode 100644 index 000000000..0d04565eb --- /dev/null +++ b/docs/pt-br/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "Servidor MCP" +description: "Conecte Claude, Cursor, Codex ou outro cliente MCP ao Failproof AI Cloud usando suas próprias permissões." +icon: "plug" +--- + +Conecte uma ferramenta de IA ao Failproof AI Cloud e trabalhe com os dados dos seus agentes a partir dela. Sua ferramenta pode consultar sessões e eventos, executar SQL somente leitura, ler dashboards, alertas, issues, auditorias e políticas e, se você tiver a permissão necessária, fazer alterações como criar um alerta ou implantar uma política. + +Cada chamada é executada com **suas próprias** permissões, em **uma** organização que você escolhe ao se conectar. + +Há um único endereço para todos, hospedado ou auto-hospedado: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Conectar um cliente + +Adicione o endereço ao seu cliente. Na primeira vez que uma ferramenta for usada, seu navegador será aberto. Escolha onde está seu Failproof AI Cloud, faça login, selecione uma organização e clique em **Allow**. **Cancel** não conecta nada. + +A página exibe o nome do aplicativo e para onde ele redireciona. Um aplicativo que não é identificado pelo próprio endereço web é marcado como **unverified app**, portanto, prossiga somente se você acabou de iniciá-lo a partir do seu próprio cliente. + + + + No claude.ai ou Claude Desktop, vá em **Settings → Connectors → Add custom connector**. Dê o nome `Failproof AI`, insira o endereço, selecione **Add** e depois **Connect**. + + Nos planos Team e Enterprise, um proprietário adiciona o conector para a organização primeiro. Cada pessoa então conecta sua própria conta. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Em seguida, execute `/mcp` dentro do Claude Code, selecione `failproofai` e escolha **Authenticate**. + + + Adicione isto ao `~/.cursor/mcp.json` ou ao `.cursor/mcp.json` do seu projeto: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + O Cursor exibirá **Needs login** ao lado do servidor. Selecione-o para fazer login. + + + Adicione isto ao `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Em seguida, execute `codex mcp login failproofai`. + + + Qualquer cliente que suporte servidores MCP remotos via Streamable HTTP com OAuth funciona. Forneça o endereço acima. Não há client ID ou secret para configurar. + + + +## Uma organização por conexão + +Uma conexão atua somente na organização que você escolheu. Para usar duas organizações, adicione o servidor duas vezes com nomes diferentes, como `failproofai-acme` e `failproofai-sandbox`, e conecte cada um à sua própria organização. + +Organizações de demonstração não aceitam conexões. Escolha sua própria organização. + +## Permissões + +Uma conexão pode fazer o que você pode fazer na organização, dentro do conjunto abaixo. Ela segue suas permissões atuais: se um administrador conceder mais permissões, a ferramenta as ganha; se ele revogar algo, a ferramenta perde no próximo call. + +| Permissão | Permite que a ferramenta | +| --- | --- | +| `events:read` | Liste eventos, leia o resumo de uma sessão, liste agentes e ambientes | +| `evaluations:read` | Liste sessões, leia e resuma resultados e jobs de avaliação | +| `evaluations:trigger` | Crie avaliações, publique novas versões, ative ou desative, faça backfill e reavalie uma sessão | +| `dashboards:read`, `dashboards:write` | Leia dashboards, ou crie, renomeie e adicione consultas a eles | +| `queries:read`, `queries:write` | Leia consultas salvas, ou salve e edite-as | +| `queries:run` | Execute uma consulta SQL somente leitura e leia o schema de consultas | +| `alerts:read`, `alerts:write` | Leia alertas, ou crie, edite, pause, exclua e teste-os | +| `issues:read` | Leia issues, confirme-as e comente nelas | +| `issues:create` | Abra uma issue em um alerta | +| `issues:close` | Resolva e feche issues | +| `audits:read`, `audits:write` | Leia auditorias, execuções e findings, ou crie e edite auditorias e inicie uma execução | +| `code_fixes:read` | Veja como corrigir uma issue e obtenha seu contexto para que seu próprio agente a corrija | +| `code_fixes:write` | Inicie uma correção no Failproof AI Cloud, que abre um pull request no seu GitHub | +| `policies:read`, `policies:write` | Leia políticas, máquinas e deployments, ou publique, implante e faça rollback de políticas | + +Algumas ferramentas não exigem permissão por não lerem dados da organização: construção de links de sessão e evento e busca nesta documentação. + +Uma ferramenta de IA nunca pode acessar chaves de API, usuários, configurações ou administração da organização, e não pode enviar eventos. + +## Aprovando alterações + +Operações de escrita solicitam confirmação primeiro, se o seu cliente suportar o prompt. Você vê o que será alterado e seleciona **Approve this change** para prosseguir. Se você recusar ou não responder em aproximadamente 4 minutos, nada é alterado. Alguns clientes param de aguardar após um minuto, portanto responda rapidamente. + + + Um cliente que não suporta prompts não é consultado, e uma operação de escrita é executada assim que o cliente faz a chamada. Nesse caso, a confirmação do próprio cliente é a única existente, portanto mantenha-a ativada para ferramentas de escrita. + + +## Aplicativos conectados e revogação + +**Settings → Integrations → MCP** lista seus aplicativos conectados na organização atual, com suas permissões e último uso. **Revoke** desconecta um aplicativo imediatamente. Remover o servidor no seu cliente também revoga a conexão. + +Você pode ter até 5 aplicativos conectados por organização. Conectar o mesmo aplicativo novamente substitui sua conexão anterior. + +## Implantações auto-hospedadas + +Escolha **Self-hosted Failproof AI Cloud** ao conectar e insira o endereço que você usa para fazer login. Sua implantação deve ser acessível via HTTPS público. + +As chamadas de ferramentas e seus resultados passam pelo gateway hospedado do Failproof AI no caminho entre sua ferramenta de IA e sua implantação. O gateway não os armazena. + +## O que acontece com seus dados + +Os resultados vão para a ferramenta de IA que você conectou, e o provedor dessa ferramenta os trata sob seus próprios termos. Para cada chamada de ferramenta, o Failproof AI registra o nome da ferramenta, seu resultado, quanto tempo levou e a organização — nunca os argumentos ou resultados. Consulte a [política de privacidade](https://befailproof.ai/privacy/). + +## Solução de problemas + +| O que você vê | O que fazer | +| --- | --- | +| "Started in another browser" | Conclua o login no navegador que o cliente abriu, com cookies permitidos, e comece novamente pelo cliente | +| Um erro após **Allow** | O link funciona uma única vez e expira após 10 minutos, portanto comece novamente pelo cliente | +| Uma ferramenta esperada está ausente | Você não possui sua permissão nesta organização. Consulte um administrador. Não é necessário reconectar quando obtiver a permissão | +| O cliente continua pedindo para fazer login | A conexão foi revogada, você saiu da organização ou ficou sem uso por 90 dias. Conecte novamente | +| "You have 5 connected apps" | Revogue um em **Settings → Integrations → MCP** e conecte novamente | + +Ainda com problemas? Envie um e-mail para [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/pt-br/reference/otel.mdx b/docs/pt-br/reference/otel.mdx new file mode 100644 index 000000000..f9d9f5243 --- /dev/null +++ b/docs/pt-br/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Ative o OTEL para agentes de codificação, inspecione a entrega e restaure suas configurações anteriores." +icon: "radio" +--- + +`failproofai otel` configura o relatório opcional de OpenTelemetry para o FailproofAI Cloud. Primeiro conecte sua máquina com `failproofai config` e peça a um administrador da organização para habilitar **Settings → OpenTelemetry**. + +A configuração interativa pergunta sobre OpenTelemetry após o campo de chave do Cloud e o seletor de agente. A etapa opcional tem como padrão Não. Escolha Sim para selecionar agentes OTEL; o mesmo código de habilitação é executado após a conexão ser gravada. Pressionar Esc antes de aplicar a configuração não altera nada. Configuração sem interação, uma chave fornecida, modo open-source e manter uma conexão salva não ativam a opção automaticamente. + +## Habilitar um agente + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Os agentes suportados são `claude`, `codex` e `copilot` (VS Code). A configuração do Copilot requer um executável do VS Code ou uma extensão Copilot instalada. Apenas um diretório de configurações remanescente não é suficiente; a configuração ignora o Copilot quando nenhum dos dois é encontrado. + +`--local` envia para o relay local em vez de diretamente para o Cloud. O Copilot usa o relay automaticamente porque suas configurações não podem armazenar o cabeçalho de autenticação. + +O relay escuta apenas na sua máquina. O daemon FailproofAI configurado detecta a mudança em segundos; não é necessário reiniciá-lo. Se outra aplicação ocupar a porta do relay, o status o reporta como desativado e o daemon continua em execução. + + +A captura de texto está ativada por padrão. Adicione `--no-content` para omitir prompts e detalhes de ferramentas. Versões diferentes de agentes podem expor controles de conteúdo distintos; revise o que seu agente exporta antes de usá-lo com dados sensíveis. + + +O Codex exporta apenas logs de conversação, não rastros de tempo de execução internos nem métricas. Um `log_user_prompt = false` explícito na sua configuração do Codex permanece desativado; o enable exibe uma nota quando preserva essa escolha. + +### Escolha um caminho de relatório + +Se o relatório de transcrição estiver ativado para um agente, a configuração pergunta: + +> failproofai já envia sessões do Claude Code para o Cloud. Enviá-las via OTEL? O upload de transcrições do Claude Code será interrompido. + +O padrão é Não. `--yes` aceita a troca sem prompt. Outros agentes e a aplicação de políticas não são afetados. + +A configuração do Codex aguarda o daemon confirmar a mudança do coletor antes de gravar as configurações do exportador. Se a confirmação expirar, a configuração avisa para aguardar antes de iniciar o Codex. + +A config v2 mantém a lista de rastreamento lembrada em `agents.selected` (e o histórico de detecção em `agents.seen`). A preferência de transcrição por agente permanece em `collector.agents..sessions`, a propriedade OTEL em `otel.agents`, e as configurações do relay em `collector.otlp.enabled` / `collector.otlp.port`. Essas chaves separadas mantêm as configurações antigas de OTEL legíveis: a configuração pode alterar a lista de rastreamento sem perder a preferência de transporte ou o estado necessário para restaurar as configurações do agente. + +## Inspecionar a configuração + +```bash +failproofai otel status +``` + +O status mostra cada agente, se suas configurações são gerenciadas pelo FailproofAI, seu destino, o interruptor de ingestão da organização, o estado do relay e o último resultado de upload do relay. + +`unknown` no interruptor da organização significa que o servidor não o forneceu ou não pôde ser alcançado. Não é um erro e não impede a configuração em versões mais antigas do Cloud. + +Se o Cloud ainda não suportar OTEL, o relay retém as exportações rejeitadas em vez de descartá-las. Se a ingestão da organização estiver desativada, `enable` não grava nada e encerra com um erro; peça a um administrador para ativá-la primeiro. + +## Imprimir configuração para uma aplicação + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +A saída é um bloco de variáveis de ambiente shell para um exportador OTLP/HTTP. A saída do Cloud define `OTEL_EXPORTER_OTLP_ENDPOINT` para a base OTLP do Cloud, `https:///otel`, e o exportador adiciona `/v1/`; uma variável por sinal como `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` precisa do endereço completo `https:///otel/v1/logs`. A saída local aponta para o relay, `http://127.0.0.1:`. A saída do Cloud inclui a chave de API configurada; trate-a como um segredo. A saída local omite a chave. Para usar a saída local, primeiro habilite um agente local para que o relay esteja em execução. + +## Restaurar configurações anteriores + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +O disable restaura apenas as configurações gravadas pelo FailproofAI, mantém alterações não relacionadas e restaura a escolha de relatório de transcrição anterior de cada agente. Quando o último agente local gerenciado é desativado, o relay para de aceitar exportações. + +Para o Codex, o disable também registra `collector.agents.codex.sessions_resume_after` (milissegundos desde epoch). Os bytes de rollout existentes são tratados como entregues para que as sessões capturadas com OTEL não sejam enviadas novamente; acréscimos posteriores ainda fluem pelo relatório de transcrição. + +Todos os comandos suportam `--help`. Consulte [OpenTelemetry in Cloud](/pt-br/agenteye/opentelemetry) para exemplos de aplicações e agentes de codificação. \ No newline at end of file diff --git a/docs/pt-br/reference/slack.mdx b/docs/pt-br/reference/slack.mdx new file mode 100644 index 000000000..55bb1dc8b --- /dev/null +++ b/docs/pt-br/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "App para Slack" +description: "Consulte o Assistente Failproof pelo Slack, receba gráficos no thread e aprove alterações com um botão." +icon: "slack" +--- + +Consulte o [Assistente Failproof](/pt-br/sessions/assistant) pelo Slack. Mencione o app em um canal, envie uma mensagem direta ou use `/failproof `. As respostas utilizam **suas próprias** permissões do Failproof AI, os gráficos aparecem no thread e qualquer ação que envolva alterações solicita sua aprovação antes de prosseguir. + +Há um único app oficial. Ele funciona da mesma forma independentemente de o Failproof AI Cloud ser hospedado ou auto-hospedado. + + + As respostas são geradas por modelos de IA e podem ser imprecisas. Verifique informações importantes nos dados de origem vinculados. + + +## Conectar um workspace + +Você precisa da permissão `settings:write` no Failproof AI e, no Slack, ser administrador ou proprietário do workspace, ou ser a pessoa que está adicionando o app. + + + + 1. Acesse **Configurações → Integrações** e selecione **Adicionar ao Slack**. + 2. Aprove o app no Slack. + 3. De volta ao Failproof AI, confirme a conexão do workspace com sua organização. + + + 1. Adicione o app e abra a aba **Início**. + 2. Escolha **Continuar com FailproofAI Cloud** ou **Usar minha própria URL** e insira o endereço que você usa para entrar. + 3. Selecione o botão de continuar, faça login, escolha a organização e confirme. O link funciona apenas uma vez e expira após 10 minutos. + + + +Um workspace se conecta a uma organização, e uma organização a um workspace. + +Não tem uma conta? [Crie uma](https://app.befailproof.ai/login) primeiro e depois conecte. + +## Quem você é no Slack + +Na primeira vez que você pergunta, o app identifica qual membro você é: + +- **Automaticamente, pelo e-mail**, quando você é membro pleno do workspace conectado, seu e-mail do Slack está confirmado e exatamente um membro da organização usa esse e-mail. +- **Caso contrário**, você recebe um botão privado **Vincular sua conta** que abre o Failproof AI e vincula seu usuário do Slack à sua conta. + +## Fazer uma pergunta + +| Onde | Como | +| --- | --- | +| Um canal | Mencione o app. Responda no thread para continuar, sem precisar mencionar novamente | +| Uma mensagem direta | Envie uma mensagem para o app | +| Uma mensagem direta em grupo que o app participa | Mencione-o e responda no thread para continuar | +| Um canal do Slack Connect | Mencione o app | +| Qualquer conversa em que o app participa | `/failproof ` inicia um thread com a resposta | +| `/failproof help` | Veja o que o app pode fazer | +| `/failproof status` | Veja qual organização está conectada e com quem você está vinculado | +| `/failproof link` | Veja a qual conta do Failproof AI você está vinculado | + +Um thread equivale a uma conversa. Colegas podem mencionar o app no mesmo thread e ele responde a cada um com suas próprias permissões. Apenas quem iniciou o thread pode continuar a conversa sem precisar fazer uma menção. + +Quando a resposta envolve dados, o app publica um gráfico ou uma tabela com um link para abri-la no Failproof AI. + +## Aprovar alterações + +Toda alteração que o assistente faz exibe os botões **Aprovar** e **Cancelar** antes de prosseguir, e o Slack solicita uma confirmação adicional antes de **Aprovar**. Apenas a pessoa que fez a pergunta pode responder a esses botões, que expiram após 5 minutos, e a alteração é realizada com as permissões dessa pessoa. + +Pelo Slack, o assistente pode alterar consultas salvas e dashboards, avaliações, alertas, auditorias, problemas e políticas, além de sugerir correções de código — desde que você tenha a permissão correspondente. Ele não pode alterar chaves de API, usuários ou configurações. + +## Pré-visualização de links + +Links do Failproof AI para problemas, sessões e avaliações colados no Slack são expandidos em cards no Failproof AI Cloud hospedado. Um card exibe apenas o que a pessoa que o acionou tem permissão para ver. Links para endereços auto-hospedados não são expandidos, embora os cards nas próprias respostas do assistente ainda apareçam. + +## Canais do Slack Connect + +Pessoas de outro workspace podem usar o app se forem membros da organização, após vincularem suas contas. As respostas ficam visíveis para todos na conversa, incluindo pessoas que não são membros da sua organização — portanto, pergunte apenas onde todos possam ver a resposta. + +O app só responde depois que pelo menos uma pessoa de cada outro workspace no canal estiver vinculada à organização. Até lá, ele informa à pessoa que perguntou o motivo. + +## Permissões solicitadas pelo app + +| Permissão do Slack | Por que | +| --- | --- | +| `app_mentions:read` | Saber quando alguém menciona o app | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Receber mensagens diretas e respostas nos threads do app. O app ignora outras mensagens e nunca lê mensagens anteriores de uma conversa | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Verificar o tipo de conversa em que está, para saber quem pode ver uma resposta | +| `chat:write` | Publicar respostas e botões de aprovação | +| `commands` | Disponibilizar o `/failproof` | +| `files:write` | Publicar gráficos | +| `links:read`, `links:write` | Exibir pré-visualizações de links do Failproof AI colados | +| `users:read`, `users:read.email` | Identificar você com sua conta do Failproof AI e exibir nomes | + +## Desconectar + +Acesse **Configurações → Integrações** e selecione **Desconectar**, use **Desconectar** na aba **Início** do app ou remova o app do Slack. + +Qualquer uma dessas ações exclui a conexão do workspace, o token do bot, as contas vinculadas e os registros de threads. As conversas anteriores do Slack continuam acessíveis no dashboard. A organização pode então conectar qualquer workspace imediatamente. + +## Dados e privacidade + +Perguntas e respostas são salvas como conversas no dashboard da sua organização, associadas à pessoa que iniciou o thread. Os dados do Slack nunca são usados para treinar modelos de IA. Consulte a [política de privacidade](https://befailproof.ai/privacy/) para saber o que o app recebe e por quanto tempo os dados são mantidos. + +## Solução de problemas + +| O que você vê | O que fazer | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | Um administrador do workspace abre a aba **Início** do app e escolhe um | +| "This link expired or was already used." | Escolha seu Cloud novamente na aba **Início** para obter um novo link | +| "This org is already connected to a Slack workspace." | Desconecte-o nas configurações primeiro | +| "That Slack workspace is connected to another org." | Desconecte-o dessa organização primeiro | +| "Link your account to use the assistant." | Selecione o botão e confirme no Failproof AI | +| O app não responde em uma mensagem direta em grupo | Adicione o app ao Slack novamente para conceder suas permissões de grupo. Sua conexão é mantida | +| "I won't post answers from your organization here" | Alguém nesse workspace que seja membro da organização menciona o app e vincula sua conta | + +Ainda com problemas? Envie um e-mail para [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/pt-br/sessions/sentiment.mdx b/docs/pt-br/sessions/sentiment.mdx new file mode 100644 index 000000000..de214d53e --- /dev/null +++ b/docs/pt-br/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Análise de sentimento" +description: "Encontre mensagens de frustração, confusão e correção com as pontuações de sentimento do Jev." +icon: "smile" +--- + +O Jev pontua cada mensagem enviada por uma pessoa aos seus agentes de 0 a 100 para quatro sentimentos — **raiva**, **frustração**, **felicidade** e **confusão** — e três sinais sobre o desempenho do agente: + +- **Corrigindo**: a pessoa diz que o agente errou algo. +- **Resolvido**: a pessoa confirma que o agente resolveu o problema dela. +- **Duvidoso**: a pessoa questiona se a resposta do agente é verdadeira, ou se ele realmente executou a tarefa. + +Use a análise de sentimento para encontrar conversas em que as pessoas estão perdendo a paciência, agentes que precisam de correções frequentes e respostas que funcionam bem. Isso é uma pontuação Jev integrada; você não precisa criar uma avaliação. Para perguntas de resposta fixa, [crie uma avaliação Jev](/pt-br/evaluations/jev). + + + O sentimento fica desativado até que um administrador o ative para a organização. O Jev faz uma solicitação de pontuação por mensagem e recebe essa mensagem junto com a resposta do agente anterior a ela. A pontuação utiliza o orçamento de modelo da sua organização. + + +## Ativar o recurso + +1. Acesse **Administração → Configurações**. +2. Em **Sentimento de entrada humana**, ative a opção e salve. + +As mensagens do último dia são pontuadas primeiro. Depois disso, as novas mensagens são pontuadas em um ou dois minutos após chegarem. + +## Encontrar uma conversa para revisar + +Abra **Observar → Sentimento**. Filtre por período, ambiente, agente ou ID de sessão. O cabeçalho exibe a contagem de mensagens e sessões, mostra quantas mensagens estão **sinalizadas** e indica o principal sinal. Uma mensagem é sinalizada quando uma pontuação de raiva, frustração, correção, confusão ou dúvida atinge 35 de 100. + +![O painel de Sentimento exibindo contagens de mensagens e sessões, mensagens sinalizadas e pontuações Jev ao longo do tempo.](/images/dashboard/sentiment-overview.png) + +Use **Pontuação ao longo do tempo** para comparar sinais. Escolha as pontuações a serem exibidas e selecione um ponto para ver as mensagens daquele intervalo de tempo. A tabela **Por agente** mostra onde um sinal está concentrado. Em **Mensagens**, ordene pela pontuação negativa mais alta ou selecione uma única pontuação. Abra uma mensagem na sua sessão para ler a conversa ao redor antes de decidir o que falhou. + +![A lista de mensagens de Sentimento ordenada pela pontuação negativa mais alta, com um link para cada sessão de origem.](/images/dashboard/sentiment-messages.png) + +## Quais mensagens são pontuadas + +Apenas mensagens escritas por uma pessoa: + +- Mensagens que seus agentes personalizados registram como entrada humana com o SDK. +- Prompts digitados no Claude Code, Codex, OpenCode, pi, Hermes e OpenClaw, quando transcrições de sessão são enviadas (o padrão). Tarefas agendadas, instruções injetadas, transferências entre sub-agentes e outros textos escritos pelo próprio tempo de execução do agente não são pontuados. Também não são pontuadas execuções não interativas como `claude -p`, `codex exec` e `hermes -z`: esses prompts foram escritos por um script, não por uma pessoa. + +A pontuação avalia as próprias palavras da pessoa. Uma instrução curta e direta como "conserta isso" não é contada como raiva, e fazer uma pergunta não é contado como confusão. Um novo pedido não é uma correção, e um simples agradecimento por si só não conta como resolvido. \ No newline at end of file diff --git a/docs/pt-br/start/use-jev.mdx b/docs/pt-br/start/use-jev.mdx new file mode 100644 index 000000000..221540d70 --- /dev/null +++ b/docs/pt-br/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Use Jev" +description: "Configure avaliações Jev para sessões concluídas ou políticas Jev para revisão de chamadas de ferramentas em tempo real." +icon: "sparkles" +--- + +O Jev atua em dois momentos durante a execução de um agente: pontuar uma sessão concluída em relação a respostas conhecidas, ou revisar uma chamada de ferramenta no contexto do que você pediu ao agente para fazer. + + + + Use uma avaliação Jev quando uma sessão concluída puder ser pontuada em relação a uma pergunta com algumas respostas conhecidas, como "O cliente pediu reembolso? Responda sim ou não." Isso ajuda a identificar padrões entre as sessões. + + ## Criar uma avaliação + + No painel Cloud, abra **Analyze → eval authoring → new eval**. Digite uma pergunta de resposta fixa, selecione **draft** e verifique se foi escolhida uma pontuação de classificador. [Teste-a](/pt-br/evaluations/test) em sessões reais e, em seguida, publique-a. + + ![O formulário compartilhado de criação de avaliação, onde você descreve uma pergunta, revisa o rascunho e o publica. Esta captura de tela mostra um rascunho de código; use uma pergunta de resposta fixa para o Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Ler as pontuações + + Após a conclusão de uma nova sessão, abra **Observe → Evaluations** ou use o Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + O CLI lê as pontuações; a criação de uma avaliação Jev atualmente utiliza o painel. Consulte [avaliações Jev](/pt-br/evaluations/jev) para tipos de perguntas e exemplos. + + + Use a revisão de políticas Jev quando uma política de correspondência de strings precisar do contexto da sua solicitação para decidir se uma chamada de ferramenta é segura. Comece no modo **observe** para que você possa inspecionar as respostas do Jev enquanto suas políticas instaladas ainda decidem cada chamada. + + As verificações do Jev vêm de um pacote; a Failproof AI não fornece nenhum. Até que você os instale, o Jev não faz nenhuma pergunta, mesmo quando está configurado: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Configurar o Cloud Jev + + No painel Cloud, abra **Administration → Keys** e crie uma chave com o preset **machine**. Use-a com `failproofai config` conforme mostrado no [guia de início rápido](/pt-br/start/quickstart). Em uma máquina sem uma configuração Jev existente, isso habilita o Cloud Jev no modo observe. Verifique a conexão com: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Usar seu próprio endpoint + + No painel local, abra **Settings → Jev**. Escolha o provedor, cole o token, selecione **observe** e ative o Jev. + + ![O painel de configurações Jev local com um provedor, campo de token e modo observe selecionado.](/images/dashboard/jev-settings.png) + + Ou configure e teste seu endpoint pelo terminal: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Peça a um agente com hook que use sua ferramenta de leitura de arquivos no `README.md`. Confirme que a chamada de ferramenta aparece na sessão e, em seguida, inspecione-a em **Policies → Activity** no painel local. Quando os resultados do observe parecerem corretos, [políticas Jev](/pt-br/policies/jev) explica quando aplicar a execução. Para detalhes sobre provedores e configuração, consulte a [referência de integração](/pt-br/reference/jev). + + \ No newline at end of file diff --git a/docs/reference/cloud-cli.mdx b/docs/reference/cloud-cli.mdx index 9eca539b5..058f288f9 100644 --- a/docs/reference/cloud-cli.mdx +++ b/docs/reference/cloud-cli.mdx @@ -6,6 +6,9 @@ icon: "cloud-cog" Use `fp` to inspect Cloud telemetry, manage cloud-managed enforcement (policies, fleet deployments, guardrail decisions), and manage audits, findings, issues, alerts, keys, users, queries, and settings. Use [`failproofai`](/reference/failproof-cli) for local hooks, policies, capture, and machine enrollment. +You can also author and deploy hosted code, LLM-judge and Jev evaluators, manage +dashboards, inspect sentiment, and use the dashboard assistant from the terminal. + Install the released Cloud CLI as an isolated tool: ```bash @@ -36,21 +39,144 @@ Run `fp COMMAND --help` or `fp COMMAND SUBCOMMAND --help` for terminal help. ## CLI commands +### Author an evaluator + +`fp evaluators` authors definitions; `fp evals` reads results. An enabled managed +instance is required (`fp evaluators instances`). Authoring needs +`evaluations:trigger`; session dry-runs and schema profiling also need `events:read`. + +Code is one restricted Python expression. Save this as `error_free.py`: + +```python +EvalResult(score=Score(1.0 if session.count("error") == 0 else 0.0), reasoning="Error-free session") +``` + +```bash +fp --json evaluators create --key error_free --name "Error free" --code error_free.py --dry-run-on run-001 +fp --json evaluators dry-run --code error_free.py --session run-001 +fp --json evaluators deploy error_free --code error_free.py --version 2 --dry-run-on run-001 +fp --json evaluators list --key error_free --all +``` + +LLM judge: + +```bash +fp --json evaluators create --key relevance --name Relevance --judge --criteria "Grade relevance to the request" --threshold 0.7 +fp --json evaluators deploy relevance --version 2 --judge --criteria "Grade relevance and completeness" --threshold 0.8 +fp --json sessions re-evaluate run-001 +fp --json sessions history run-001 +``` + +Jev binary and graded rubric: + +```bash +fp --json evaluators create --key resolution --name Resolution --jev noul --instructions "Was the request resolved?" --true "Resolved" --false "Unresolved" +fp --json evaluators dry-run --jev noul --instructions "Was the request resolved?" --true "Resolved" --false "Unresolved" --session run-001 +fp --json evaluators deploy resolution --version 2 --jev score --instructions "Grade resolution quality" --level "Unresolved" --level "Partly resolved" --level "Fully resolved" +``` + + +Creation enables the evaluator. Deploy creates a new immutable version, then +disables older enabled versions. A failed follow-up leaves the new version +published: inspect `evaluators list --all` before retrying. +Judge dry-runs are refused by Cloud. Jev dry-runs spend model budget. +Backfill covers code, judge and Jev evaluators and accepts at most 90 days; it queues only sessions an evaluator has not scored yet. Judge and Jev backfills spend model budget, so run `fp evaluators backfill --dry-run` first. +Human output shows per-session dry-run results before creating/deploying. +Failed previews stop the write unless you explicitly pass `--force` after review. + + +AI drafting requires `fp login` and writes a spec accepted by create/deploy: + +```bash +fp --json evaluators draft "Measure error-free sessions with code" --kind code --out evaluator.json +# Review the draft's key, source and condition before enabling it. +fp --json evaluators create --file evaluator.json --dry-run-on run-001 +fp --json evaluators dry-run --file evaluator.json +``` + +| Command | Options / behavior | +| --- | --- | +| `fp evaluators list` | `--key`, `--all` | +| `fp evaluators show KEY[@VERSION]` | Full source/envelope | +| `fp evaluators create` | `--key`, `--name`, `--version`, repeated `--label`, `--condition EXPR\|@file`, one source, repeated `--dry-run-on`, `--disabled`, explicit `--force` for failed previews | +| `fp evaluators deploy KEY` | Same source flags; `--version`, `--backfill 7d` (any kind, 1–90 days), `--force`; numeric versions auto-increment; KEY supplies a missing spec-file `eval_key` | +| `fp evaluators draft "intent"` | Session; `--kind code\|judge\|jev`, `--out` | +| `fp evaluators dry-run` | Source flags or `--file`, repeated `--session` (maximum 10); none = compile only | +| `fp evaluators enable\|disable KEY[@VERSION]` | Toggle | +| `fp evaluators label KEY[@VERSION]` | Repeated `--add`, `--remove` | +| `fp evaluators instances\|schema\|jobs` | Inspect managed fleet/schema/jobs | +| `fp evaluators backfill` | `--from`, `--to`, `--key`, `--dry-run`; code, judge and Jev | + +Code flags are `--code FILE|-`, `--result-kind score|metric|assertion`, +`--timeout S`. Judge flags are `--judge --criteria TEXT`, repeated `--step` and +`--threshold`. Jev flags are `--jev noul --instructions --true --false` or +`--jev score --instructions` with 3–5 distinct `--level` values, worst first. +Judge/Jev require a score; thresholds are 0–1. Binary judge steps are rejected. + +Spec files contain exactly `eval_key`, `display_name`, `eval_version`, +`result_kind`, `labels`, `condition_source`, `evaluator_source`, `timeout_seconds`. +Judge/Jev `evaluator_source` is a JSON envelope string. Do not include row ids, +enabled state, or AI reasoning metadata. `--file` and discrete spec flags are +exclusive; deploy can override the file's version. Output files are never overwritten. + +### New dashboard controls + +All commands accept global `--json`. Unknown-route 404s exit 6 with “not available +on this FailproofAI Cloud yet”. Missing-record 404s also exit 6 but report that the +record was not found. Session-only commands deny key mode before HTTP (exit 2). + +Human commands use summaries and tables. For raw JSON exports, pass global +`--json` or save with `--out FILE`; otherwise session and JSON query exports show +a readable view. CSV exports remain plain CSV for piping. + +| Commands | Options / notes | +| --- | --- | +| `fp dashboards list\|show ID\|create\|update ID\|delete ID` | Create `--name`, `--description`, `--file` definition; update preserves unmentioned fields | +| `fp dashboards tiles ID list\|add\|update TILE\|remove TILE\|layout` | Add `--query ID --chart TYPE --title`; config/geometry or layout via `--file` | +| `fp sessions show\|export\|history\|re-evaluate ID` | Export `--out`; history is evaluation history | +| `fp sessions import FILE...` | Claude Code transcripts, Codex rollouts or event JSONL (`.gz` ok); `--format auto\|failproofai\|claude\|codex`, `--env`, `--dry-run`; needs `events:add` | +| `fp events latency` | `--since` | +| `fp sentiment summary\|messages\|sessions\|session ID` | `--since`; list `--limit`; messages `--session-id` | +| `fp query compose "question"` | Session; `--run` | +| `fp query export [ID]` | Or `--sql`; `--format csv\|json`, `--out` | +| `fp alerts recipients` / `fp alerts issues ID` | Issues can `--create --title --summary` or `--create --file` | +| `fp audits contracts list\|show ID\|create\|update ID` | `--agent-id`, `--body TEXT\|@file`, `--file` JSON; update `--enabled/--disabled` | +| `fp policies author "intent" [--kind regex\|jev\|both]` | Session; drafts a policy from your org's events, never publishes | +| `fp policies backtest [FILE_OR_ID]` | Session; regex replays the module; `jev`/`both` (published, or `--semantic checks.json`) estimate for free, `--run [--sample N]` spends Jev allowance; `--kind`, `--hours`, `--agent-id`, `--env` | +| `fp policies candidacy --issue ID` | Session; could a policy prevent this issue | +| `fp issues facets` | Values the inbox filters can take, with counts | +| `fp agent brief` | Session; `--range 24h\|7d` | +| `fp orgs create --name N [--slug S]` | Session; derives omitted slug, does not switch org | +| `fp roles list\|show NAME\|create\|update NAME\|delete NAME` | Permission sets; create `--name --permission`; update replace `--permission` or merge `--add/--remove`; `--description`, `--file` | +| `fp users delete ID` / `fp users defaults` | Deletion by id | +| `fp usage windows` / `fp plan` / `fp plan claim OFFER` | `usage windows` needs an API key; plan (offers and trial) and claim require a signed-in session | +| `fp settings context-windows list\|set MODEL TOKENS\|delete MODEL` | 0–1000000 tokens | +| `fp otel status\|enable\|disable` | Cloud org ingest switch, not local capture | +| `fp slack status\|disconnect` | Session | + +`fp agent ask` renders artifact SQL as tables/stats through `queries:run`. +Write approvals show the proposed change and prompt on a terminal. Scripts and +`--json` decline unless `--approve` is explicit. Existing JSON shapes stay +unchanged when no artifact is returned. + ### Authentication | Command | Purpose | Options | | --- | --- | --- | -| `fp login` | Sign in with an emailed one-time code and select an organization. | `--email`, `-e`; `--org`; `--force` | +| `fp login` | Sign in from a browser or with an emailed one-time code, and select an organization. `--email` goes straight to the code. | `--email`, `-e`; `--org`; `--force` | | `fp logout` | Revoke and remove the saved user session. | — | | `fp whoami` | Show the current identity, authentication mode, organization, and permissions. | — | | `fp version` | Show the installed CLI version. | — | | `fp help` | Show top-level command help. | — | ```bash +fp login fp login --email you@example.com --org reliability-team fp whoami ``` +On a terminal, `fp login` starts on a link, to sign in with your browser or SSO, and opens it (over SSH or with no display it only shows it, and it works from any device); authorize it and the terminal finishes on its own. That terminal gets your access in all your organizations until the session expires, so only authorize a link you just asked for. If the login started on a different network, you get an email once the session exists, and the page warns you where the deployment can tell. Press **Tab** for a 6-digit code by email instead, and Tab again to go back. `--email`, `--json` and anything without a terminal use the code. + ### Events ```text @@ -159,6 +285,9 @@ fp errors [OPTIONS] | `fp list hooks` | List hook names. | | `fp list tools` | List tool names. | | `fp list error_types` | List error types. | +| `fp list trigger_events` | List hook trigger events. | +| `fp list eval_envs` | List environments with evaluation results. | +| `fp list metric_keys` | List evaluation metric keys. | ### Organizations @@ -291,8 +420,8 @@ Include context during creation when the first run needs it. Creation commits th | Command | Purpose | Options | | --- | --- | --- | -| `fp issues list` | List issues. Archived issues are hidden. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Count open or selected issue states. | `--state` | +| `fp issues list` | List issues. Archived issues are hidden unless `--archived only` or `all`. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id`; filters `--agent-id`, `--env`, `--machine`, `--source`, `--audit-id`, `--assignee` (email, `me`, `unassigned`), `--archived`, `--search`, `--since` | +| `fp issues count` | Count open or selected issue states. | `--state`; `--alert-id`; the same filters as `list` | | `fp issues show INCIDENT_ID` | Show issue details, comments, subscribers, and activity. | — | | `fp issues open` | Open a manual or alert-linked issue. | required `--summary`; optional `--title`, `--alert-id`, `--severity` | | `fp issues ack INCIDENT_ID` | Acknowledge an issue. | — | @@ -329,9 +458,9 @@ Cloud-managed policy versions. **Session-only** — every command here exits `2` | Command | Purpose | Options | | --- | --- | --- | -| `fp policies list` | List policy versions. | `--json` | -| `fp policies show POLICY_ID` | Show one policy, with its source. | — | -| `fp policies publish NAME PATH` | Mint a version from a local `.mjs`. | `--description`; `--no-verify` | +| `fp policies list` | List policy versions, with each one's kind (`regex`, `jev`, `both`) and Jev check names. | `--json` | +| `fp policies show POLICY_ID` | Show one policy, with its source and its Jev checks. | — | +| `fp policies publish NAME [PATH]` | Mint a version: JavaScript (`regex`, the default), Jev checks from a JSON file of declarations (`jev`), or both, where the JavaScript is reviewable by its own checks. | `--kind`; `--source`; `--semantic`; `--description`; `--no-verify` | | `fp policies enable POLICY_ID` | Add it back to every deployment it was removed from, minting a new generation on each. | `--yes`, `-y` | | `fp policies disable POLICY_ID` | Remove it from every deployment carrying it, minting a new generation on each. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | Delete a policy version. | `--yes`, `-y` | @@ -345,11 +474,11 @@ Which machines run which policies. **Session-only**, same reason as above. | Command | Purpose | Options | | --- | --- | --- | | `fp fleet list` | List enrolled machines and their deployment generation. | — | -| `fp fleet show MACHINE_ID` | The policy set a machine currently runs. | — | -| `fp fleet deploy MACHINE_ID` | **Replaces the machine's whole policy set.** Prints the plan and asks only on an interactive terminal without `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet show MACHINE_ID` | The policy set a machine currently runs, the Jev mode FailproofAI Cloud derived from it, and the policy errors it reported. | — | +| `fp fleet deploy MACHINE_ID` | **Replaces the machine's whole policy set.** Prints the plan and asks only on an interactive terminal without `--json`. Jev is on for a machine while a `jev` or `both` policy is deployed to it; trial one with `:observe`. | `--add`; `--remove`; `--set`; `--target POLICY=INTEGRATION[/agt_ID]` (scope one assignment to an integration or one agent; repeat to OR); `--all-agents POLICY` (clear that scope); `--create`; `--yes`, `-y` | | `fp fleet diff MACHINE_ID` | Compare a machine against another deployment. | — | -| `fp fleet history MACHINE_ID` | Past deployments for a machine. | — | -| `fp fleet rollback MACHINE_ID GENERATION` | Reinstate a past generation's policy set, as a new generation. | `--yes`, `-y` | +| `fp fleet history MACHINE_ID` | Past deployments for a machine, with the Jev mode each one had. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Reinstate a past generation's policy set as a new generation. | `--yes`, `-y` | | `fp fleet rename MACHINE_ID` | Give a machine a readable name. | required `--name` | ### Guardrails @@ -365,7 +494,7 @@ What enforcement actually did. **Session-only**, same reason as above. | Flag | Description | | --- | --- | -| `--json` | Emit machine-readable JSON. | +| `--json` | Emit machine-readable JSON. Errors include the failed request's `request_id`. | | `--base-url ` | Use a self-hosted or development dashboard. | | `--org ` | Select an organization for this invocation. | | `--token ` | Override the saved user-session token. | diff --git a/docs/reference/custom-agents-typescript.mdx b/docs/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..0b226e6d2 --- /dev/null +++ b/docs/reference/custom-agents-typescript.mdx @@ -0,0 +1,433 @@ +--- +title: "Custom agents (TypeScript)" +description: "Configuration, the event catalog, the scopes and the framework adapters for @failproofai/sdk." +icon: "square-js" +--- + +What every setting, method and field does for the TypeScript SDK. If you are instrumenting for the first time, start with the guide — this page is for looking things up. + + + + Install, instrument, the event methods, a worked example, and common problems. + + + The same events, the same wire format, the same spool — from Python. + + + +Node 20.9 or newer. ESM and CommonJS. No runtime dependencies. + + + This SDK and the Python one write **the same events into the same spool**. A fleet with Node agents and Python agents produces one set of sessions, not two, and nothing in the dashboard distinguishes them. Pick per service, not per company. + + +## Install + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +The framework adapters ship in the package itself. The frameworks are **optional peer dependencies** — declared so the supported ranges are visible, never installed on your behalf, and imported only when you call `instrument()`. + +## Connect the Failproof daemon + +Identical to the Python SDK: create an `events:add` key under **Admin → Keys**, then [connect the daemon](/start/setup#connect-a-machine-to-cloud) on the agent machine. The SDK writes to disk; the daemon ships. + +## Configuration + +### OpenTelemetry spans (opt in) + +Install OpenTelemetry separately with `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Then add FailproofAI to your provider's processors: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +For an existing provider, keep its other processors in the same list. Providers +that expose `addSpanProcessor` can instead be passed as `{ provider }`. Without +options, setup registers a new provider only if no provider is already registered. +`OtelSpanExporter` can also be used directly with your own processor. + +Exports go through the connected FailproofAI daemon; the SDK sends no network +requests and needs no key or local listener. Ask an admin to enable +[OpenTelemetry ingest](/agenteye/opentelemetry). A bare `instrument()` does not +enable this exporter. `uninstrument("otel")` disables only its own processor. +Your span attributes control content capture; flush your provider before exit. +OpenTelemetry stays an optional application dependency, not a hard SDK dependency. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Option | What it does | +| --- | --- | +| `environment` | The label on every event — `production`, `staging`, `prod-eu`. Defaults to `dev`. | +| `flushInterval` | How often the timer writes to disk, in seconds. Defaults to `0.5`. | +| `baseDir` | Where to write. Defaults to the daemon's spool, which is what you want unless you know otherwise. | + +Nothing is applied unless all of it validates, so a rejected call leaves the SDK exactly as it was rather than with a new `baseDir` and the old interval. + +Set by environment variable instead: + +| Variable | What it does | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Sets `environment` without a code change. A `configure()` option wins over it. | +| `FAILPROOFAI_HOME` | Moves the Failproof AI root that holds the spool. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (default), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` makes instrumentation errors throw instead of being logged. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` makes a framework-compatibility problem throw instead of warning and carrying on. | + + + **No commas in `environment`.** Ingest splits that field on commas to build its filters, and skips any event whose label contains one — so a whole run silently vanishes. Write `prod-eu`, not `prod,eu`. + + `configure({ environment: "prod,eu" })` throws so you find out immediately. `AGENTEYE_ENVIRONMENT` cannot throw — nothing is calling you — so it warns once and falls back to `dev`. + + +Route the SDK's own log lines into your logger with `failproofai.setLogger({ debug, info, warn, error })`. + +## Shutdown + +Buffered events are flushed on `process.on("exit")`. + +A process killed by a signal never reaches that, and Node's default for `SIGTERM` is to terminate without running exit handlers — so a containerised agent loses whatever the last interval had not written. + + + **This SDK will not install a signal handler for you.** Registering one changes your process's behaviour: a listener suppresses Node's default termination, so a library that added one would silently stop Ctrl-C from working. Add your own: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +A short-lived script or a serverless handler should `await failproofai.flush()` before returning — the interval alone does not guarantee delivery. + +## Identity + +Every event belongs to a session and an agent. **The scopes fill both in**, so you rarely pass them: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Passing `sessionId` or `agentId` explicitly still works and wins. With neither bound nor passed, the call throws rather than emitting an event Cloud would quietly discard. + + + Identity rides on `AsyncLocalStorage`. It follows `await`, `.then()`, timers and any callback created inside the scope. It does **not** follow a callback stored during one run and invoked during another, or work handed across a `worker_threads` boundary — wrap those in `failproofai.propagate()` or their events land unattached. + + +### Scopes + +| Scope | Emits | Returns | +| --- | --- | --- | +| `session(body)` | nothing — identity only | whatever `body` returns | +| `agent(id, options?, body)` | `agent_start`, then `agent_end` | whatever `body` returns | +| `toolCall(name, options?, body)` | `tool_use`, then `tool_result` | whatever `body` returns | + +A synchronous body stays synchronous: `agent("x", () => 1)` returns `1`, not a promise. + +`toolCall` records the body's resolved value as the tool's `output`, unless you assign `call.output` yourself. + + + +| What happened | Events | `outcome` | +| --- | --- | --- | +| the block returned | `agent_end` | `"success"`, or your `outcome` | +| the block threw | `error`, then `agent_end` | `"failed"` | +| an `AbortError` | `agent_end` only | `"cancelled"` | + +The error is always re-thrown. + +A tool failure is recorded on the leaf — `tool_result` with an `error` string — and emits **no** run-level `error` event. One the agent loop catches is not a run failure, and one that propagates is reported exactly once, by the enclosing `agent()`. + + + + + +When the work is not a single function — a scope opened in a constructor and closed in a teardown, or one that straddles existing control flow: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +Both forms emit byte-identical events. Prefer the callback form: it runs inside `AsyncLocalStorage.run()`, so there is nothing to unwind and the whole class of "opened here, closed over there" bugs is unreachable. + +A `using` block that catches its own failure reports it with `span.fail(error)` — the disposer has no exception channel of its own. + + + +## Event catalog + +The same fifteen methods as the Python SDK, in camelCase. Most come in **pairs** — you call the opener, then the closer, and the SDK times the gap. + +| | Opens | Closes | +| --- | --- | --- | +| **Agents** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Models** | `modelRequest` | `modelResponse` | +| **Tools** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Humans** | `humanWait` | `humanInput` | + +Three stand alone: `error`, `humanPause`, `humanInterrupt`. + + + +Every method also takes `sessionId` and `agentId`, which the scopes fill in for you. Anything omitted is dropped rather than sent as JSON `null`. + +| Method | Required | Optional | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Any other key you add becomes a custom payload field. Namespace anything framework-specific `fw_*`; a name that collides with a declared field is refused rather than silently overwriting a promoted column. + + + + + **`duration_ms` is computed, not accepted.** The four closing methods time the gap from their opener and refuse a caller-supplied `duration_ms` — a reported duration is unfalsifiable. + + Pairs are matched on the **session** and the id, never on the agent. A tool opened under `planner` and closed under `worker` still pairs, which is what nested multi-agent runs actually do. + + +## Framework adapters + +```ts +await failproofai.instrument(); // whatever it can find +await failproofai.instrument("langchain"); // exactly one +failproofai.uninstrument(); // put everything back +``` + +| Framework | Supported | How it attaches | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, so every `invoke`/`stream`/`batch` is covered without passing `callbacks:` anywhere — or pass `langchainHandler()` yourself and patch nothing. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` at the call site, or `instrument("ai")` for the whole process on `ai` 7 (on 4–6 that is opt-in — see below). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, the agent's model and tool resolution, and the workflow run/step engine. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (subscribed) plus `AgentWorkflow.runStream`, for workflow runs and their steps. | + +Every range is tested against real framework releases, at both ends, as an ES module and as CommonJS, on every CI run. + +The mapping is the Python SDK's, so the same program draws the same tree in either language. A construct is an **agent** only if it owns an LLM decision loop — a graph or chain run, an AI SDK `generateText`/`streamText` call, a Mastra agent, a LlamaIndex agent run. A LangGraph node or a workflow step is a **hook** (`hook_triggered`/`hook_completed`), never a nested agent. Model calls are `model_request`/`model_response` pairs with token counts; tool calls carry the model's own tool call id. A failure is recorded once, on the event it happened in. + +An adapter that fails to install is logged and skipped; the others still install, because a broken LlamaIndex should not cost you LangGraph. + + + `instrument()` with no argument detects a framework by whether it **resolves**, not by whether it is already imported — Node exposes no equivalent of Python's `sys.modules` for ES modules. A framework you have installed but do not use will be imported and patched. Name the one you want if that matters. + + + + Most of these frameworks ship an ES-module build and a CommonJS build, which Node loads as two unrelated copies. The adapters patch the copy your application loads (and the CommonJS copy too if something already `require`d it), so both module systems work. A framework **bundled into your own output** by esbuild or webpack is out of reach — use the call-site helpers there: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain without patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +The handler works with or without `instrument()` and never double-records. `instrument("langchain")` takes `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` and `captureLimit`, as the Python adapter does; `metadata: { failproofai_sdk_session_id }` on a call picks the session for that invocation. + +### Vercel AI SDK + +The AI SDK exports plain functions from an ES module, and an ES module namespace is immutable by specification — there is nowhere to patch. It uses the extension points the SDK itself documents: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // on ai 7, `telemetry: telemetry({ … })` — the same object, the new name +}); +``` + +That is the complete integration: an agent span, a model request/response pair per step with token counts, and every tool call. One call site works on every major — `ai` 4–6 read the tracer it carries, `ai` 7 the telemetry integration. + +`instrument("ai")` does the same process-wide **on `ai` 7**: every call, through the AI SDK's global telemetry-integration list, which is additive and takes nothing from anybody else's. + +**On `ai` 4–6, `instrument("ai")` records nothing by itself, and logs one warning saying so.** The only process-wide hook those majors have is the global OpenTelemetry tracer provider — a single slot OpenTelemetry refuses to hand over once taken. Registering ours would silently refuse your own `NodeSDK.start()` later in startup and send your http/database spans to a tracer that exports nothing. Use `telemetry()` at the call site or `wrapModel` there. If the process runs no OpenTelemetry of its own, opt in with `instrument("ai", { registerGlobalTracer: true })`: it then records every call that passes `experimental_telemetry: { isEnabled: true }`, and only takes the slot if it is still empty. `registerGlobalTracer: false` keeps the default and silences the warning. + +If you would rather wrap the model once, `wrapModel` sees model calls only, because tool calls happen above the model layer. A wrapped model called with nothing around it is recorded as its own run. A streamed call closes however the stream stops — `stop_reason: "cancelled"` when the consumer cancels it, `"error"` with the error when it fails part-way: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Using both is fine: the middleware notices the call is already being recorded and defers, so each call is recorded once. + +`functionId` names the agent span. Keep it low-cardinality — it lands in `agent_id`, the primary dashboard facet. + +### Next.js + +`next build` bundles your server's dependencies by default, and a framework bundled into the build is a copy `instrument()` cannot reach. Wrap the config once and call `instrument()` from Next's startup hook: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` adds LangChain, Mastra, LlamaIndex and the SDK itself to `serverExternalPackages`, keeping your own list. Without it, `instrument()` warns once per framework it cannot reach rather than failing silently; if you list the packages yourself, set `FAILPROOFAI_NEXT_EXTERNALS=1`. The Vercel AI SDK and the call-site helpers work either way. An Edge route gets a no-op build: importing the SDK is safe and records nothing. + +### Token counts on streamed calls + +OpenAI-compatible APIs only report usage on a stream when the client asks. LangChain and the Vercel AI SDK ask; for LlamaIndex pass `additionalChatOptions: { stream_options: { include_usage: true } }` to its `OpenAI` LLM, and for Mastra build the model with usage enabled (for example `createOpenAICompatible({ includeUsage: true })`). Otherwise streamed model calls carry no token counts. + +### Runtimes + +Node ≥ 20.9, Bun and Deno — every framework, as an ES module and as CommonJS, is tested on each against Node's trace. The SDK runs beside the `failproofaid` daemon, which ships what it writes. + +## Your own agent — no framework + +For an agent loop you wrote yourself, or a framework without an adapter. You emit the events with the same API the adapters use underneath, so the trace has the same shape and quality. + +You don't need to know how the agent is organised. Every hand-built agent already has three places, whatever its functions are called, and those three are the whole integration: + +| Where | What to add | Emits | +| --- | --- | --- | +| Where **one run** starts and ends | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| The **one function that calls the model** | `event.modelRequest` before, `event.modelResponse` after — both halves, even on failure | one pair per model turn | +| The **one function that runs tools** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +Identity is ambient: everything inside `agent()` lands on that run's session without taking an id, and nothing else in the program changes — including whatever the agent already writes to its own database. + +- **A service or a worker:** pass your own request or job id as `sessionId`, so a session on the dashboard and the record in your own logs or database are the same string. +- **Sub-agents:** nest `agent()` calls. The inner one joins the session with the outer as its `parent_id`. +- **Emit the pairs.** A `modelRequest` with no `modelResponse` is a span the dashboard shows as running forever — hence the `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) in the repository is the complete, runnable version: a real OpenAI tool loop instrumented exactly like this, run in CI on every change as an ES module and as CommonJS. + +## Evaluations + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +See the [Evaluator SDK reference](/reference/evaluator-sdk) for the protocol, the worker settings and the result types. + + + **An evaluation must yield.** A synchronous function that never returns blocks the one thread Node has, and no timeout can fire while it does. Write `async` evaluations. + + +## What it will not do to your process + +| | | +| --- | --- | +| **Block your agent loop** | Events go into an in-memory queue; a timer writes them. The timer is `unref`'d, so importing this package never stops a script exiting. | +| **Grow without bound** | The queue is capped by count *and* by measured bytes. Past either, the oldest events are discarded and a warning says so — a telemetry outage must not become an OOM kill. | +| **Take the process down** | One unencodable event is dropped alone, not the batch around it. A throwing getter, a circular reference, a `BigInt`, a lone surrogate: each is handled rather than propagated. | +| **Leave a half-written batch** | Content is `fsync`ed before an atomic rename, the directory is `fsync`ed after, and a failed write cleans up its temporary file. | +| **Leave transcripts readable** | Batches are `0600` inside a `0700` directory. They carry goals, prompts, tool arguments and tool output. | +| **Ship credentials** | API keys, tokens, JWTs, bearer headers and secret-shaped assignments are redacted before the bytes reach disk. The daemon redacts again before upload. | diff --git a/docs/reference/custom-agents.mdx b/docs/reference/custom-agents.mdx index ab9b7245d..b0d0147cd 100644 --- a/docs/reference/custom-agents.mdx +++ b/docs/reference/custom-agents.mdx @@ -10,12 +10,16 @@ What every setting, method and field does. If you are instrumenting for the firs Install, instrument, the event methods, a worked example, and common problems. - - LangChain, CrewAI, LlamaIndex and Pydantic AI instrument themselves with one call. + + The same events, the same wire format, the same spool — from Node. -Python 3.10 or newer. No runtime dependencies. +Python 3.11 or newer. No runtime dependencies. Using a framework? [LangChain, CrewAI, LlamaIndex and Pydantic AI](/start/integrations) instrument themselves with one call. + + + There is a **TypeScript SDK** too, and the two write the same events into the same spool. A fleet with Node agents and Python agents produces one set of sessions, not two. Pick per service, not per company. + ## Install @@ -54,6 +58,35 @@ The package is installed as `failproofai-sdk` and imported in Python as `failpro ## Configuration +### OpenTelemetry spans (opt in) + +Install `opentelemetry-sdk` separately, then attach the optional exporter: + +```python +import failproofai_sdk +from opentelemetry.sdk.trace import TracerProvider + +provider = TracerProvider() +failproofai_sdk.instrument("otel", provider=provider) +with provider.get_tracer("my-agent").start_as_current_span( + "agent", attributes={"gen_ai.operation.name": "invoke_agent"} +): + pass +provider.force_flush() +``` + +Setup uses your registered provider if you omit `provider`, creating one only +when none is registered. You can also pass `failproofai_sdk.OtelSpanExporter()` +directly to your own span processor. Other exporters remain unchanged. + +The connected FailproofAI daemon delivers exports; the SDK needs no network +setup, key, or local listener. An admin must enable +[OpenTelemetry ingest](/agenteye/opentelemetry). A bare `instrument()` never +enables OTEL. `uninstrument("otel")` disables only its own processor. +Your instrumentation controls content capture. Flush the provider before exit. +The SDK still declares zero hard runtime dependencies and imports OpenTelemetry +only when requested. + ```python import failproofai_sdk diff --git a/docs/reference/failproof-cli.mdx b/docs/reference/failproof-cli.mdx index c4a234cb9..d173fafdf 100644 --- a/docs/reference/failproof-cli.mdx +++ b/docs/reference/failproof-cli.mdx @@ -25,7 +25,9 @@ failproofai policies add FailproofAI/policies failproofai config --status ``` -`failproofai config` is the whole of setup: it installs the `failproofaid` service (root once, via `sudo -n` — never an interactive password prompt), wires hooks into every agent CLI it finds, and connects to Cloud when a key is available. With no terminal — CI, a container, an agent driving it — it applies rather than asking, and exits 1 if anything it was asked to do did not happen. +`failproofai config` is the whole of setup: it installs the `failproofaid` service (root once — in a terminal it asks for your sudo password, and asks again if that expired before setup finished; with no terminal it uses `sudo -n` and never prompts), wires hooks into every agent CLI it finds, and connects to Cloud. With no terminal — CI, a container, an agent driving it — it applies rather than asking, and exits 1 if anything it was asked to do did not happen. + +In a terminal, the **Connect to cloud** step on a machine that is not connected yet starts **logging in to FailproofAI Cloud** straight away; press Tab for the other options, **Paste an API key** or **Use open source**. Logging in opens a link — or prints it over SSH or with no display, to open on any device — where you sign up or sign in, pick or create an org, and authorize the machine; the terminal picks up the approval by itself and shows who approved it and for which org. The key is minted only when setup finishes, after the daemon is installed. On a machine that is already connected with a working key, the step is a menu with **Keep current connection** first, so re-running setup never opens a browser by itself; a saved key that no longer works starts logging in again straight away, and says why. Logging in again makes a new key and leaves the old one working until you revoke it. A Cloud from before browser login says so and offers the other options. It chooses **no** policies. That is the second command's job, and without it a freshly configured machine enforces nothing but the always-on guard. @@ -39,8 +41,8 @@ Run `failproofai` without arguments to open the local policy dashboard. | Command | Outcome | | --- | --- | -| `failproofai config` | Set the machine up: agents, daemon, and Cloud when a key is present | -| `failproofai config --token ` | Set up and connect in one pass, asking nothing | +| `failproofai config` | Set the machine up: agents, daemon, and Cloud — log in through the browser, paste a key, or stay open source. Every agent on the machine also gets a small `failproofai` skill that points it at the [FailproofAI skills](https://github.com/FailproofAI/skills) online | +| `failproofai config --token ` | Set up and connect in one pass, asking nothing. A key that carries `jev:evaluate` also turns on [Jev through FailproofAI Cloud](/reference/jev-cloud) in observe mode, unless a `jev.json` already exists or `--no-transcripts` is given | | `failproofai config --connect ` | Enrol a machine that is **already** set up — no daemon, no hooks | | `failproofai config --status` | Show connection, daemon, delivery, and pause state | | `failproofai policies` | List builtin, custom, convention, pack, and Cloud-managed policies | @@ -51,20 +53,29 @@ Run `failproofai` without arguments to open the local policy dashboard. | `failproofai policies show /` | What a pack carries, read from its manifest, before you take it | | `failproofai policies show / --releases` | Every version it has published, and which one is here | | `failproofai policies add ` | Install a policy pack from a GitHub release; no tag takes the newest and pins it | -| `failproofai publish` | Ship your own policies as a pack; `--init` writes one to start from | +| `failproofai publish` | Ship your own policies as a pack; `--init` writes one to start from, and `--min-cli-version ` sets the oldest CLI that may install it ([Jev checks in a pack](/policies/publish-a-pack#jev-checks-in-a-pack)) | | `failproofai policies remove ` | Uninstall a pack | | `failproofai audit` | Scan local agent history and open the local audit view | | `failproofai audit --schedule [days] --email
` | Schedule recurring local scans and email their findings | | `failproofai audit --status` | Show the report address, interval, and next scheduled scan | | `failproofai audit --no-schedule` | Stop recurring scans without deleting audit history | | `failproofai harness list` | List extra capture paths | +| `failproofai otel status` | Inspect optional [OpenTelemetry reporting](/reference/otel) | +| `failproofai jev --url --key-stdin` | Set Jev up in one step; the provider is taken from the URL's host | +| `failproofai jev setup --provider --key-stdin` | Let [Jev](/reference/jev-providers) judge tool calls through your own endpoint and key | +| `failproofai jev setup --provider failproofai` | Let Jev judge tool calls [through FailproofAI Cloud](/reference/jev-cloud), with this machine's Cloud key | +| `failproofai jev setup --mode ` | Switch Jev's mode: `enforce`, `observe`, or `off` (keeps the config, stops asking Jev) | +| `failproofai jev status` | Show the Jev config, its permissions and recent fallbacks; never the key | +| `failproofai jev test` | Send one live Jev request and show its latency and version; exits 1 when the answer is late for hooks or wrong | +| `failproofai jev models` | List the model ids `GET /models` says an endpoint serves | +| `failproofai jev remove` | Turn Jev off; hooks run the regex policies exactly as before | | `failproofai flush --wait` | Deliver the current event spool | | `failproofai backfill --since 30d` | Re-read previously passed history | | `failproofai config --pause [duration]` | Pause one local session for 30 minutes by default, up to 8 hours | | `failproofai config --resume` | Resume one paused local session; add `--all` to clear all pauses | | `failproofai update` | Finish package migrations and update the daemon | | `failproofai migrate --dry-run` | Preview or run pending home-layout migrations | -| `failproofai uninstall` | Remove hooks and the daemon before removing the package | +| `failproofai uninstall` | Remove hooks, the `failproofai` skill and the daemon before removing the package | | `failproofai --version` | Print the installed package version | | `failproofai --help` | Show commands and global usage | @@ -77,8 +88,8 @@ Run `failproofai` without arguments to open the local policy dashboard. | `--connect ` | Enrol only, on a machine already set up. Skips the daemon and every hook | | `--machine-id ` | Set the stable machine ID | | `--machine-label ` | Rename a machine that is **already connected**. On its own it never runs setup, so give it after `failproofai config`, not during | -| `--no-transcripts` | Send decisions without transcript content | -| `--disconnect` | Stop Cloud policy pulls and event delivery | +| `--no-transcripts` | Send decisions without transcript content, and do not turn on Cloud Jev, which would send each checked tool call and the recent prompt; a `jev.json` left running Jev through FailproofAI Cloud is removed | +| `--disconnect` | Stop Cloud policy pulls and event delivery. Also removes the Cloud Jev key and a `jev.json` that names FailproofAI Cloud; your own Jev setup is left in place | | `--status` | Show current machine state | | `--pause [duration]` | Pause the newest session in the current directory; accepts seconds, minutes, or hours and defaults to 30 minutes | | `--resume` | End a matching pause early | @@ -108,7 +119,7 @@ Local pauses suspend builtin, custom, convention, and pack policies for one sess | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` should be run after `npm install -g failproofai@latest`; it performs home-layout migrations, installs the matching daemon binary, and restarts the service. `--no-daemon` performs only the layout migration. +`failproofai update` should be run after `npm install -g failproofai@latest`; it performs home-layout migrations, installs the matching daemon binary, and restarts the service. It then moves every Hermes profile that already uses FailproofAI to the linked native plugin and prints one line per profile. `--no-daemon` skips the daemon step. `update` exits non-zero when the daemon could not be replaced, a migration failed, or a Hermes profile could not be migrated (for example because the running daemon cannot serve the native plugin, in which case its shell hooks are left in place). ## Harness paths @@ -174,5 +185,5 @@ npm rm -g failproofai Run `failproofai --help` for version-specific details. - Run `failproofai uninstall` before `npm rm -g failproofai`; npm does not remove installed agent hooks or the daemon service. + Run `failproofai uninstall` before `npm rm -g failproofai`; npm does not remove installed agent hooks, the `failproofai` skill or the daemon service. diff --git a/docs/reference/harnesses.mdx b/docs/reference/harnesses.mdx index 8d52d8952..72d275b0c 100644 --- a/docs/reference/harnesses.mdx +++ b/docs/reference/harnesses.mdx @@ -34,7 +34,7 @@ Each integration normalizes its native hook event names, tool names, and tool-in | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` and session events are observational. | | OpenCode | `PreToolUse` | Post-tool and lifecycle events are observational; current stop handling is guidance for a later turn rather than a verified gate. | | Pi | `PreToolUse`, `UserPromptSubmit` | Post-tool and lifecycle events are observational; stop guidance applies to a later turn. | -| Hermes | `PreToolUse` | A native plugin delivers `instruct()` as one bounded, model-visible interruption before permitting a later API iteration. Post-tool, session, and subagent-stop verdicts are not gates. | +| Hermes | `PreToolUse` | `deny()` blocks. `instruct()` does not stop the call: it runs, and the guidance is placed at the start of its result. Post-tool, session, and subagent-stop verdicts are not gates. | | OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-tool, session, subagent-stop, and compaction events are observational. | | Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-tool and subagent-stop verdicts are observational. | | Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, conditional `PermissionRequest` | Permission hooks do not run in every permission mode; post-tool and session events are observational. | @@ -46,16 +46,65 @@ Capabilities are version-sensitive. Re-test after upgrading an agent CLI, especi ### Hermes native plugin Hermes is integrated through a profile-local native plugin rather than a shell -command. Installation copies the plugin into every default and named Hermes -profile, enables it in that profile's `config.yaml`, and migrates only legacy -FailproofAI shell-hook entries. This avoids a process spawn on each hook and -lets `instruct()` reach the model through Hermes' native blocked-tool result. - -The first matching instruction blocks the pending call. The same API request -stays blocked; a later model iteration may retry. A persistent, profile-scoped -ledger and a per-turn cap prevent an advisory instruction from becoming an -unbounded loop. `deny()` remains a hard block. Run `failproofai config --status` -to detect a disabled, incomplete, duplicated, or newly unconfigured profile. +command. Installation links every default and named Hermes profile's +`plugins/failproofai` to the plugin shipped in the npm package (a copy where a +symlink cannot be created), enables it in that profile's `config.yaml`, and +migrates only legacy FailproofAI shell-hook entries. Because the plugin is +linked, `npm install -g failproofai@latest` updates it with no reinstall. This +avoids a process spawn on each hook. The plugin supports Hermes 0.20.0 and +later. + +Legacy shell hooks (installed by 1.0.5 and earlier) do **not** check Hermes +cron jobs: each cron run builds its own hook scope, which the native plugin +joins and `config.yaml` shell hooks do not. `failproofai update` migrates every +profile that already uses FailproofAI to the linked plugin. If the running +daemon cannot serve the plugin, `update` leaves the shell hooks in place and +exits non-zero; run `failproofai config` to update the daemon, then +`failproofai update` again. Cron jobs load the plugin on their next run; restart +running gateways and interactive sessions to load it there. + +On Hermes, `deny()` blocks the call and `instruct()` does not: the call runs, +and the guidance is placed at the start of its result — as the first key, +`failproof_policy_reminder`, of a JSON result, or as a leading +`[FailproofAI policy reminder (...)]` line — so the model reads it with the +output, and scripts that parse the result keep working. A policy's reminder is +shown once per turn, and kept short on a large result. Use `deny()` when an +action must not happen at all: `instruct()` no longer stops the action first. +Tool calls made from an `execute_code` script put their reminder on the +`execute_code` result the model reads; the script's own copy of the result is +left untouched. The model is told never to quote a reminder in its replies. + +A Hermes build without plugin middleware falls back to holding the matching +call once with "FailproofAI policy guidance"; the next model response may +repeat it, or do the same work with another tool, without being held again. + +Tool names are matched across Hermes versions: `process_manage`, +`cronjob_manage`, and `todo_list` (Hermes 0.21) are treated like `process`, +`cronjob`, and `todo` (Hermes 0.20). Each time Hermes loads the plugin it writes +`heartbeat.json` in the profile's +`plugin-data/agent-plugin-failproofai-5296f299/` directory, recording the +Hermes version, the plugin's path and version, and the hooks Hermes accepted. +Run `failproofai config --status` to detect a disabled, incomplete, duplicated, +or newly unconfigured profile, or one still on legacy shell hooks (reported as +"Hermes cron jobs are not checked"). + +### OpenClaw plugin + +OpenClaw loads FailproofAI as an in-process gateway plugin, registered in every +profile's `openclaw.json`. Like the Hermes plugin, it asks the local +`failproofaid` daemon for each verdict over its socket, so it needs a running +daemon: installation refuses without one, and if the daemon cannot answer, tool +calls and prompts are blocked and the reason is written to the gateway log. +After `npm install -g failproofai@latest`, restart the OpenClaw gateway so it +loads the updated plugin. + +### Codex hook trust + +Codex 0.129 and later runs a hook from `~/.codex/hooks.json` only after you approve it in interactive `codex` ("Review hooks"); until then, every Codex session — headless `codex exec` included — skips it. Hooks in Codex's system config, `/etc/codex/config.toml` on Linux and macOS, run without that approval. + +So when `failproofai config` (or `policies --install --cli codex` at user scope) can use sudo, it writes the Codex hooks into `/etc/codex/config.toml`, between `# >>> failproofai managed hooks >>>` and `# <<< failproofai managed hooks <<<`, and leaves the rest of that file as it was. The file applies to every account on the machine. `failproofai uninstall` and unticking Codex in `failproofai config` take the block out again. + +Without sudo, and on Windows, the hooks stay in `~/.codex/hooks.json`. `failproofai config` and `failproofai config --status` then do not count Codex as enforcing until the hooks are approved, and say how to fix it: re-run `failproofai config` and allow sudo, or open `codex` once and approve the hooks. ## Install capture and policy hooks diff --git a/docs/reference/http-api.mdx b/docs/reference/http-api.mdx index ea88e20eb..cbd60fc8e 100644 --- a/docs/reference/http-api.mdx +++ b/docs/reference/http-api.mdx @@ -69,6 +69,21 @@ The current specification has complete route, method, parameter, permission, and Use `Content-Type: application/json` for JSON writes. Treat `401` as missing or invalid authentication, `403` as a valid identity without the required permission, `404` as a missing or organization-inaccessible resource, `409` as a state conflict, and `422` as an invalid field or permission value. Error responses include a human-readable message; permission failures also name the required grant. +Event ingestion uses newline-delimited JSON: one complete object per line. Check +both `accepted` and `skipped` in a successful response. Retry the entire batch +after a network failure or an HTTP 408, 429, or 5xx response; replaying the same +events is safe. Historical batches can span many months. If ingestion returns `422` with +`error: "event_too_large"`, reduce the offending event's payload before retrying. +Splitting a batch into smaller requests does not shrink an individual event. +For file imports, reuse the original `existing_before` cutoff on retries so a +partially stored session can finish. + +## Request IDs + +Every response carries an `X-Request-Id` header, and every JSON error body includes the same value as `request_id`. Quote it when you contact support: it identifies that one request. + +You can send your own `X-Request-Id` to correlate a request with your own logs. Use 32 lowercase hexadecimal characters, such as a UUID v4 with the dashes removed. Any other value is replaced with a new ID, which is returned in the response. + Policy enforcement deployment is intentionally managed outside the ordinary public `/v1` surface. Use the supported Cloud deployment workflow. diff --git a/docs/reference/jev-cloud.mdx b/docs/reference/jev-cloud.mdx new file mode 100644 index 000000000..409577cbd --- /dev/null +++ b/docs/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev through FailproofAI Cloud" +description: "Cloud machine keys, connection state, limits, and failure behavior for live Jev policy review." +icon: "cloud" +--- + +This is the Cloud route reference for [Jev policies](/policies/jev). Jev, TypeSafe's classifier, reads each tool call against what you actually asked for and answers alongside your policies, never instead of them. Through **FailproofAI Cloud**, a connected machine uses Jev with the same key it already connects with: no TypeSafe account, no second key, no endpoint to configure. Each call is charged to your organization's existing plan allowance. + +Everything Jev does is unchanged from the [bring-your-own-key setup](/reference/jev-providers): hard policies stay final, a reviewable policy's deny is cleared only when Jev was asked about exactly that concern, and any failure falls back to the regex result for that call. + + +Requires **failproofai 1.0.8-beta.0** or later. 1.0.7 has no Jev, even though it sorts above the 1.0.7 betas. Without a Jev config nothing changes: hooks run the regex policies exactly as they always have. + + +## Before you start + +Install Failproof AI on the machine where your agent runs and attach its hooks to a [supported harness](/reference/harnesses). If you are starting from scratch, follow the [quickstart](/start/quickstart) through hook installation. Check the installed CLI with `failproofai --version`; update it if it predates Jev. You also need access to your organization's **Administration → Keys** page to create a machine key. + +Jev reviews named tool calls at the `PreToolUse` or `PermissionRequest` gate. It does not review every event in a session. To see Jev clear a policy deny, you need an installed policy marked [reviewable](/policies/authority); all other policy denies remain final. + +## Turn it on + +1. **Create a key with Jev.** In the FailproofAI Cloud dashboard, open **Administration → Keys → Create key** and pick the **machine** preset. It grants the three permissions a machine needs: `events:add` (send activity), `policies:pull` (receive policies) and `jev:evaluate` (Jev, charged to your organization's plan). A key cannot carry `jev:evaluate` without the other two. +2. **Connect the machine** with that key. Read its one-time secret at a prompt, then run the full setup command: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` installs the daemon, attaches hooks for the agent CLIs it finds, and connects the machine. The environment variable keeps the key out of the command's arguments and your shell history. If your harness was installed later, [attach it explicitly](/start/quickstart). + + If your organization runs its own FailproofAI Cloud rather than the hosted one, add its address: `--url https://` (or export `FAILPROOFAI_CLOUD_URL`). Without it the key is checked against the hosted service and the connection fails. If that host's certificate comes from a private CA, install the CA in the machine's system trust store (for example with `update-ca-certificates`), not only in `NODE_EXTRA_CA_CERTS`: the daemon that sends events and pulls policies reads the system store. See [Troubleshooting](/reference/troubleshooting). + +That is all. Connecting stores the key and, when the machine has **no** Jev config yet, writes one for FailproofAI Cloud. From the machine's first deployment (within about 30 s) FailproofAI Cloud sets the mode: `enforce` while a Jev policy is deployed to it, `off` when none is (see [Who sets the mode](#who-sets-the-mode)). The output says so: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Checks FailproofAI Cloud deploys run on Cloud. To add checks of your own on the machine, install a pack: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**With `--no-transcripts`, connecting does not turn Jev on.** Jev sends each checked tool call and the recent prompt to FailproofAI Cloud, which is more than a decisions-only connection asked to send. The key is still stored, and the output says Jev is available and how to switch it on: + +```bash +failproofai jev setup --provider failproofai +``` + +It also turns Jev through FailproofAI Cloud **off**. A `jev.json` that runs Jev through FailproofAI Cloud (left by an earlier connection with transcripts on) is removed, by the same rule `config --disconnect` uses, and the output says Jev via FailproofAI Cloud stays off on this machine. A `jev.json` for your own Jev endpoint is left as it is, and so is a FailproofAI Cloud one you switched off (`--mode off`). + + +Connecting **never overwrites** an existing `~/.failproofai/jev.json`. If you already use your own Jev endpoint, it keeps being used, and the output says the file was left as configured — and, when that file leaves Jev off (refused, or switched off), says so and how to fix it. To switch that machine to FailproofAI Cloud, run `failproofai jev setup --provider failproofai`. + + +## Who sets the mode + +On a machine connected to FailproofAI Cloud, **FailproofAI Cloud sets the Jev mode**; nothing on the machine does: + +- `enforce` while any Jev (or regex + Jev) policy is deployed to the machine: every checked tool call from an agent one of those policies targets goes to FailproofAI Cloud, which asks its checks together with the checks of the packs installed there. A call from an agent no Cloud Jev policy targets, with no pack check of its own, is not sent at all. In `enforce`, Jev's own deny checks block calls as well as clearing the regex verdicts they review. +- `off` when none is: no Jev at all, whatever `jev.json` says. + +To try a Jev policy before it acts, deploy it with effect **observe**: its checks are still asked, and what they would have done is recorded as a **would-have** on the policy page, but it never blocks a call and never clears one. `failproofai jev setup --mode` and the dashboard's **Settings → Jev** switch say the mode is managed by FailproofAI Cloud and change nothing. `jev.json` is not used for Cloud's checks, even if it names another provider. `failproofai config --disconnect` hands Jev back to the machine's own `jev.json`. + +`failproofai jev status` then says `Jev checks run on FailproofAI Cloud (mode: enforce)`. It also names the checks that review each `both` policy. The fleet page shows why a machine with a mode cannot ask: + +- `transcripts_disabled`: the machine was connected with `--no-transcripts`, which never switches Jev on. +- `jev_unconfigured`: the machine's key does not carry `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud refused some of the machine's calls for the organization's Jev rate limit, and those calls were decided by the regex policies alone. +- `jev_unavailable`: several calls in a row failed, so the machine skips FailproofAI Cloud's Jev for a minute at a time. It retries on its own. + +If FailproofAI Cloud does not answer within 5 seconds, the regex policies decide alone, as for any Jev outage. After 3 failures in a row the machine stops asking for a minute at a time, so a Cloud outage does not slow every tool call. + +A session pause (`failproofai config --pause`) does not stop FailproofAI Cloud's Jev checks, just as it does not stop Cloud-managed policies. It does pause the Jev checks of packs installed on the machine. + +## Check what it is doing + +```bash +failproofai jev status +failproofai jev test +``` + +`status` shows the provider as **FailproofAI Cloud**, the Cloud host the machine connected to, the mode, and the key source as **FailproofAI Cloud connection**, never the key. When a FailproofAI Cloud `jev.json` is in place but Jev cannot run, it says why: + +| `status` says | `status --json` | Meaning | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | The machine is connected, but no Jev key is stored for it: the key lacks `jev:evaluate`, or the connect could not confirm it. Run `failproofai config` again with the key in `FAILPROOFAI_CLOUD_TOKEN`; if it lacks the permission, use a **machine** key. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | There is no FailproofAI Cloud connection on this machine for the Jev key to belong to. | + +After `failproofai config --disconnect` there is no FailproofAI Cloud `jev.json` any more (unless it was switched off, which is kept), so `status` simply reports Jev as off. `status --json` carries the same facts (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), also when the config is absent or refused. `permissions` is always `jev.json`'s; a refusal about `credentials.json` adds `credentialsPermissions`, and `fix` when one command fixes it. `test` sends one live request and reports its latency and the Jev version that answered. It exits 1, and says so in its title, when the answer arrives after the hook timeout (hooks would record `timeout`) or answers its check question wrongly. + +The dashboard's **Settings → Jev** panel also shows the **FailproofAI Cloud connection**: which organization the machine reports into and whether its key carries Jev. It is read from the machine's own files, with no network call. + +## Verify a real call + +Start a new session in the hooked agent. Ask it to use its file-reading tool on `README.md` and report the title. Confirm that the session contains that tool call, then run `failproofai jev status` again: its recent evaluated-call count should increase. Open **Policies → Activity** in the [local dashboard](/reference/local-dashboard#review-policy-activity) to inspect that call's Jev verdict and mode. In Cloud, the organization's **Policies** page shows Jev outcomes for delivered activity. In observe mode, the verdict is recorded as a **would-have** and the policy result still decides the call. A clearance appears only when a reviewable policy matched and Jev cleared its named checks. + +## What reaches the policy page + +The machine already sends its hook activity to FailproofAI Cloud (`events:add`). With Jev on, each gated call's record also says which evaluator ran, what Jev decided, which policies it cleared, why it fell back when it did, its latency and the model that answered — decisions, codes and names, never the command or your prompt. On your organization's **Policies** page: + +- a call Jev's own verdict decided (enforce mode) is attributed to **Jev**, and when the deciding check came from a pack, the record also names that pack and its version; +- in observe mode, Jev's deny or warning appears as a **would-have**, next to the rollouts you are observing; +- the policies Jev cleared, or would have cleared in observe mode, are counted per policy. +- a decision Jev took part in (a block, a warning, a clear, or a would-have in observe mode) lists each check it asked and what that check concluded: verdict, why (`not-detected`, `exempt`, `fired`, `op-requested`, …), its evidence `p`, the `exempt` answer and each probe's answer. A check of a policy deployed to watch (observe) is listed too, marked watched; it never blocks. Jev answers with probabilities, not prose, so there is no free-text reason. Plain allows roll up into counts and do not carry this list. + +## When Jev cannot answer + +Every one of these falls back to your policies' result for that call, and is recorded with its reason: + +| Reason | Cause | +| --- | --- | +| `out-of-credits` | Your organization has used its plan allowance. | +| `http-401`, `http-403` | The key was revoked, or does not carry `jev:evaluate`. Reconnect with a key that does. | +| `http-429` | FailproofAI Cloud is rate-limiting Jev for your organization. Until the wait it asks for is over (its `Retry-After`, at most 60 seconds), the machine sends it nothing and every call falls back straight away. Calls held back that way are recorded as `http-429`, or as `rate-limited` when the machine's own rate limit holds them first. | +| `http-429` (daily limit) | Your organization has used its daily Jev calls: **10,000 per UTC day**, unless whoever operates your FailproofAI Cloud has set another limit. Every call falls back until the count resets at 00:00 UTC; the machine still asks again at most once a minute, so it picks the reset up within a minute. `failproofai jev test` says "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev refused this call's request, usually because the tool call held dense text (base64, hex, minified code) over Jev's token budget. That call falls back every time; it is not an outage. | +| `http-502` | Jev is unavailable right now. | +| `http-503` | This Cloud cannot serve Jev for your org: no model gateway, an org not provisioned yet, or the gateway is down. Ask your admin; hooks ask again at most once a minute. | +| `http-404` | This FailproofAI Cloud does not serve Jev yet. | +| `timeout` | No answer within `timeoutMs` (default 3000). While FailproofAI Cloud sets the machine's Jev mode, the wait is 5000 ms and `jev.json`'s `timeoutMs` is not used. | +| `model-mismatch` | A Jev version other than 1.13 answered. | + +## Where the key lives, and where it goes + +- The key is stored once, in `~/.failproofai/credentials.json` (`0600`, in an owner-only directory), beside the other FailproofAI Cloud credentials. `jev.json` holds no key for this route; one written there makes the config invalid. +- If `credentials.json` carries **any** permission for anyone but you (group or other, read or write), or its directory can be **written** by anyone but you, it is **refused**, not read, and Jev is off until you fix it: `chmod 600` on the file, `chmod 700` on the directory (or reconnect, which rewrites the file at `0600` and makes the directory owner-only). A directory others can only read is fine; one they can write lets them swap the file. +- The key counts only while the connection it came with is on the machine: a policy or reporting credential for the same FailproofAI Cloud **with the same key**, in the same file. A Jev key left behind without one is ignored, and Jev stays off. That happens when an older failproofai's `config --disconnect` leaves the Jev key in place (it does not know to remove it), or when an older failproofai's `config --token` connects with another key, which on FailproofAI Cloud may belong to another organization. To switch Jev back on, connect again with a **machine** key. +- The key is only ever sent to the Cloud origin it was verified against. A `jev.json` pointing anywhere else is refused. +- **An agent on the machine can read it.** `credentials.json` is owner-only, and the agent runs as that owner. Reading failproofai's own files is allowed on purpose (only changing them is blocked, by `block-failproofai-commands`), so the only thing between an agent and this file is `block-read-outside-cwd` — a *reviewable* policy — and from a session started in your home directory, nothing. A key with `jev:evaluate` spends your organization's Jev allowance (up to the daily cap) from wherever it is used, so treat a machine key like any other spending credential: if an agent may have read it, disable it on the Keys page and reconnect with a new one. +- Only your global files decide this. A repository cannot turn Cloud Jev on, point it elsewhere or supply its key, and `FAILPROOFAI_JEV_API_KEY` is ignored for this route. +- For each call Jev evaluates, one request goes to FailproofAI Cloud, carrying what the [bring-your-own-key page](/reference/jev-providers#what-leaves-the-machine) lists (secrets redacted). FailproofAI Cloud forwards it to TypeSafe and does not log or keep it. + +## Turn it off + +On a connected machine, Jev is off when FailproofAI Cloud deploys no Jev policy to it: remove or archive the Jev policies there. + +| Command | Outcome | +| --- | --- | +| Remove the machine's Jev policies in FailproofAI Cloud | Cloud's mode becomes `off` at the next poll (about 30 s): no Jev at all, whatever `jev.json` says. | +| `failproofai config --disconnect` | Disconnect the machine: the key is removed, and so is `jev.json` when it names FailproofAI Cloud and is not switched off. A `jev.json` for your own endpoint stays. | + +From the next tool call, hooks run the regex policies exactly as before. diff --git a/docs/reference/jev-evaluations.mdx b/docs/reference/jev-evaluations.mdx new file mode 100644 index 000000000..bb944c739 --- /dev/null +++ b/docs/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev evaluation reference" +description: "Question types, calibrated scores, limits, and backfill for Jev session evaluations." +icon: "list-checks" +--- + +This page describes the question shapes and scoring rules behind [Jev evaluations](/evaluations/jev). Some questions need a model to *read* the conversation, but not to *write* about it. "Did the customer express urgency?" has two answers. "How frustrated were they?" has a handful, in order. You know every answer before you ask. + +A **classifier evaluation** is for exactly those. You write the question and the answers it may give, and a small model built for classification returns a calibrated number — never free text. + + +Like a judge, a classifier evaluation costs a model call per session. Unlike a judge it is a small, single-purpose model rather than a general one, so it is faster and cheaper — but it will never explain itself. If you need the reasoning, use a [judge](/evaluations/judge). + + +## Which one do I want? + +| Question | Use | +| --- | --- | +| How many tool calls were there? | code | +| Was the session under 30 seconds? | code | +| Did the customer express urgency? | **classifier** | +| Which team should handle this: billing, technical, or sales? | **classifier** | +| How frustrated was the customer? | **classifier** | +| Was the answer actually correct? | **judge** | +| Did it follow our escalation policy, and why do you think so? | **judge** | + +The rule of thumb: **countable → code, answers you can list → classifier, needs an explanation → judge.** + +You do not have to decide up front. Describe what you want measured and the assistant picks, tells you which it chose and why, and you can switch it. + +## The two question types + +### `noul` — is this true? + +Two answers, and you describe both. The result is the probability that the "true" description fits: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Describe both sides. "No urgency expressed" is a real answer and saying so makes the other one sharper. + +### `score` — how much of this? + +An ordered rubric, **worst first**. The result is where the session lands on it, rescaled to 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**A rubric takes three to five levels, and they must all be different.** Both limits are measured, not stylistic: + +- **Two levels** collapses into what `noul` already does better, and **more than five** makes the model hedge toward the middle instead of committing. The same question over the same session scored 0.00 with two levels, 0.01 with three, and 0.55 with ten. +- **Repeated levels** split the answer arbitrarily between them. A session that was unmistakably angry scored 1.00 against `["Calm", "Frustrated", "Very angry"]` and 0.66 against `["Angry", "Angry", "Angry"]` — a well-formed number that means nothing. + +Categories with no order — "billing, technical, or sales" — are not a rubric. Ask them as a `noul` per category, or use a judge. + +## Reading the results + +A classifier produces a **score** from 0 to 1, exactly like a judge, so it charts, filters, and triggers alerts the same way. Two differences are worth knowing: + +- **There is no reasoning.** The field is empty, deliberately. This model does not explain itself, and inventing an explanation would be a fabrication rather than a feature. +- **Uncertainty is labelled.** A `score` question reports its own confidence, and a result the model was unsure about is tagged `low_confidence` — so "which of these should a human look at" is a filter rather than a guess. A `noul` question does not report confidence, so it is never tagged. + +Very long sessions are read in excerpts and combined. When a session is too long to read in full, the result says how many turns were left out — you will never see a judgement made on part of a session presented as one made on all of it. + +## Limits + +- **Three to five rubric levels, all distinct.** See above; both bounds are enforced at authoring time. +- **One question per evaluation.** Ask two things and you get two evaluations, which is also what you want on a chart. +- **Editing the question publishes a new version.** Old and new scores are not comparable, so they are kept apart rather than mixed into one trend line. +- **A classifier always produces a score**, never a metric or an assertion. +- **No reasoning**, as above. If a number will make someone ask "why?", write a judge instead. + +## Testing and backfill + +Unlike a judge, a classifier evaluation **can** be tested before you deploy it — [test it](/evaluations/test) against real sessions the same way you would a code evaluation, and read the scores before anything goes live. + +It can also be [backfilled](/evaluations/deploy#score-sessions-you-already-have) over sessions you already have. It costs a model call per session, so scope the window deliberately rather than replaying everything. diff --git a/docs/reference/jev-intent.mdx b/docs/reference/jev-intent.mdx new file mode 100644 index 000000000..c0f45bc36 --- /dev/null +++ b/docs/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev intent capture" +description: "Which harness events tell the Jev evaluator what the human asked for, which field carries the text, what is never counted, and the risk that comes with trusting a harness-delivered prompt." +icon: "message-square-quote" +--- + +When you configure [Jev policy review](/policies/jev), the evaluator judges each gated tool call against **what the human asked for**, not against whatever text the harness put in front of the agent. A reply such as "yes, force-push it" can clear a **reviewable** policy — which is the whole point of the evaluator, since a regex that cannot read the request blocks a third of real work. + +That text comes from one place: **the prompt the harness itself hands the hook at its prompt-submit event**. Failproof AI records the part of it the human typed — harness wrapping stripped, secrets redacted, capped — into a `0600` file under its own state directory. Nothing on disk is consulted: the session transcript is a file the agent can rewrite in one command, so it is never asked who wrote a prompt. + +## The risk this accepts, plainly + +An agent that can already run commands can make a harness submit a prompt. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` and `pi -p` all fire the same prompt-submit event, with the same payload, as a person typing, in a child session that agent controls. It can also run Failproof AI's own hook binary and feed it a payload it wrote. Nothing inside Failproof AI can tell either from the real thing — both are the same program reading the same stdin. + +**So an agent with a shell can forge its own consent.** That is a deliberate trade, taken on 2026-09-23, and here is both halves of it: + +- **What it buys.** The alternative was built and measured: require a field in which the harness names a human as the prompt's author, and record nothing otherwise. No shipping harness sends such a field, so that version recorded **nothing, on every harness** — Jev judged every call with no stated intent and could never clear a single policy. A capture that never fires is not a safer product, it is no product. +- **What it cannot do.** A recorded prompt only ever clears a policy already marked **reviewable**. A **hard** policy is never cleared by anything Jev says, so a forged prompt can never turn a hard deny into an allow — and skipping the hook gains an agent nothing either: the harness invokes Failproof AI for the tool call independently. +- **What it can do, at full size.** The worst it can do is clear one of the fifteen reviewable built-in policies — and **twelve of those fifteen block**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` and the six infrastructure-CLI blocks (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) are denies, so a forged consent can turn a real deny into an allow on printing environment secrets, reading a `.env` file, reading outside the project, `rm -rf`, a force-push, writing a secrets file, or changing live infrastructure. Only `warn-git-amend`, `warn-destructive-sql` and `warn-global-package-install` are nudges. A default install switches on two of the twelve, `protect-env-vars` and `block-env-files`; the other ten reach only a machine where someone enabled them. What no prompt reaches is everything hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, the guard that stops an agent disabling Failproof AI, and every other built-in not marked reviewable. [Policy authority](/policies/authority) lists all fifteen and what each one is reviewed by. + +What is still refused is everything that is cheap to check and that an agent cannot obtain just by asking: a turn the harness's own payload marks as machine-submitted, a payload naming a sub-agent, a session id that is not a plain name, an event that is not the prompt-submit one, and text that is nothing but harness wrapping — including Failproof AI's own stop-gate words, which several harnesses feed back as the next user turn. + +## Per-harness table + +"Text field" is the stdin payload field after Failproof AI's per-harness normalization. "Recorded" says whether the prompt is kept as the human's request. + +| Harness | `--cli` | Prompt event → canonical | Text field | Recorded | Agent's last message read from | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Yes, unless the payload's `source` names a turn nobody submitted (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, an unknown value and a build that sends no `source` at all are all recorded | the session transcript (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Yes | the rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Yes | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Yes, with the `` wrapper peeled when it is the whole prompt | the agent transcript JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | Yes — but current OpenCode carries no text in that event, so in practice nothing is recorded; a repeat of the same message is recorded once | none (sessions are SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Yes, unless `input_source` is `extension` — another extension's `sendUserMessage()`, whose text can be model-written or repo-derived | the Pi session JSONL | +| Hermes | `hermes` | none | — | No — Hermes has no prompt-submit event at all | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Yes, unless the run metadata marks the run as a machine's: a `trigger` other than `user`, an `inputProvenance.kind` other than `external_user`, or `senderIsOwner: false` | none (`before_agent_run` carries no transcript path) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Yes | the droid session JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Yes | none (sessions are SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | none | No — `PreInvocation` fires before *every* model call in a turn and carries no prompt text | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Yes | none (sessions are SQLite) | + +Two harnesses record nothing, and for the same reason in both cases: their event delivers no human text. Hermes has no prompt-submit event — its native plugin handles `pre_llm_call` itself and forwards only tool, session and subagent events. Antigravity's `PreInvocation` fires before every model call, on a human turn and on the five that follow it, and carries no prompt field; hooks can also inject `userMessage` steps into the same conversation. There is nothing in either event to record. + +## What makes a prompt the human's + +1. **The event.** Failproof AI was invoked for the harness's prompt-submit event, which the handler canonicalizes to `UserPromptSubmit`. +2. **The payload.** The harness writes it on the hook's stdin, and it carries the text in the field named above. A call that reaches Failproof AI without the payload records nothing. +3. **Nothing in the payload rules the turn out.** A payload that names a sub-agent (`agent_id`) is the agent prompting itself. A `source`, `input_source` or OpenClaw run marker that names a machine-submitted turn is refused. An **absent** marker rules nothing out — that is the difference from the version that recorded nothing, since every marker here is absent on every shipping build. +4. **Something is left after the wrapping is stripped** (see below). + +**The session transcript is not evidence of who wrote a prompt.** Earlier versions of this page described a transcript cross-check: the prompt was refused if the transcript showed the model scheduling it, and the transcript had to continue the one the previous prompt saw. That check is gone. A transcript is a file the agent already has a shell over — it can be truncated, replaced, padded past the read budget, snapshotted at the start of a turn and restored at the end, or made to read well again with entries the agent wrote. Each round of hardening was followed by another spelling of the same forgery, so the whole mechanism was removed rather than repaired. + +The transcript is still read for one thing: **the agent's last visible message**. That message is agent-written by definition, Jev is told so, and it is never consent on its own. + +## What is kept from a prompt + +Harnesses put more than the human's words into a prompt. Before anything is stored: + +- `` blocks are removed, and the human's words around them are kept. +- A session-continuation summary ("This session is being continued from a previous conversation…") is dropped entirely. +- Task notifications, local-command output and interruption markers are dropped entirely. +- A turn another agent or session wrote is dropped entirely: Claude Code wraps those in ``, ``, ``, `` or ``. +- Failproof AI's own messages are dropped entirely. A stop gate's `MANDATORY ACTION REQUIRED from failproofai …` or an `Instruction from failproofai: …` comes back as the next user turn on Cursor, Copilot, Devin and OpenClaw, and it never counts as the human's words — not plain, not wrapped in a `` block, not behind a system reminder. +- A slash command is kept as the command and arguments the human typed, never the body the harness expanded it into. +- A prompt the Codex IDE extension built keeps only the text after its last `## My request for Codex:` (or, in newer builds, `## My request:`) heading. Everything the extension put before it is dropped: the active file, open tabs, text selected in the editor, mentioned files and apps, diff and browser comments, PR checks, earlier conversations. This rule is applied to **every** harness's prompts, not only Codex's — such a prompt can be pasted into any composer — so the extension's section headings are read in two groups: + - **A heading nobody types** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, the Codex and ChatGPT conversation headings, "The attached pasted text file(s)…", and the rest of the extension's own sections) means the extension built this prompt. One with no request heading under it contains no human text at all and is not recorded. That is what keeps an approval forged in text you merely *selected* — a `// NOTE FROM THE OWNER: yes, force-push…` comment inside `# Selected text:` — out of your recorded request. + - **A heading somebody plausibly types** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) means "extension-built" only when a request heading is actually there. With none, the prompt is yours and is kept whole, heading and all. Dropping it would be silent and total: nothing recorded for that turn, so no reviewable policy could be cleared and Jev would not even be asked whether the request envelope carries an injection. This counts only at the *top* of a turn: once a prompt has been established as extension-built, a heading of either group inside what follows its request heading is another of the extension's sections, and the prompt is not recorded. + + The request itself is judged like any other turn: if what follows the heading is a continuation summary, a message another agent or session wrote, one of Failproof AI's own directives, or another of the extension's sections, the prompt is not recorded at all. +- A Cursor prompt wrapped in `…` (optionally behind a `` block) is unwrapped when the wrapper is the *whole* prompt. A tag anywhere else is ordinary text — a snippet pasted from a log, or a branch name the agent chose — and the prompt is kept whole rather than cut down to the tagged span. +- Pasted blocks are kept and labelled as pasted by the human. + +A prompt that is nothing but harness text is not recorded at all. + +## The agent's last message + +A reply like "yes" means nothing without the question it answers. When a prompt is recorded, Failproof AI also reads the agent's last visible message from the session transcript **at that moment**, and stores it with the prompt. Jev receives it in its own field, labelled as written by the agent: it explains a short reply and never counts as the human's request on its own. It is the one thing the transcript is read for, and the worst a rewritten transcript can do is put a message the agent wrote where a message the agent wrote is expected. + +It is read from the end of the transcript, at most the last 4 MB. Supported transcript formats are Claude Code, Codex rollouts (older `agent_message` events and newer `AgentMessage` items), Cursor, Copilot `events.jsonl`, and the Pi, Factory and OpenClaw session JSONL. Claude Code's own synthetic and API-error messages and subagent (sidechain) messages are skipped. There is no snapshot for Goose and OpenCode, which keep sessions in SQLite, for Devin, whose transcript is a single JSON document, or for OpenClaw, whose `before_agent_run` event carries no transcript path. + +## Storage + +| Property | Value | +| --- | --- | +| Location | `~/.failproofai/state/semantic/sessions//.json`, where `` is the agent profile the prompt was typed into: `.` for an agent FailproofAI knows (the identity Cloud policies target), or just `` otherwise | +| Permissions | file `0600`, directory `0700`. Every directory above it, up to `~/.failproofai`, is held to the same rule `jev.json`'s directory is: one that anyone else can **write** to can be renamed away and replaced, so the read path takes those write bits off where it can, and reads **nothing** where it cannot. A recorded prompt is then absent rather than forged, and nothing is cleared | +| Kept per session | the last 5 prompts; a prompt identical to the one before it replaces it rather than taking a new slot | +| Window | prompts older than 6 hours are ignored | +| Size | each prompt and agent message is capped at 6,000 characters, keeping the head and the tail | +| Secrets | redacted with the same patterns as the `sanitize-*` policies before anything is written. A text longer than 48,000 characters is redacted as its first 28,800 and last 19,200 characters, and the text next to those cuts, where a secret could have been split, is never stored | + +A session ID containing anything but letters, digits, `.`, `_` and `-`, or longer than 128 characters, is never used as a file name, so nothing is recorded for it. + +A session file exists only once a prompt has been recorded in it. It holds prompts and nothing else — no origin state, no transcript mark — and it is deleted once it has been silent for longer than the six-hour window, the next time a new session writes its first prompt. + +A prompt is read back only for the same agent profile and session ID it was recorded under. Session IDs come from the agent, so two profiles can use the same one; keying by profile keeps one profile's words from ever counting as another's request. Files from before this layout (`sessions/.json`) cannot say which profile wrote them, so they are never read, and expire with the six-hour window. + +Nothing is recorded unless a Jev endpoint is configured. Under a FailproofAI Cloud Jev mode, nothing is recorded for an agent profile that no Cloud Jev check is assigned to and no installed pack's check reviews. + +### The project root + +"Inside the project" — what `read-outside-workspace` and the other path checks judge against — means inside the project the session was in at its **first reviewed call**. The root is pinned then and a later `cd` never moves it; a `cd` still changes how a relative path resolves. Letting it follow the `cd` would let `cd ~/.ssh` in one call make `~/.ssh` the project for the next. + +The pin is `~/.failproofai/state/semantic/roots/.json`, holding `{root, at}`: file `0600`, directory `0700`, and the same session-ID rule as above. Files older than 7 days are deleted when a new session pins its root. A `roots` directory other users can write to is ignored, and the live directory's root is used instead. To re-pin a session, delete its file. + +## Known limits + +- **A prompt is only as trustworthy as the hook invocation.** Everything here reads the payload the harness wrote on the hook's stdin. An agent that can run commands can run the harness headlessly (`claude -p` and the seven others listed above) or run Failproof AI's hook binary itself with a payload it wrote, and record a prompt nobody typed. This is the accepted trade described at the top of this page: it clears reviewable policies only, never a hard one — but twelve of the fifteen reviewable built-ins are denies, so a forged prompt can turn a real block into an allow on those twelve. +- **Sub-agent detection is Claude-shaped.** A payload carrying `agent_id` is never recorded, on any harness. That is the field Claude Code, Factory Droid and Devin would use. Codex fires its prompt event inside sub-agent threads, Copilot runs in-process sidekicks, Goose has a `delegate` tool and OpenClaw runs personas — none of which marks the payload in a way this recognises, so a sub-agent prompt on those harnesses is recorded as the session's own. OpenClaw's `openclaw.agentId` is **not** that mark: the shipped plugin sets it on every run, the owner's included. +- **Schedulers that carry no marker.** Claude Code's `schedule_wakeup` and `loop_wakeup`, and OpenClaw's `cron` and `heartbeat` triggers, are refused because those harnesses say so in the payload. Goose's own scheduler (`goose schedule add`) and Codex's `codex exec` say nothing, so a run they start is recorded like any other. +- **An agent's last message can be a message the agent chose.** The transcript is not authenticated, so an agent that writes its own transcript can decide what its "last message" says. It is labelled agent-written and never clears anything by itself — but note that `decide.ts`'s v1 path lets it satisfy the deterministic "did the user name this target" check, so an agent that controls its transcript can supply a target name an override needs. +- **A prompt that opens with one of the extension's machine headings is dropped whole.** Start a prompt with `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` or another section heading from the first group above, and never write a `## My request:` heading, and nothing is recorded for that turn — so nothing is cleared for it either. That is deliberate: those sections carry text somebody else controls (code you selected, a reviewer's diff comment, a page title), and recording that as your words is the worse failure. Headings a developer plausibly types are in the second group and never drop a prompt on their own. +- **OpenCode records nothing in practice.** Its `message.updated` event carries no text in current OpenCode, and it also fires for the child sessions its task tool creates, whose "user" message the parent agent wrote. +- **`CODEX_HOME` is not honoured** by the rollout discovery in `lib/codex-sessions.ts`. This affects only where an agent-message snapshot is looked for, never whether a prompt is recorded. diff --git a/docs/reference/jev-providers.mdx b/docs/reference/jev-providers.mdx new file mode 100644 index 000000000..193225b6c --- /dev/null +++ b/docs/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev providers and own-key setup" +description: "Provider endpoints, model IDs, configuration, and failure behavior for live Jev policy review with your own key." +icon: "key-round" +--- + +This is the provider and configuration reference for [Jev policies](/policies/jev) with your own key. Regex policies match strings. They cannot tell `rm -rf build/` that you asked for from `rm -rf ~` that slipped into a plan, so they block too much in one place and too little in another. **Jev**, TypeSafe's classifier, reads the call against what you actually asked for and answers a set of yes/no questions about it in one fast request. + +With your own Jev endpoint and key configured, Failproof AI asks Jev about each tool call **alongside** the regex policies, never instead of them: + +- A **hard** policy's deny is final. Jev cannot clear it. Every policy is hard unless it is explicitly marked reviewable and names the Jev checks that cover it, so a custom, pack or Cloud policy that says nothing is hard, and the always-on self-protection guard is always hard. +- A **reviewable** policy's deny may be cleared, but only when Jev was asked about the exact concern that policy covers and answered "nothing here" or "the user asked for this". A check that finds the concern real, when the user did not ask for the call, keeps the deny — even when its own verdict is only a warning, because before a tool call a warning does not stop the agent. And when that check is one that can deny (secret exposure, credential exfiltration, destructive deletion, …), nothing is cleared on that call. +- A block can still become a **warning** when the call is a step of the task you gave and reaches no further: Jev softens its own deny to a warning, and that warning — naming what is actually wrong with the call — replaces the policy's block. +- Jev can also warn or deny on its own, for harm no regex describes. +- If Jev cannot answer (timeout, rate limit, server error, no credits, an unexpected model version), that call gets the regex result, exactly as without Jev. +- Jev never makes a call more permissive than your policies alone unless it read the whole call and was asked about the exact concern. Anything less — a call too big to send whole, a suspected injection — withdraws the clearances and keeps every deny. + + +Without a Jev config nothing changes: hooks run the regex policies exactly as they always have. The config is the whole opt-in. + + + +On FailproofAI Cloud? You do not need a key of your own: a machine connected with a key that carries `jev:evaluate` can use Jev on your organization's plan. See [Jev through FailproofAI Cloud](/reference/jev-cloud). + + +## Before you start + +Install **failproofai 1.0.8-beta.0 or later** and attach its hooks to a [supported harness](/reference/harnesses) on the machine where your agent runs. Follow the [quickstart](/start/quickstart) if this is a new machine, or [set up local enforcement](/start/setup#enforce-locally) if you do not use Cloud. Check the installed CLI with `failproofai --version`. + +Get an API key from a provider below, or have a compatible endpoint and its key ready. Jev reviews named tool calls at the `PreToolUse` or `PermissionRequest` gate. It can issue its own verdict, but clearing an existing policy deny also requires an installed policy marked [reviewable](/policies/authority). Hard policy denies stay final. + +## Choose a provider + +Jev is reachable through five routes. Bring a key for any one of them. + +| Provider | `--provider` | Endpoint | Default model | Notes | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Exact version pin. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Requests are routed to zero-data-retention endpoints only, with no fallback to another provider. Reports a dated version such as `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Names Jev only by an alias, so the answering version is recorded as unverified. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Needs `--account-id`. About six calls a second per key were measured before HTTP 429. | +| Your own endpoint | `custom` | `/systemone` | `jev-1.13.0` | Any endpoint that accepts TypeSafe's request body and reports which model answered. `https` only; plain `http` to a loopback host (`localhost`, `127.0.0.1`, `::1`) is accepted for local testing. | + + +With Vercel's own bring-your-own-key feature, a failed request is silently retried with Vercel's credentials. If you need every call billed to, and seen by, your own TypeSafe account only, use TypeSafe directly. + + +## Set it up + +One command, the endpoint and the key. Start in `observe` mode so you can inspect Jev's verdicts while the existing policies keep deciding calls: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### The URL picks the provider + +You do not have to name the provider: the URL's **host** is which one it is. + +| URL host | Provider | Also needs | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| any other host | `custom` | — the URL you gave is the base URL | + +Three things follow from that: + +- **A URL that is the provider's own API writes no override.** `--url https://api.typesafe.ai/v1` produces exactly the config `--provider typesafe` would have. Give a different path or host on a known provider and it is stored as the base URL, as `--base-url` would store it. +- **`--provider` still overrides the inference**, which is how you reach a proxy that speaks a provider's API from a host of your own: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **A `--provider` that contradicts the host is refused**, not guessed at. `--provider openrouter --url https://api.typesafe.ai/v1` writes nothing and says why: the two spellings disagree about where your key is about to be sent. The same pair is refused from `jev setup --base-url` and from the dashboard's Jev settings. (`--provider custom` is not a contradiction — it means "treat this URL as itself" — except on Cloudflare's host, whose per-account endpoint a custom route cannot reach.) + +`--url` is validated exactly as the `baseUrl` in the config file is, and refused in the same words: `https`, or plain `http` to a loopback host (`localhost`, `127.0.0.1`, `::1`) in any mode. Risk: nothing authenticates a loopback server, so while it is down another local process could take its port and answer; use `https` outside local testing. + +### The key + +Pipe it in with `--key-stdin`, or run the command in a terminal without it and paste the key at a masked prompt. Either way it goes straight into the config file and is never printed back. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` takes the same flags and is the longhand for all of it: `setup --provider ` where you would rather name the provider than the URL. + +### `--token`, and what it costs + +`--token ` puts the key on the command line, which is the fastest way to configure a machine and the only spelling that leaves the key anywhere but the config file: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +A command-line argument is in your shell's history file afterwards, and while the command runs it is in the process list — readable from `/proc` by anything running as you. `setup` says so every time `--token` is used. Prefer `--key-stdin` on a machine you share, in a recorded session, or anywhere the history file is synced; rotate a key you have passed this way if it matters. + + +`--token`, `--key-stdin` and `--key-from-env` are mutually exclusive: give one. + +Then send one small live request to check the key, the endpoint and which Jev answered: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` exits 1, and says so in its title, when the answer arrives after the timeout (every hook would fall back to regex as `timeout`) or answers its check question wrongly. + +Hooks read the config on every tool call, so it applies from the next one. There is nothing to restart, with or without the daemon. + +## Check what it is doing + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` shows the provider, endpoint, model, mode, the config file and its permissions, and never the key. Below that it summarizes recent activity: how many calls Jev evaluated, how often it fell back to regex and why, its latency, and which reviewable policies it cleared. + +## Verify a real call + +Start a new session in the hooked agent. Ask it to use its file-reading tool on `README.md` and report the title. Confirm that the session contains that tool call, then run `failproofai jev status` again: its recent evaluated-call count should increase. Open **Policies → Activity** in the [local dashboard](/reference/local-dashboard#review-policy-activity) to inspect the call's Jev verdict and mode. In observe mode, the policy result still decides the call. A clearance appears only if a reviewable policy matched and Jev cleared every named check; an ordinary read may have no policy to clear. + +## Observe mode + +`enforce` is the default. To watch Jev without letting it change any decision, switch to `observe`: Jev is still asked and its verdicts are recorded, but the regex result is what is enforced. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` keeps the config — the endpoint and the key — and stops asking Jev: hooks run the regex policies exactly as without a config, and `failproofai jev status` says "off (switched off)". Switch back with `--mode observe` or `--mode enforce`. + +Re-running `setup` for the same provider keeps the stored key, so a mode switch is one flag. Switching provider starts over and asks for that provider's key. So does a `--base-url` that moves requests to a different host: a stored key is only sent to the host it was given for, or to its provider's own API. + +## The config file + +Everything lives in one file, `~/.failproofai/jev.json`, written by `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Field | Meaning | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` or `custom` — or `failproofai`, whose key comes from the FailproofAI Cloud connection instead of this file (see [Jev through FailproofAI Cloud](/reference/jev-cloud)). | +| `apiKey` | Sent as `Authorization: Bearer `. | +| `baseUrl` | Required for `custom`; replaces the provider's API base otherwise. Must be `https`. Plain `http` to `localhost` is accepted only with `mode: observe`: nothing authenticates a local port, so while your proxy is down any process on the machine, including the agent being judged, could answer in its place. | +| `accountId` | Cloudflare only: 32 lowercase hex characters. | +| `model` | Replaces the provider's default model id. A versioned id must name Jev 1.13. A value shaped like an API key is refused (and not repeated back), so a key pasted into `--model` is never stored or sent as the model. | +| `timeoutMs` | How long a tool call waits for Jev before using the regex result. 100–10000, default 3000. | +| `mode` | `enforce` (default), `observe`, or `off` (keep the config, run no Jev). | + +Three rules protect it: + +- **Owner-only.** It is written with permissions `0600`. A copy that any other user or group can read or write is **refused**, and hooks fall back to regex until you run `chmod 600 ~/.failproofai/jev.json` or `setup` again. The directory is checked too: `~/.failproofai` must not be **writable** by anyone else, because whoever can write there can replace the file whatever its own permissions are. `setup` takes those write bits off if it finds them. `failproofai jev status` says when a config has been refused and shows the endpoint the file names: someone else could have changed it, so check it is yours before you `chmod`. Re-running `setup` on such a file carries its stored key only to the provider's own API; any other endpoint it names needs the key again (`--key-stdin`), or `--base-url default` to send requests back to the provider. +- **Global only.** A repository cannot turn Jev on, point it at another endpoint or pick its model: a `.failproofai/jev.json` inside a project is ignored, and the provider, URL, model and account id are read only from that file — never from the environment, which a repository's agent settings can set. (`FAILPROOFAI_HOME` is not a way around that: it moves the whole failproofai directory, your policies included, rather than redirecting Jev on its own.) +- **The key alone may come from the environment.** If the file has no `apiKey`, `FAILPROOFAI_JEV_API_KEY` supplies it for that session (`setup --key-from-env` writes such a file). It never replaces a key the file holds, and it cannot turn Jev on without the file. Where the variable is not set, Jev is simply off for that shell: `failproofai jev status` says so, exits 0 and leaves the config alone (`status --json` reports `"status": "key-missing"` with `"reason": "no-env-key"`). The `failproofaid` daemon does not see your shell's environment, so on a machine set up with `failproofai config`, keep the key in the file. + +## Which Jev answers + +Failproof AI's decision thresholds were calibrated on Jev 1.13, so an answer is used only when it comes from that family: `jev-1.13.x`, or OpenRouter's `typesafe/jev-1.13-`. Where a provider names Jev only by an alias and reports no version (Vercel, and Cloudflare when it does not say), the answer is used and recorded as unverified. A `custom` endpoint must report the model that answered; the one exception is an unversioned `--model` name you configured for it, which, echoed back, is recorded as unverified in the same way. An answer reporting any other version, or a `custom` answer reporting none, is not used: that call falls back to regex with the reason `model-mismatch`. + +## When Jev cannot answer + +Each of these falls back to the regex result for that call and is recorded with its reason, which `failproofai jev status` totals: + +| Reason | Cause | +| --- | --- | +| `timeout` | No answer within `timeoutMs`. | +| `http-429` | The provider rate-limited the key. | +| `rate-limited` | Failproof AI's own limiter held the call back before sending it: 5 requests a second, in bursts of up to 5, and none for a moment after the provider answers `429`. Not the provider. | +| `http-500`, `http-502`, `http-503`, … | A server error at the provider. The exact status is recorded. | +| `out-of-credits` | HTTP 402: the provider account has no credits left. | +| `provider-refused` | HTTP 402 from Cloudflare reading "Model execution failed (Payment error)": the provider declined to run the model on this request. Usually not billing, so topping up will not move it. | +| `http-401`, `http-403` | The key was refused. | +| `http-404` | Nothing is served at `/systemone`, so the base URL is wrong — `/systemone` is appended to it, and every provider serves it at its version root. `failproofai jev models` shows what the endpoint does serve. | +| `network` | The endpoint could not be reached. | +| `http-301`, `http-302`, `http-307`, `http-308` | The endpoint answered with a redirect. Redirects are never followed, so the answer only ever comes from the URL in your config; set `--base-url` to the final URL. | +| `malformed` | The endpoint answered, but not with a Jev answer — a body that is not JSON, or one with no answers in it. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare's envelope reported a failure, or a job that had not finished. | +| `model-mismatch` | A Jev version other than 1.13 answered, or a `custom` endpoint did not say which model answered. | +| `request-cut` | **Not an outage.** Jev answered; it was shown only part of the call, so its answer cleared nothing. See [When Jev answered, but not on the whole call](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` can show a few rarer reasons too, such as `upstream-error` (the answer carried the provider's own error) or `config`, and totals any reason it cannot name as `other`. + +`request-cut` is in this table because `failproofai jev status` totals it with the rest, and because it too leaves every deny standing. It is the one reason here that says nothing about your provider: the request arrived and Jev answered it. Unlike every row above it, that answer still counts — Jev's own deny or warning applies on top of the regex result rather than being discarded. So a run of them means calls are reaching the evaluator too big to send whole, not that your endpoint is unwell, and topping up credits or changing the URL will not move the number. + +## When Jev answered, but not on the whole call + +Two more things can happen, and neither is Jev failing to answer. Both are about how much of the call, or of the conversation, fitted into one request. + +**Part of the call itself did not fit.** A tool call is sent inside a fixed budget, and an outsized one — a very large `Write`, a huge MCP body, a command padded out to the cap — is sent with what fitted. Jev still answers, and its answer still counts: its own deny or warning applies as usual. What it cannot do is **clear** anything, because a verdict given on part of a call is not a verdict on the call. So every policy deny stands, and the call is recorded as a fallback with the reason `request-cut`, which `failproofai jev status` totals alongside the reasons above. The rule this gives you: making a call bigger can cost it its clearances, and can never buy one. + +**A message did not fit.** A long prompt you pasted, the agent's last message, or a prompt this evaluator's own store had already capped. **Nothing changes**: the call is judged, cleared and recorded exactly as any other, and it is not counted as a fallback. The length of what you type never decides a verdict, and a cut cannot manufacture consent: where a prompt arrived already capped, "you did not ask for this" stops being a conclusion that can be drawn from it at all, rather than becoming one. + +The line between the two is who wrote the text. The call is the agent's, and a rule that let its length subtract severity would be a rule the agent can use; your prompt is yours, and treating its length as a signal only ever punished pasting a spec or a stack trace. + +## What leaves the machine + +For each tool call Jev evaluates, one request goes to your provider, carrying: + +- the tool call itself, with secrets such as API keys, bearer tokens and `KEY=` assignments redacted; +- the recent prompts you typed, with text your agent's harness added removed; +- the agent's last message before your latest prompt, labelled as agent-written; +- facts computed locally, such as whether a path is inside the project — the one the session was in at its first reviewed call, [pinned for the session](/reference/jev-intent#the-project-root) — and the current git branch. + +It goes only to the endpoint in your config, under your key. + +## Turn it off + +```bash +failproofai jev remove +``` + +This deletes `~/.failproofai/jev.json`. From the next tool call, hooks run the regex policies exactly as before. The per-session stores under `~/.failproofai/state/semantic/` (recorded prompts in `sessions/`, project roots in `roots/`) are left in place and age out. To stop asking Jev but keep the config, use `failproofai jev setup --mode off` instead. + +## Command reference + +| Command | Outcome | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configure it in one command; the provider comes from the URL's host | +| `failproofai jev --url --token ` | Same, with the key on the command line — your history and the process list see it | +| `failproofai jev setup --provider --key-stdin` | Write the config from a key piped on stdin | +| `failproofai jev setup --provider ` | Same, asking for the key at a masked prompt | +| `failproofai jev setup --key-from-env` | Store no key; read `FAILPROOFAI_JEV_API_KEY` per session | +| `failproofai jev setup --mode observe` | Switch mode (`enforce`, `observe` or `off`), keeping the stored key | +| `failproofai jev setup --model ` / `--base-url ` | Override the model or API base; `default` clears the override | +| `failproofai jev setup --timeout-ms ` | Change the per-call budget | +| `failproofai jev status [--json]` | Configuration, permissions and recent activity; never the key | +| `failproofai jev test [--json]` | One live request: latency and the version that answered | +| `failproofai jev models [--provider ] [--url ] [--json]` | The model ids that endpoint's `/models` reports, marking the configured one | +| `failproofai jev remove` | Delete the config; Jev is off | diff --git a/docs/reference/jev.mdx b/docs/reference/jev.mdx new file mode 100644 index 000000000..187637a3e --- /dev/null +++ b/docs/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev integration reference" +description: "Configuration, providers, keys, request data, and failure behavior for Jev." +icon: "braces" +--- + +Jev has two uses in Failproof AI: + +| Use | When it runs | What it returns | Start here | +| --- | --- | --- | --- | +| Session evaluation | After a session finishes | A score for a fixed-answer question | [Jev evaluations](/evaluations/jev) | +| Tool-call policy review | Before a gated tool call runs | A verdict alongside the installed policies | [Jev policies](/policies/jev) | + +## Reference pages + +| Topic | Details | +| --- | --- | +| [Evaluation questions](/reference/jev-evaluations) | Boolean and ordered-score criteria, results, limits, and backfill. | +| [Provider comparison and own-key setup](/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare, and custom endpoints; URL inference, model IDs, `jev.json`, modes, and fallback codes. | +| [FailproofAI Cloud route](/reference/jev-cloud) | Machine-key permissions, automatic observe setup, usage limits, connection state, and data handling. | + +The local CLI commands are listed in the [Failproof AI CLI reference](/reference/failproof-cli). The [local dashboard reference](/reference/local-dashboard#set-up-jev) describes its Jev settings and activity view. diff --git a/docs/reference/local-dashboard.mdx b/docs/reference/local-dashboard.mdx index a9c224a98..02116370c 100644 --- a/docs/reference/local-dashboard.mdx +++ b/docs/reference/local-dashboard.mdx @@ -17,7 +17,7 @@ The local dashboard is separate from Failproof AI Cloud. It works without a Clou | Projects | Browse discovered projects across supported agent histories and compare their most recent sessions. | | Project sessions | Open one local transcript, review raw ordered entries and subagents, download it, and correlate policy activity. | | Audit | Review the last offline scan, risky patterns, strengths, affected projects, and suggested builtin policies. | -| Settings | Configure scheduled local scans and emailed audit reports when the daemon/platform supports them. | +| Settings | Configure scheduled local scans and emailed audit reports when the daemon/platform supports them, and [Jev](#set-up-jev): its provider, endpoint, token and mode, and whether this machine's FailproofAI Cloud connection can run it. | ## Review policy activity @@ -67,6 +67,15 @@ The Projects page combines supported local history stores. Select a project to l If a project or session is missing, confirm the harness uses its default history location or register an extra root with `failproofai harness add-path`. +## Set up Jev + +The **Settings** page's Jev section writes the same `~/.failproofai/jev.json` that `failproofai jev setup` writes, validated by the loader's own rules, so the hooks use it on their next call. It says whether Jev is on and in which mode, and — once it is on — how many calls it answered and how often it fell back to the regex policies. Failproof AI ships no Jev checks: while no installed pack declares any, the section says so and names `failproofai policies add FailproofAI/jev-policies`, and Jev asks nothing. + +- **Your own endpoint.** Choose the provider, give an endpoint URL for `custom` (optional for the others) and an account id for Cloudflare, paste the token, and pick the mode (`observe`, `enforce` or `off`). The token is write-only: the page never shows it, and leaving the field blank keeps the stored one while the provider and the endpoint's host stay the same. Change either and the page asks for the token again, so a stored key is never sent somewhere it was not given for. See [Jev with your own key](/reference/jev-providers). +- **FailproofAI Cloud.** Jev through Cloud is turned on by connecting the machine (`failproofai config --token `); the page offers only its on/off switch and mode. See [Jev through FailproofAI Cloud](/reference/jev-cloud). + +A config whose key comes from `FAILPROOFAI_JEV_API_KEY` (`jev setup --key-from-env`) is judged from the dashboard's own environment, which may not be the one your agent runs in; run `failproofai jev status` where the agent runs to see what its hooks do. + ## Schedule offline audits diff --git a/docs/reference/mcp.mdx b/docs/reference/mcp.mdx new file mode 100644 index 000000000..0f980b8dd --- /dev/null +++ b/docs/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP server" +description: "Connect Claude, Cursor, Codex, or another MCP client to Failproof AI Cloud, using your own permissions." +icon: "plug" +--- + +Connect an AI tool to Failproof AI Cloud and work with your agents' data from it. Your tool can query sessions and events, run read-only SQL, read dashboards, alerts, issues, audits, and policies, and, if you hold the permission, make changes such as creating an alert or deploying a policy. + +Every call runs with **your own** permissions, in **one** organization you choose when connecting. + +There is one address for everyone, hosted or self-hosted: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Connect a client + +Add the address to your client. The first time a tool is used, your browser opens. Choose where your Failproof AI Cloud is, sign in, pick one organization, and select **Allow**. **Cancel** connects nothing. + +The page names the app and where it returns to. An app that isn't identified by its own web address is marked **unverified app**, so continue only if you just started this from your own client. + + + + In claude.ai or Claude Desktop, go to **Settings → Connectors → Add custom connector**. Name it `Failproof AI`, enter the address, select **Add**, then **Connect**. + + On Team and Enterprise plans, an owner adds the connector for the organization first. Each person then connects their own account. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Then run `/mcp` inside Claude Code, select `failproofai`, and choose **Authenticate**. + + + Add this to `~/.cursor/mcp.json`, or to your project's `.cursor/mcp.json`: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor shows **Needs login** next to the server. Select it to sign in. + + + Add this to `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Then run `codex mcp login failproofai`. + + + Any client that supports remote MCP servers over Streamable HTTP with OAuth works. Give it the address above. There is no client ID or secret to configure. + + + +## One organization per connection + +A connection acts only in the organization you picked. To use two organizations, add the server twice under different names, such as `failproofai-acme` and `failproofai-sandbox`, and connect each to its own organization. + +Demo organizations don't accept connections. Pick your own organization instead. + +## Permissions + +A connection can do what you can do in the organization, within the set below. It follows your current permissions: if an admin gives you more, the tool gains it, and if they take something away, the tool loses it on its next call. + +| Permission | Lets the tool | +| --- | --- | +| `events:read` | List events, read a session's overview, list agents and environments | +| `evaluations:read` | List sessions, and read and summarize evaluation results and jobs | +| `evaluations:trigger` | Create evaluations, publish new versions, turn them on or off, backfill, and re-evaluate a session | +| `dashboards:read`, `dashboards:write` | Read dashboards, or create, rename, and add queries to them | +| `queries:read`, `queries:write` | Read saved queries, or save and edit them | +| `queries:run` | Run one read-only SQL query and read the query schema | +| `alerts:read`, `alerts:write` | Read alerts, or create, edit, pause, delete, and test them | +| `issues:read` | Read issues, acknowledge them, and comment on them | +| `issues:create` | Open an issue on an alert | +| `issues:close` | Resolve and close issues | +| `audits:read`, `audits:write` | Read audits, runs, and findings, or create and edit audits and start a run | +| `code_fixes:read` | See how to fix an issue, and get its context for your own agent to fix | +| `code_fixes:write` | Start a fix in Failproof AI Cloud, which opens a pull request on your GitHub | +| `policies:read`, `policies:write` | Read policies, machines, and deployments, or publish, deploy, and roll back policies | + +A few tools need no permission because they read no organization data: building session and event links, and searching this documentation. + +An AI tool can never touch API keys, users, settings, or organization administration, and it can't send events. + +## Approving changes + +Writes ask you first if your client can show the prompt. You see what will change and select **Approve this change** to go ahead. If you decline or don't answer within about 4 minutes, nothing changes. Some clients stop waiting after a minute, so answer promptly. + + + A client that doesn't support prompts isn't asked, and a write runs as soon as the client makes the call. There, your client's own confirmation is the only one, so keep it on for write tools. + + +## Connected apps and revoking + +**Settings → Integrations → MCP** lists your connected apps in the current organization, with their permissions and last use. **Revoke** cuts an app off at once. Removing the server in your client also revokes the connection. + +You can have up to 5 connected apps per organization. Connecting the same app again replaces its earlier connection. + +## Self-hosted deployments + +Choose **Self-hosted Failproof AI Cloud** when connecting, and enter the address you sign in at. Your deployment must be reachable over public HTTPS. + +Tool calls and their results pass through the hosted Failproof AI gateway on their way between your AI tool and your deployment. The gateway doesn't store them. + +## What happens to your data + +Results go to the AI tool you connected, and that tool's provider handles them under its own terms. For each tool call, Failproof AI logs the tool's name, its outcome, how long it took, and the organization, never the arguments or results. See the [privacy policy](https://befailproof.ai/privacy/). + +## Troubleshooting + +| What you see | What to do | +| --- | --- | +| "Started in another browser" | Finish sign-in in the browser the client opened, with cookies allowed, and start again from the client | +| An error after **Allow** | The link works once and expires after 10 minutes, so start again from the client | +| A tool you expected is missing | You don't hold its permission in this organization. Ask an admin. You don't need to reconnect once you have it | +| The client keeps asking you to sign in | The connection was revoked, you left the organization, or it went unused for 90 days. Connect again | +| "You have 5 connected apps" | Revoke one under **Settings → Integrations → MCP**, then connect again | + +Still stuck? Email [support@befailproof.ai](mailto:support@befailproof.ai). diff --git a/docs/reference/openapi.json b/docs/reference/openapi.json index ab319110f..8975065d7 100644 --- a/docs/reference/openapi.json +++ b/docs/reference/openapi.json @@ -1229,7 +1229,7 @@ "Auth" ], "description": "Describe the API key making this request: the organization it belongs to and the permissions it holds. Requires no permission of its own — any valid key may describe itself, and only itself. Intended to be called once when provisioning a machine, so a bad key, a missing permission and a wrong organization can be told apart before anything is sent. A key that has just been revoked or has just expired may still be reported as valid for up to a minute.", - "operationId": "handler", + "operationId": "get_auth_introspect", "responses": { "200": { "description": "The key is valid. Reports its organization and effective permissions." @@ -2031,7 +2031,7 @@ ], "summary": "The distinct environment names seen in this organization's evaluations.", "description": "Returns a bare JSON array of strings, suitable for an environment filter.\nRead from the evaluations dataset rather than the event store, so a key with\n`evaluations:read` but not `events:read` can still populate the filter.\nCached per organization for 60 seconds, so a brand-new environment can take\nup to a minute to show up here.", - "operationId": "list_environments", + "operationId": "get_evaluations_environments", "responses": { "200": { "description": "A JSON array of environment names, sorted." @@ -2217,7 +2217,7 @@ ], "summary": "Ingest a batch of events.", "description": "The body is newline-delimited JSON — one event object per line, not a JSON\narray. Malformed lines are SKIPPED, not rejected: the response reports\n`accepted` and `skipped` counts and the status is 200 even when every line\nwas bad. A 5xx means \"retry the whole batch\"; duplicate events are collapsed\nserver-side, so retrying is safe.", - "operationId": "handler", + "operationId": "post_events", "requestBody": { "description": "One JSON event object per line.", "content": { @@ -2241,6 +2241,9 @@ }, "500": { "description": "Storage write failed — retry the batch." + }, + "422": { + "description": "An event exceeds the storage JSON row limit; reduce its payload." } }, "security": [ @@ -2283,7 +2286,7 @@ ], "summary": "List the environment names this organization has actually sent events from.", "description": "A JSON array of strings, alphabetically sorted — the values accepted by the\n`environment` filter on `/events`, `/events/summary` and `/sessions`. Derived\nfrom stored events, so an environment appears only once something has been\ningested under it, and results are cached for up to a minute: a brand-new\nenvironment can take that long to show up.\n\nEither `events:read` or `evaluations:read` grants this, so session-only keys\ncan populate the same filter.", - "operationId": "list_environments", + "operationId": "get_events_environments", "responses": { "200": { "description": "The organization's environment names, sorted." @@ -2869,7 +2872,7 @@ ], "summary": "Liveness probe.", "description": "The only endpoint on `/v1` that needs no credential — it reports that the\nprocess is answering, nothing about your data.", - "operationId": "handler", + "operationId": "get_health", "responses": { "200": { "description": "The server is answering." @@ -4017,7 +4020,7 @@ ], "summary": "Describe the tables a query may read.", "description": "Returns `{schema, tables: [{name, columns: [{name, type}]}]}` — the same\nlisting the query editor's autocomplete and schema browser are built on.\nTypes are normalised display names (`string`, `int`, `float`, `timestamp`,\n`uuid`, `bool`), with a trailing `?` when the column is nullable.\n\nThe shape is the same for every organization; only the rows a query over\nthese tables returns are yours.", - "operationId": "get_schema", + "operationId": "get_queries_schema", "responses": { "200": { "description": "The queryable tables and their columns." @@ -4528,7 +4531,7 @@ ], "summary": "The setting catalogue — key, type, and constraints, with no values.", "description": "Registry metadata only, so it reads nothing per-organization and returns the\nsame document for every caller. Use it to render typed inputs without\nre-declaring the catalogue; use `GET /settings` when you also need values.", - "operationId": "get_schema", + "operationId": "get_settings_schema", "responses": { "200": { "description": "The setting definitions, under `settings`." @@ -4946,6 +4949,103 @@ } ] } + }, + "/events/import": { + "post": { + "tags": [ + "Events" + ], + "summary": "Import one file of agent events into the caller's organization.", + "description": "The body is the file itself, optionally gzipped (detected from its bytes).\nThe format is detected from the content unless `format` names it: our event\nJSONL, a Claude Code transcript, or a Codex rollout. Transcripts are\nconverted exactly as the failproofaid collector converts them live, secrets\nare redacted, and every event is stamped `ingest_source: \"upload\"` and\n`uploaded_by: `. Sessions already present in the organization are\nskipped whole. `dry_run=true` reports what would happen and stores nothing.", + "operationId": "post_events_import", + "parameters": [ + { + "name": "format", + "in": "query", + "description": "`auto` (default), `agenteye`, `claude` or `codex`.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "path", + "in": "query", + "description": "The file's path relative to what was dropped, e.g.\n`-home-me-repo/0b5c….jsonl`. Claude and Codex take the session id from\nit, and a Claude subagent its parent session. A trailing `.gz` is ignored.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "environment", + "in": "query", + "description": "Environment for events that do not name one. Default `upload`.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "dry_run", + "in": "query", + "description": "Convert and report; store nothing.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "existing_before", + "in": "query", + "description": "Unix milliseconds. A session counts as already present only when it has\nrows ingested before this. Pass the dry run's `checked_at`, so the later\nfiles of a session this import created are not skipped as \"existing\".\nDefault: now.", + "required": false, + "schema": { + "type": "integer", + "format": "int64" + } + } + ], + "requestBody": { + "description": "One file: event JSONL, a Claude Code transcript or a Codex rollout. Gzip is accepted.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "File processed (or, with `dry_run`, previewed)." + }, + "400": { + "description": "Bad `format`, `path` or `environment`." + }, + "401": { + "description": "Missing, unknown, or disabled key." + }, + "403": { + "description": "The key lacks `events:add`." + }, + "413": { + "description": "The file exceeds MAX_BODY_BYTES after decompression." + }, + "422": { + "description": "Unrecognized file format, or a converted event exceeds the storage JSON row limit." + }, + "500": { + "description": "Storage failed — retry the file." + } + }, + "security": [ + { + "api_key": [] + } + ] + } } }, "components": { diff --git a/docs/reference/otel.mdx b/docs/reference/otel.mdx new file mode 100644 index 000000000..8c06ed529 --- /dev/null +++ b/docs/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Opt in to OTEL for coding agents, inspect delivery, and restore your previous settings." +icon: "radio" +--- + +`failproofai otel` configures optional OpenTelemetry reporting to FailproofAI Cloud. First connect your machine with `failproofai config` and ask an organisation admin to enable **Settings → OpenTelemetry**. + +Interactive setup asks about OpenTelemetry after the Cloud key field and the agent picker. The optional step defaults to No. Choose Yes to pick OTEL agents; the same enable code runs after the connection is written. Esc before setup applies changes nothing. Unattended setup, a supplied key, open-source mode, and keeping a saved connection do not opt you in. + +## Enable an agent + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +The supported agents are `claude`, `codex`, and `copilot` (VS Code). Copilot setup requires a VS Code executable or an installed Copilot extension. A leftover settings directory alone is not enough; setup skips Copilot when neither is found. + +`--local` sends to the local relay instead of directly to Cloud. Copilot uses the relay automatically because its settings cannot store the authentication header. + +The relay listens only on your machine. Your configured FailproofAI daemon picks up the change within seconds; you do not need to restart it. If another application owns the relay port, status reports it as off and the daemon keeps running. + + +Text capture is on by default. Add `--no-content` to omit prompts and tool details. Agent versions can expose different content controls; review what your agent exports before using it with sensitive data. + + +Codex exports conversation logs only, not internal runtime traces or metrics. An explicit `log_user_prompt = false` in your Codex configuration stays off; enable prints a note when it preserves that choice. + +### Choose one reporting path + +If transcript reporting is on for an agent, setup asks: + +> failproofai already sends Claude Code sessions to Cloud. Send them with OTEL instead? Transcript upload for Claude Code stops. + +The default is No. `--yes` accepts the switch without a prompt. Other agents and policy enforcement are unaffected. + +Codex setup waits for the daemon to confirm the collector change before writing its exporter settings. If confirmation times out, setup warns you to wait before starting Codex. + +Config v2 keeps the remembered tracing list at `agents.selected` (and detection history at `agents.seen`). The per-agent transcript preference remains at `collector.agents..sessions`, OTEL ownership at `otel.agents`, and relay settings at `collector.otlp.enabled` / `collector.otlp.port`. These separate keys keep old OTEL configurations readable: setup can change the tracing list without losing the transport preference or the state needed to restore your agent settings. + +## Inspect setup + +```bash +failproofai otel status +``` + +Status shows every agent, whether its settings are managed by FailproofAI, its destination, the organisation's ingest switch, relay state, and the last relay upload result. + +`unknown` for the organisation switch means the server did not provide it or could not be reached. It is not an error and does not prevent configuration on an older Cloud version. + +If Cloud does not support OTEL yet, the relay retains rejected exports instead of discarding them. If organisation ingest is off, `enable` writes nothing and exits with an error; ask an admin to turn it on first. + +## Print configuration for an application + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +The output is a shell environment block for an OTLP/HTTP exporter. Cloud output sets `OTEL_EXPORTER_OTLP_ENDPOINT` to Cloud's OTLP base, `https:///otel`, and the exporter appends `/v1/`; a per-signal variable such as `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` needs the full `https:///otel/v1/logs`. Local output points at the relay, `http://127.0.0.1:`. Cloud output includes the configured API key; treat it as a secret. Local output omits the key. To use local output, first enable a local agent so the relay is running. + +## Restore previous settings + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable restores only the settings FailproofAI wrote, keeps unrelated changes, and restores each agent's prior transcript-reporting choice. When the last managed local agent is disabled, the relay stops accepting exports. + +For Codex, disable also records `collector.agents.codex.sessions_resume_after` (epoch milliseconds). Existing rollout bytes are treated as delivered so sessions captured with OTEL are not uploaded again; later appends still flow through transcript reporting. + +Every command supports `--help`. See [OpenTelemetry in Cloud](/agenteye/opentelemetry) for application and coding-agent examples. diff --git a/docs/reference/overview.mdx b/docs/reference/overview.mdx index c98399bf8..52dcd2ab4 100644 --- a/docs/reference/overview.mdx +++ b/docs/reference/overview.mdx @@ -22,6 +22,9 @@ Choose the integration closest to where your agent already runs. Configure local capture, hooks, policies, audits, delivery, and machine state. + + Compare session evaluations with live policy review, then configure providers, keys, and modes. + Query and administer Cloud sessions, audits, issues, alerts, keys, users, and settings. diff --git a/docs/reference/policy-sdk.mdx b/docs/reference/policy-sdk.mdx index f31e027e8..649e2de57 100644 --- a/docs/reference/policy-sdk.mdx +++ b/docs/reference/policy-sdk.mdx @@ -88,6 +88,8 @@ customPolicies.add({ | `description` | No | Human-readable purpose shown in policy listings and decisions. | | `match.events` | No | Event types that invoke the policy. Omitting `match` invokes it for every available event. | | `fn` | Yes | Synchronous or asynchronous function that returns an `allow`, `instruct`, or `deny` result. | +| `authority` | No | `"hard"` (the default) or `"reviewable"`. Whether the Jev semantic evaluator may clear this policy's verdict. See [Policy authority](/policies/authority). | +| `reviewedBy` | No | The semantic checks Jev must all be asked, none of which may answer deny, before Jev may clear the verdict. A check that warns still clears it. Required for `"reviewable"`. | Filter tools inside `fn`. `match.toolNames` is not part of the public custom-policy type. @@ -285,6 +287,64 @@ Attribute the result to your custom policy under **Observe → policy**. A block Keep policy modules deterministic and quick. Avoid top-level network calls or server startup. Bound work inside `fn`, catch dependency failures, and choose deliberately whether that failure should allow or deny the operation. +## Jev checks + +A custom policy decides with code. A **Jev check** is a set of yes/no questions the Jev semantic evaluator answers about a tool call instead. A `reviewable` policy names checks in `reviewedBy`, and Jev may clear its verdict only through them — see [Policy authority](/policies/authority). Declare one with `semanticPolicies.add()`: + +```js +import { semanticPolicies } from "failproofai"; + +semanticPolicies.add({ + name: "prod-db-write", + title: "Wrote to the production database", + appliesTo: ["shell"], + mode: "deny", + userCanOverride: true, + probes: [ + { + id: "writes_data", + instructions: "Does this command insert, update or delete rows, or change a schema?", + criteria: { true: "It changes data or schema.", false: "It only reads." }, + }, + { + id: "production_target", + instructions: "Is the database it targets a production one, rather than a local or test copy?", + }, + ], + guidance: "Writes to the production database need a human. Ask before running this.", +}); +``` + + + A Jev check takes effect **only through a published pack**. `failproofai publish` is the one thing that reads `semanticPolicies.add()`; in a local policy file (`.failproofai/policies/`, `--custom`) it loads without an error, the hook log names it as ignored, and it is never asked, and a local policy whose `reviewedBy` names it stays hard. See [Jev checks in a pack](/policies/publish-a-pack#jev-checks-in-a-pack). + + +| Field | Required | Description | +| --- | --- | --- | +| `name` | Yes | Letters, digits, `.`, `_` and `-`, up to 128 characters, unique in the pack. What a `reviewedBy` names; reported as `semantic/`. | +| `title` | Yes | A past-tense phrase for what was caught. Up to 120 characters. | +| `appliesTo` | Yes | The tool classes Jev is asked about: one or more of `shell`, `write`, `read`, `network`, `other`. | +| `mode` | Yes | `"deny"` blocks on strong evidence and warns on moderate evidence. `"instruct"` only ever warns, so it can never keep a deny standing — pair a blocking policy with it alone and a clear leaves nothing that can deny. | +| `userCanOverride` | Yes | Whether the human's own explicit request clears the check. It decides whether words in a prompt can talk their way past it, so it has no default. | +| `probes` | Yes | 1 to 6 questions. **Every** probe must hold for the check to fire. | +| `probes[].id` | Yes | Matches `^[a-z][a-z0-9_]{0,31}$`, unique within the check. `exempt` and `user_asked` are reserved. | +| `probes[].instructions` | Yes | The question. Up to 600 characters. | +| `probes[].criteria` | No | `{ true, false }`: what a yes and a no mean, up to 300 characters each. Both halves or neither. | +| `exempt` | No | One more question in the probe shape (its `id` is ignored). When it holds, the check does not fire — the documented exceptions. | +| `precondition` | No | One name from the table below. Absent means the check is asked on every call its `appliesTo` covers. | +| `guidance` | Yes | Shown to the agent when the check fires, whether it blocks or warns — a `"deny"` check only warns on moderate evidence, so do not say the call is blocked. Up to 600 characters. | + +A precondition is a name, never code: a manifest cannot carry a function, and a downloaded pack must not decide what runs on every tool call. + +| Precondition | The check is asked only when | +| --- | --- | +| `always` | Always — the same as leaving it out. | +| `protected_branch` | The current git branch is `main`, `master`, `production`, `prod`, `release` or `trunk`. | +| `in_git_repo` | The call runs on a git branch. A detached `HEAD` counts as outside a repository. | +| `has_paths` | The call names at least one path. | +| `paths_outside_project` | Some path it names is outside the project. | +| `system_or_root_paths` | Some path it names is a system path or the filesystem root. | + ## API exports | Export | Purpose | @@ -293,10 +353,12 @@ Keep policy modules deterministic and quick. Avoid top-level network calls or se | `allow(reason?)` | Permit the operation. | | `instruct(reason)` | Permit the operation and provide guidance where supported. | | `deny(reason)` | Block the operation where supported. | +| `semanticPolicies.add(check)` | Declare a [Jev check](#jev-checks) for `failproofai publish` to put in a pack. | | `getCustomHooks()` | Return the policies currently registered in the module registry. | -| `clearCustomHooks()` | Clear that registry, primarily for tests and loaders. | +| `getSemanticRegistrations()` | Return the Jev checks currently declared, primarily for tests and loaders. | +| `clearCustomHooks()` | Clear both registries, primarily for tests and loaders. | -TypeScript exports `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, and `PolicyFunction`. +TypeScript exports `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, `PolicyFunction`, `PolicyAuthority`, `SemanticPolicyDeclaration`, `SemanticProbeDeclaration`, and `SemanticToolClass`. Publish a version, deploy it in observe mode, verify decisions, and move to enforcement. diff --git a/docs/reference/slack.mdx b/docs/reference/slack.mdx new file mode 100644 index 000000000..c4f2f6955 --- /dev/null +++ b/docs/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack app" +description: "Ask the Failproof Assistant from Slack, get charts in the thread, and approve changes with a button." +icon: "slack" +--- + +Ask the [Failproof Assistant](/sessions/assistant) from Slack. Mention the app in a channel, send it a direct message, or use `/failproof `. Answers use **your own** Failproof AI permissions, charts arrive in the thread, and anything that would change something asks you to approve it first. + +There is one official app. It works the same whether your Failproof AI Cloud is hosted or self-hosted. + + + Answers are generated by AI models and can be inaccurate. Check anything important against the linked source data. + + +## Connect a workspace + +You need the `settings:write` permission in Failproof AI and, in Slack, to be a workspace admin or owner, or the person adding the app. + + + + 1. Go to **Settings → Integrations** and select **Add to Slack**. + 2. Approve the app in Slack. + 3. Back in Failproof AI, confirm connecting the workspace to your organization. + + + 1. Add the app, then open its **Home** tab. + 2. Choose **Continue with FailproofAI Cloud**, or **Use my own URL** and enter the address you sign in at. + 3. Select the continue button, sign in, pick the organization, and confirm. The link works once and expires after 10 minutes. + + + +One workspace connects to one organization, and one organization to one workspace. + +Don't have an account? [Create one](https://app.befailproof.ai/login) first, then connect. + +## Who you are in Slack + +The first time you ask, the app works out which member you are: + +- **Automatically, by email**, when you are a full member of the connected workspace, your Slack email is confirmed, and exactly one member of the organization uses that email. +- **Otherwise**, you get a private **Link your account** button that opens Failproof AI and links your Slack user to your account. + +## Ask a question + +| Where | How | +| --- | --- | +| A channel | Mention the app. Reply in its thread to continue, with no mention needed | +| A direct message | Message the app | +| A group direct message the app is in | Mention it, then reply in its thread to continue | +| A Slack Connect channel | Mention the app | +| Any conversation the app is in | `/failproof ` starts a thread with the answer | +| `/failproof help` | See what the app can do | +| `/failproof status` | See which organization is connected and who you're linked as | +| `/failproof link` | See which Failproof AI account you're linked to | + +One thread is one conversation. Colleagues can mention the app in the same thread, and it answers each of them with their own permissions. Only the person who started the thread continues it without a mention. + +When the answer is data, the app posts a chart or a table with a link to open it in Failproof AI. + +## Approve changes + +Every change the assistant makes shows **Approve** and **Cancel** buttons first, and Slack asks once more before **Approve**. Only the person who asked can answer them, the buttons expire after 5 minutes, and the change is made with that person's permissions. + +From Slack, the assistant can change saved queries and dashboards, evaluations, alerts, audits, issues, and policies, and suggest code fixes, each if you hold the permission. It can't change API keys, users, or settings. + +## Link previews + +Failproof AI issue, session, and evaluation links pasted in Slack unfurl into cards on hosted Failproof AI Cloud. A card shows only what the person who triggered it can see. Links to a self-hosted address don't unfurl, though cards in the assistant's own answers still appear. + +## Slack Connect channels + +People from another workspace can use the app if they are members of the organization, after linking their account. Answers are visible to everyone in the conversation, including people who aren't members of your organization, so ask where everyone may see the answer. + +The app only answers once every other workspace in the channel has someone linked to the organization. Until then, it tells the person asking why. + +## Permissions the app asks for + +| Slack permission | Why | +| --- | --- | +| `app_mentions:read` | Know when someone mentions the app | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Receive direct messages and replies in the app's threads. The app ignores other messages, and it never reads a conversation's past messages | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Check what kind of conversation it's in, so it knows who can see an answer | +| `chat:write` | Post answers and approval buttons | +| `commands` | Provide `/failproof` | +| `files:write` | Post charts | +| `links:read`, `links:write` | Show previews of pasted Failproof AI links | +| `users:read`, `users:read.email` | Match you to your Failproof AI account, and show names | + +## Disconnect + +Go to **Settings → Integrations** and select **Disconnect**, use **Disconnect** on the app's **Home** tab, or remove the app from Slack. + +Any of these deletes the workspace's connection, bot token, linked accounts, and thread records. Past Slack conversations stay readable in the dashboard. The organization can then connect any workspace straight away. + +## Data and privacy + +Questions and answers are saved as conversations in your organization's dashboard, under the person who started the thread. Slack data is never used to train AI models. See the [privacy policy](https://befailproof.ai/privacy/) for what the app receives and how long it's kept. + +## Troubleshooting + +| What you see | What to do | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | A workspace admin opens the app's **Home** tab and chooses one | +| "This link expired or was already used." | Choose your Cloud again on the **Home** tab for a new link | +| "This org is already connected to a Slack workspace." | Disconnect it in settings first | +| "That Slack workspace is connected to another org." | Disconnect it from that organization first | +| "Link your account to use the assistant." | Select the button and confirm in Failproof AI | +| The app doesn't answer in a group direct message | Add the app to Slack again to grant its group permissions. Your connection is kept | +| "I won't post answers from your organization here" | Someone in that workspace who is a member of the organization mentions the app and links their account | + +Still stuck? Email [support@befailproof.ai](mailto:support@befailproof.ai). diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 4e9ea8dc2..a0c9a0e88 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -4,6 +4,12 @@ description: "Diagnose missing sessions, missing policies, failed delivery, and icon: "wrench" --- +Temporary network failures and HTTP 408, 429, or 5xx responses leave telemetry +eligible for automatic retry, even after a long outage. The daemon preserves the +batch until delivery is acknowledged. An `event_too_large` rejection needs a +smaller event payload before retrying. Files already marked `.poison` need +manual recovery; updating does not automatically resend them. + @@ -57,6 +63,30 @@ icon: "wrench" + + + + The machine connected and its hooks work, but **Observe → Events** stays empty and **Admin → enforcement** never shows its deployment as applied. The CLI and the Failproof daemon trust certificates differently. The CLI runs on Node and honours `NODE_EXTRA_CA_CERTS`. `failproofaid`, which sends events and pulls policies, trusts the certificates bundled with it plus the operating system's trust store, and ignores `NODE_EXTRA_CA_CERTS`. Install your CA in the system store on the machine. + + + ```bash + # Debian / Ubuntu + sudo cp company-ca.pem /usr/local/share/ca-certificates/company-ca.crt + sudo update-ca-certificates + # RHEL / Fedora + sudo cp company-ca.pem /etc/pki/ca-trust/source/anchors/ && sudo update-ca-trust + # macOS + sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain company-ca.pem + + # then restart the daemon, which loads trusted certificates at start + sudo systemctl restart failproofaid@$USER # Linux + sudo launchctl kickstart -k system/ai.failproof.failproofaid.$USER # macOS + ``` + + The daemon's log names the cause: `sudo journalctl -u failproofaid@$USER | grep UnknownIssuer` on Linux. `SSL_CERT_FILE` or `SSL_CERT_DIR` in the service's environment replaces the system store for the daemon, and the bundled certificates still apply. Batches that failed while the CA was untrusted are kept in `~/.failproofai/state/failed` and retried automatically, about hourly and when the daemon restarts. + + + @@ -162,6 +192,25 @@ icon: "wrench" + + + + Errors in the dashboard end with a short reference, for example `ref 4bf92f35`. It identifies that one request, and support can use it to find exactly what happened on the server. Copy it into your report as it appears. + + If a whole page fails to load, the error page shows a `digest` instead. Include that. + + + Human-readable `fp` errors end with the same `ref`. With `--json`, the error object carries the full `request_id`: + + ```bash + fp --json sessions --since 24h + ``` + + + When an upload fails, the daemon's log names a `request_id` and a `batch_id`: on Linux, `sudo journalctl -u failproofaid@$USER | grep batch_id`. Every attempt gets its own `request_id`; the `batch_id` stays the same across retries, so it ties the attempts of one batch together. Include both. + + + -When contacting support, include the CLI version, harness, environment, relevant session or deployment ID, and the output of `failproofai config --status` with secrets removed. +When contacting support, include the CLI version, harness, environment, relevant session or deployment ID, any `ref` or `request_id` from the error, and the output of `failproofai config --status` with secrets removed. diff --git a/docs/ru/admin/product-analytics.mdx b/docs/ru/admin/product-analytics.mdx new file mode 100644 index 000000000..f0257c052 --- /dev/null +++ b/docs/ru/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Аналитика использования" +description: "Телеметрия использования, которую отправляет Failproof AI Cloud о себе, что никогда не собирается и как это отключить." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud отправляет телеметрию использования **о самом ПО** его разработчикам. Она никогда не включает данные ваших агентов. На самостоятельно размещаемой установке она включена по умолчанию, и вы можете её отключить. + +## Что собирается + +Каждое событие содержит пять измерений и ничего, что идентифицирует человека: + +| Измерение | Пример | Что это | +| --- | --- | --- | +| `product` | `agenteye` | Какой продукт это отправил | +| `component` | `dashboard`, `server`, `cli` | Какая часть продукта это отправила | +| `app_version` | `0.0.1-beta.81` | Сборка, которую вы используете | +| `deployment_kind` | `self_hosted` | Является ли это установкой клиента, нашей демонстрацией, нашей QA или машиной разработчика | +| `org_id` | UUID | В какой организации произошло действие, в виде непрозрачного идентификатора | + +Помимо этого, события записывают **что использовалось, никогда не то, что в нём было**: какая страница была просмотрена (как шаблон маршрута, например `/:org/sessions/:id`, никогда не реальный URL), сколько фильтров какого типа было применено, успешно ли действие, и сколько времени это заняло. + +Приложение Slack записывает подключения и отключения рабочих пространств, привязки аккаунтов, заданные вопросы, опубликованные диаграммы, решения по одобрению и сбои по фиксированной категории. Оно никогда не включает ID рабочего пространства Slack, пользователя или канала, электронную почту, вопросы, ответы, SQL или токены. + +### Название вашей организации + +Наряду с непрозрачным `org_id` мы один раз записываем название вашей организации, URL-слаг и адрес панели управления в запись организации, а не в каждое событие. Это позволяет нам определить, какому аккаунту принадлежит закономерность при анализе внедрения или расследовании проблемы, которую вы сообщили. Это единственный фрагмент идентифицирующей информации о вас, который отправляет продукт. + +### Ваши итоги использования + +Сервер отчитывается об итогах измеренного использования каждой организации — те же цифры, которые вы видите на странице использования. Это только подсчёты: события, сеансы, агенты, среды, запуски оценки, оценки, аудиты, сохранённые запросы, панели управления, оповещения, проблемы, ключи API и члены, плюс даты окна измерения. Они не содержат идентификаторов, имён или текста запроса и приходят независимо от того, вошёл ли кто-нибудь в систему. + +## Что никогда не собирается + +- **Нет подсказок, ответов модели или содержимого события** — ни в виде текста, префикса или хеша +- **Нет идентификаторов сеанса, агента или трассировки** +- **Нет названий оценок оценивающего** +- **Нет сообщений об ошибках, текста исключений или тел ответов** — только код состояния и категория из фиксированного списка +- **Нет аргументов инструмента, SQL или текста запроса** +- **Нет данных подключённого приложения.** Подключение или отзыв клиента MCP отправляет максимум количество разрешений, никогда не название приложения или какой-либо токен +- **Нет адресов электронной почты** +- **Нет URL-адресов реферера или строк запроса** +- **Нет записи экрана, захвата DOM или отслеживания щелчков и движения курсора** + +## Отключите на самостоятельно размещаемой установке + +Установите `DO_NOT_TRACK=1` как для панели управления, так и для сервера. Они решают отдельно, поэтому установка только на одном оставляет другой в состоянии отправки отчётов. Перезагрузите сервер, чтобы изменение вступило в силу. + +README вашего выпуска описывает другие параметры отключения и как подтвердить отключение телеметрии. + +## Один ping при отключении + +Если вы отключите с помощью параметра продукта вместо `DO_NOT_TRACK`, панель управления может отправить **один анонимный ping** с вероятностью 1 из 1000 при запуске каждого процесса. Это говорит нам, сколько операторов отключают телеметрию. Он не содержит идентификаторов: нет организации, пользователя, имени хоста, URL или IP, только продукта, компонента, версии, типа развёртывания и причины. Отключённый сервер ничего не отправляет. + +Он никогда не отправляется при использовании `DO_NOT_TRACK`, поэтому это параметр для использования, если ваша политика запрещает любую исходящую телеметрию. + +## Куда она идёт + +На PostHog (`us.i.posthog.com`) по TLS на порту 443. Это один хостнейм, поэтому вы также можете заблокировать его с помощью одного правила исходящего трафика. + +О том, как мы обрабатываем личную информацию в целом, см. [политику конфиденциальности](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/ru/agenteye/opentelemetry.mdx b/docs/ru/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..fe968d646 --- /dev/null +++ b/docs/ru/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "Отправляйте телеметрию кодирующего агента и приложения в FailproofAI Cloud через OTLP." +icon: "radio" +--- + +OpenTelemetry позволяет отправлять трассировку агента, логи и метрики в FailproofAI Cloud, используя стандартный протокол OTLP/HTTP. Это опционально. Ваши существующие интеграции FailproofAI продолжают работать без его включения. + +## Включите прием данных для вашей организации + +Администратор организации открывает **Settings → OpenTelemetry** и включает прием данных. Используйте API ключ Cloud с разрешением `events:add` — такое же разрешение используется для отчетности агента. + +Если прием отключен, Cloud отклоняет OTLP экспорты, поэтому `failproofai otel enable` ничего не изменит, и ваши агенты будут отправлять сессии обычным способом. Выполните `failproofai otel status`, чтобы проверить переключатель организации, и попросите администратора его включить. + +## Подключите кодирующего агента + +Подключите вашу машину с помощью `failproofai config`, затем выберите агента: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +Команда установки поддерживает Claude Code, Codex и Copilot и выбирает Cloud или локальное аутентифицированное реле по мере необходимости. Copilot использует локальное реле автоматически. Запустите настроенный демон FailproofAI перед использованием реле. + +Если FailproofAI уже отправляет транскрипты сессий агента, установка спросит, переключить ли этот агент на OTEL. По умолчанию ответ — нет. Согласие остановит загрузку транскриптов для этого агента; это не изменит применение политик и отчетность от других агентов. + +## Подключите приложение + +Используйте инструментацию OpenTelemetry вашего приложения с этими переменными окружения: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +Конечная точка — это OTLP база Cloud `https://app.befailproof.ai/otel`; ваш экспортер добавляет `/v1/traces`, `/v1/logs` или `/v1/metrics` самостоятельно. Переменные для отдельных сигналов, такие как `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, используются как есть, поэтому им нужен полный путь, например `https://app.befailproof.ai/otel/v1/logs`. + +Замените `` на ваш API ключ. Держите секрет подальше от истории shell, записей экрана и закоммиченной конфигурации. Для настроенной машины `failproofai otel env --service my-agent` выведет блок с существующим ключом. Его вывод содержит учетные данные. + +Cloud принимает OTLP/HTTP экспорты для трассировки, логов и метрик в формате protobuf или JSON, включая сжатые gzip запросы. Он не принимает OTLP/gRPC. + +Метрики подтверждаются для совместимости экспортера, но не сохраняются и не отображаются. Поддерживаемые трассировки агента и логи кодирующего агента становятся сессиями; поля, которые агент не экспортирует, остаются отсутствующими. + +## Захватывайте текст приглашения + + +Захват текста может включать приглашения, аргументы инструментов и другой чувствительный контент. `failproofai otel enable` включает это. Добавьте `--no-content`, чтобы отключить захват приглашений и деталей инструментов. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Для агента, которого вы настраиваете вручную, используйте его собственные средства управления захватом контента: + + + + Добавьте эти переменные в окружение вашего агента рядом с блоком приложения выше: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Установите обе переменные контента в `0`, чтобы избежать захвата приглашений и деталей инструментов. + + + В пользовательской конфигурации Codex используйте его параметры OTEL: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Содержимое беседы Codex находится в логах; оставьте внутренние трассировки времени выполнения и метрики отключенными. Codex использует полную конечную точку, которую вы предоставляете. Установите `log_user_prompt` в `false`, чтобы исключить приглашения; команда установки сохранит явное значение `false`. + + + Используйте параметры телеметрии Gemini с локальным реле: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI не поддерживается `failproofai otel enable`. Настройте его вручную с вашим собственным аутентифицированным сборщиком. Установите `logPrompts` в `false` для отсутствия захвата приглашений. + + + Используйте эти параметры пользователя VS Code: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Выполните `failproofai otel enable copilot`, чтобы включить аутентифицированное реле. Установите `captureContent` в `false`, чтобы пропустить контент. + + + +## Проверьте или отмените настройку + +Реле сохраняет телеметрию при временных сбоях сети и сервера и повторяет попытки после восстановления. Постоянное отклонение `400`, включая событие, которое слишком велико для сохранения, требует исправления полезной нагрузки. Реле сохраняет отклоненный пакет для проверки, а не повторно отправляет его. + +После `401` или `403` замените учетные данные на ключ, предоставляющий `events:add` для той же организации. Переподключение не автоматически отправляет заново сохраненные OTLP экспорты, отклоненные по причине учетных данных; попросите вашего оператора восстановить эти пакеты. Сохраняйте их в исходной организации. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Статус различает параметры, управляемые FailproofAI, и телеметрию, которую вы настроили в другом месте. Отключение восстанавливает предыдущие управляемые параметры и предыдущий выбор загрузки транскриптов агента. + + + Параметры команд, настройка локального реле и устранение неполадок. + \ No newline at end of file diff --git a/docs/ru/evaluations/jev.mdx b/docs/ru/evaluations/jev.mdx new file mode 100644 index 000000000..b81593b1a --- /dev/null +++ b/docs/ru/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev оценки" +description: "Используйте Jev для оценки завершённой сессии по вопросу с известными ответами." +icon: "list-checks" +--- + +Оценка Jev читает **завершённую сессию** и даёт оценку от 0 до 1. Используйте её, когда ответ известен заранее, например «Выразил ли клиент срочность?» или «Насколько разочарован был клиент?» Это помогает найти закономерности между запусками; оно не останавливает вызов инструмента. Для решений, принятых **перед** запуском инструмента, используйте [Jev политики](/ru/policies/jev). + +## Создайте одну на панели управления + +1. Откройте **Analyze → eval authoring** и выберите **new eval**. +2. Опишите один вопрос и его возможные ответы. Например: «Обещал ли агент возврат средств перед проверкой политики возврата? Ответьте да или нет.» Выберите **draft** и проверьте, что результат — это оценка классификатора. +3. [Протестируйте её](/ru/evaluations/test) на недавних сессиях, затем [разверните](/ru/evaluations/deploy). Новые завершённые сессии получат оценку; [заполните истории](/ru/evaluations/deploy#score-sessions-you-already-have), если вам также нужна история. + +![Форма совместного авторства оценок, где вы описываете вопрос с фиксированным ответом, проверяете черновик и развёртываете после тестирования. Показанный пример — это оценка кода; вопрос Jev использует тот же процесс авторства.](/images/dashboard/eval-authoring-draft.png) + +Ассистент может выбирать между кодом, классификацией Jev и [судьёй](/ru/evaluations/judge). Проверьте его выбор перед развёртыванием. Jev выдаёт оценку без развёрнутого обоснования; выберите судью, если вам нужно объяснение. Типы вопросов и ограничения оценок см. в [справочнике по оценкам Jev](/ru/reference/jev-evaluations). + +## Прочитайте оценки + +Откройте **Observe → Evaluations** для построения графика результата по агентам и времени. Из терминала Cloud CLI может читать те же результаты: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI читает результаты; авторство и развёртывание происходят на панели управления. Фильтры см. в [справочнике Cloud CLI](/ru/reference/cloud-cli#evaluations). \ No newline at end of file diff --git a/docs/ru/evaluations/judge.mdx b/docs/ru/evaluations/judge.mdx new file mode 100644 index 000000000..617ec4fa7 --- /dev/null +++ b/docs/ru/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "Судьи на основе LLM" +description: "Оценивайте сессии по критериям, которые не может измерить код — корректность, тон, соответствие агента политике — описав, как должно быть, и позволив модели прочитать диалог." +icon: "scale" +--- + +Размещённая оценка на Python может считать и сравнивать: сколько вызовов инструментов, сколько ошибок, сколько времени длилась сессия. Но она не может сказать, был ли ответ *правильным*, вежлив ли был ответ или проверил ли агент политику перед действием. + +**Судья на основе LLM** может. Вы описываете, как должно быть в простых словах, и модель читает сессию и возвращает оценку от 0 до 1 с обоснованием. + + +Судья стоит один вызов модели на каждую сессию, на которой он работает, а оценка кода стоит ничего. Используйте судью только для вопросов, которые требуют *понимания* диалога — и дайте ему условие, чтобы он работал только на релевантных сессиях. + + +## Что мне выбрать? + +| Вопрос | Используйте | +| --- | --- | +| Вызвал ли инструмент дважды? | код | +| Сколько было ошибок? | код | +| Была ли сессия менее 30 секунд? | код | +| Выразил ли клиент срочность? | [классификатор](/ru/evaluations/jev) | +| Насколько расстроен был клиент? | [классификатор](/ru/evaluations/jev) | +| Был ли ответ действительно правильным? | **судья** | +| Был ли ответ грубым или пренебрежительным? | **судья** | +| Проверил ли он политику возврата перед тем, как обещать возврат? | **судья** | + +Правило: **считаемое → код, ответы, которые можно перечислить заранее → [классификатор](/ru/evaluations/jev), требует объяснения → судья.** Судья — это тот, кто пишет текст о том, что он увидел; используйте его, когда число заставит кого-то спросить «почему?». + +Вам не нужно решать заранее. Опишите, что вы хотите измерить, и помощник выберет, затем скажет вам, что он выбрал и почему. Вы можете переключиться. + +## Создайте судью + +1. Перейдите в **Analyze → eval authoring** и выберите **new eval**. +2. Опишите, что вы хотите оценить, и выберите **draft**. +3. Проверьте **criteria**, **threshold** и **condition**, затем разверните. + +### Criteria + +Одно или два предложения, написанные как требование, а не вопрос: + +> Ассистент не должен обещать или одобрять возврат, не проверив предварительно политику возврата. + +Будьте конкретны о том, что вызовет *ошибку*. «Был ли ответ хорошим?» даст вам число, которое ничего не значит; предложение выше даст вам число, на основе которого можно действовать. + +### Threshold + +Оценка, при которой или выше которой сессия считается пройденной. `0.7` — разумная начальная точка. Полная оценка от 0 до 1 всегда сохраняется, поэтому порог определяет только прошёл/не прошёл — вы можете увидеть распределение и отрегулировать. + +### Condition + +То же самое условие Python, что и в любой другой оценке, и здесь оно гораздо важнее. Без него судья работает на **каждой** сессии вашей организации, с вызовом модели за каждую: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +Панель инструментов предупредит вас, если вы развернёте судью без условия. Иногда это правильно — низкообъёмный агент, который вы хотите полностью оценить — но это должно быть решением, а не случайностью. + +## Что видит судья + +Диалог, как обороты, новейшие первыми, если сессия длинная: + +- что сказал пользователь +- что ответил ассистент +- **каждый инструмент, который вызвал агент, и что вернул этот вызов, по порядку** + +Последняя часть — это то, что делает вопрос «сделал ли он X *перед* Y» справедливым. Неудачный вызов инструмента показывается как ошибка, поэтому «восстановился ли он грациозно после ошибки» тоже работает. + +Очень длинные сессии урезаны, чтобы поместиться в контекст модели. Когда это происходит, обоснование явно об этом говорит — вы никогда не увидите оценку части сессии, представленную как оценка всей сессии. + +## Чтение результатов + +Судья создаёт **score** как любая другая оценка с оценкой, поэтому он отображается на графиках, фильтруется и срабатывает предупреждения тем же способом. Наряду с числом он сохраняет **reasoning** судьи — абзац, объясняющий, что он видел. Прочитайте это в первую очередь, когда оценка вас удивляет; обычно это либо действительно интересная сессия, либо признак того, что критерии нужно уточнить. + +Оценки стабильны для однозначных случаев, но не бит-в-бит детерминированы. Рассматривайте одну пограничную оценку как приглашение прочитать сессию, а не как вердикт. + +## Ограничения + +- **Тестирование недоступно.** Сухой прогон не имеет назначения сессии, а это назначение — то, что разрешает расходовать ваш бюджет модели — поэтому нечего взимать со скидки. Разверните при узком условии и прочитайте первые несколько результатов. +- **Backfill недоступен.** Заполнение кода оценки за месяцы истории бесплатно; это с судьёй потратит весь ваш бюджет за минуты. +- **Редактирование критериев публикует новую версию.** Старые и новые оценки не сравнимы, поэтому они хранятся отдельно, а не смешиваются в один тренд. +- **Судья всегда создаёт оценку**, никогда метрику или утверждение. + +## Когда бюджет иссякнет + +Судьи расходуют бюджет модели вашей организации. Когда он исчерпан, оценки судей остаются с понятной причиной, а не молча терпят неудачу, и **оценки кода продолжают работать нормально**. Увеличьте бюджет, и они возобновятся на следующей сессии. \ No newline at end of file diff --git a/docs/ru/policies/authority.mdx b/docs/ru/policies/authority.mdx new file mode 100644 index 000000000..49572b211 --- /dev/null +++ b/docs/ru/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Полномочия политики" +description: "Какие вердикты политики может отменить семантический оцениватель Jev, а какие являются окончательными." +icon: "scale" +--- + +Когда вы настраиваете [проверку политики Jev](/ru/policies/jev) через FailproofAI Cloud или свой собственный ключ, каждый контролируемый вызов инструмента оценивается запущенными вами политиками и Jev, который определяет, что на самом деле делает вызов и просил ли человек, введший задачу, это сделать. **Полномочия** каждой политики определяют, что происходит, когда оба механизма не согласны. + +Без настроенного Jev полномочия не имеют эффекта. Каждая политика работает в точности так же, как всегда. + +## Жесткие и подлежащие пересмотру + +- **Жесткая** — это значение по умолчанию. Отказ жесткой политики или инструкция являются окончательными: Jev не может их отменить, и жесткий отказ останавливает вызов без ожидания Jev. +- **Подлежащая пересмотру** означает, что Jev может отменить вердикт политики, но только через семантические проверки, которые политика указывает в `reviewedBy`. Вердикт отменяется только, когда **каждая** названная проверка была применена к этому вызову и каждая либо не обнаружила ничего, либо записала, что пользователь просил об этом. Проверка, которая **сработала** — обнаружила проблему — без просьбы пользователя сохраняет блокировку, даже если её собственный вердикт только предупреждение. Проверка, о которой Jev не спросили, потому что она не применима к этому инструменту, никогда ничего не отменяет, независимо от того, что сказали остальные. Одно смягчение считается согласием: когда вызов является шагом задачи, которую дал пользователь, и не выходит дальше, Jev преобразует отказ в предупреждение, и это предупреждение отменяет блокировку политики и именно это сообщается агенту. + +Политика является подлежащей пересмотру только, если выполняются все эти условия: + +1. Она объявляет `authority: "reviewable"`. +2. `reviewedBy` — это непустой список, и каждый элемент — это проверка Jev, которую объявляет установленный пакет. Failproof AI не поставляет никаких проверок Jev: [шестнадцать ниже](#semantic-policy-names) поступают из `failproofai policies add FailproofAI/jev-policies`. Без пакета, объявляющего проверки, каждая политика жесткая. +3. Это не `alwaysOn`. Охрана, которая препятствует отключению Failproof AI агентом, всегда жесткая. + +Все остальное жесткое: отсутствующее поле, неправильно написанное значение, пустой или неправильно сформированный `reviewedBy`, или имя, которое не является проверкой, которую эта машина может выполнить. Неизвестное имя делает всё объявление жестким, а не пропускается, потому что `reviewedBy` означает "все эти проверки должны быть выполнены, и ни одна из них не может отказать", и пропуск имени позволил бы Jev отменить политику на основе меньшего количества проверок, чем вы запросили. + +После настройки Jev, Failproof AI регистрирует предупреждение, когда отказывает объявлению `reviewable`, один раз на процесс. Без Jev ничего не говорится, потому что полномочия тогда ничего не решают. `failproofai publish` отказывается собирать пакет, содержащий такое объявление, поэтому автор пакета узнает об этом до того, как кто-либо его установит. Он оценивает `reviewedBy` в сравнении с проверками, которые объявляет пакет, и против шестнадцати имен `FailproofAI/jev-policies` в противном случае. + +## Где объявляются полномочия + +Каждый способ, которым политика попадает на машину, имеет одно место, которое определяет её полномочия: + +| Источник | Объявлено в | По умолчанию | +| --- | --- | --- | +| Встроенные политики | Таблица ниже | Жесткая, если не указана как подлежащая пересмотру | +| Ваши собственные файлы политик | `authority` и `reviewedBy` на `customPolicies.add` | Жесткая | +| Пакеты политик | Запись каждой политики в манифесте пакета (`failproofai-pack.json`) | Жесткая | +| Облачные управляемые политики | Назначение политики в активном развертывании | Жесткая. Развертывания это пока не устанавливают, поэтому сегодня каждая облачная политика жесткая. | + +Для пакета или облачной управляемой политики поля, установленные внутри кода политики, игнорируются; манифест или назначение решает. Пакет может описывать только свои собственные политики: имена его политик не могут содержать `/` и регистрируются под собственным префиксом пакета, поэтому никакой манифест не может отметить встроенную политику или политику другого пакета как подлежащую пересмотру. Политика, которую код пакета регистрирует без объявления в манифесте, жесткая. + +Два пакета или две облачные управляемые политики, чей код идентичен на уровне байтов, совместно используют один артефакт и загружаются как одна политика. Такая политика является подлежащей пересмотру только, если каждый из них объявляет её подлежащей пересмотру, и Jev затем должна отменить каждую проверку, которую называет любой из них. Если какой-либо из них объявляет её жесткой или вообще не объявляет, она остаётся жесткой. Порядок, в котором указаны пакеты или политики, никогда не имеет значения. + +Большинство машин получают встроенные политики из пакета `FailproofAI/policies` и читают их полномочия из манифеста этого пакета. Записи подлежащие пересмотру ниже вступают в силу, когда устанавливается выпуск пакета, который их содержит; старый выпуск их не содержит, поэтому каждая политика в нём остаётся жесткой. + +## Объявите полномочия в своей собственной политике + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` копирует оба поля в манифест пакета, поэтому политика, опубликованная как пакет, сохраняет полномочия, которые дал её автор. Она отказывается собирать пакет, если объявление не было бы выполнено: значение отличное от `"hard"` или `"reviewable"`, `reviewedBy`, который не является списком имен, или имя, которое не является проверкой — одна из собственных [проверок Jev пакета](/ru/policies/publish-a-pack#jev-checks-in-a-pack) когда он объявляет какие-либо, встроенная проверка в противном случае. + +## Встроенные политики + +Подлежащие пересмотру только там, где семантическая политика действительно охватывает ту же проблему. Все остальные встроенные политики жесткие. + +Охват проблемы необходим, но недостаточен, и оба способа ошибки тихие: + +- **Проверка, которая никогда не применяется** делает блокировку постоянной. `reviewedBy` — это конъюнкция и проверка, которая не была применена, никогда не отменяет, поэтому политика, связанная с проверкой, условие которой не срабатывает для форм, которые соответствуют политике, никогда не может быть отменена вообще. +- **Проверка, которая применяется, но не срабатывает** отвечает "нет проблемы", и отсутствие проблемы отменяет. Поэтому связь с проверкой, которая не моделирует формы вашей политики, не рассматривает политику — она выключает её ровно для входных данных, которые проверка не понимает. + +Семантическая политика в режиме инструкции никогда не может ответить отказом, но она всё ещё может сохранить блокировку: когда она срабатывает и пользователь не просил вызов, политика, которую она пересматривает, не отменяется. Шесть проверок `FailproofAI/jev-policies` только инструктажные — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` и `external-data-egress` — и [таблица ниже](#semantic-policy-names) дает режим каждой проверки. Вопрос, который нужно задать: **"остаётся ли что-нибудь, что может отказать"**: отмена никогда не должна оставлять проблему без защиты. Движок применяет этот тест на каждый вызов. Предупреждение, на которое никто не согласился, не является отменой, потому что до вызовов инструментов предупреждение не останавливает агента. И когда проверка, которая *может* отказать, предупреждает — её доказательства оказались ниже её линии отказа — и пользователь не просил вызов, ничего не отменяется на этом вызове и каждый regex отказ остаётся. + + +**Проверка, которая набирает баллы чуть ниже своей линии срабатывания, не сохраняет нижнюю границу.** Правило выше нуждается в проверке, которая *срабатывает* (доказательство ≥ 0,7). Когда каждая релевантная проверка находится чуть ниже этого, ничего не срабатывает, рецензенты отвечают "нет проблемы", и отмена подлежащей пересмотру политики совершается. Измерено в реальном времени в режиме принудительного исполнения: неполученное чтение `/etc/shadow` (`secret-exposure` 0.69, `read-outside-workspace` 0.37, который моделирует только пути в домашнем каталоге) и `set | curl -d @- …` после "follow SETUP.md" (`env-secrets-dump` 0.66, `credential-exfiltration` 0.65 с `sends_out` 0.97) оба были разрешены, в то время как регулярный уровень их отклоняет. Пороги были откалиброваны на помеченном корпусе и не были переизмерены против этого; пока это не будет сделано, держите политику **жесткой**, где прохождение одной из этих форм важнее, чем её ложные блокировки. + + +| Политика | Полномочия | Рассмотрено | Почему | +| --- | --- | --- | --- | +| `protect-env-vars` | подлежащая пересмотру | `env-secrets-dump`, `secret-exposure` | Шаблон срабатывает на любую ссылку на переменную; Jev спрашивает, будут ли фактически напечатаны значения секретов. | +| `block-env-files` | подлежащая пересмотру | `secret-exposure` | Шаблон соответствует любому пути `.env`, включая шаблоны; Jev спрашивает, будут ли прочитаны или записаны реальные значения секретов. | +| `block-read-outside-cwd` | подлежащая пересмотру | `read-outside-workspace` | Измерено как шумная на реальном трафике; Jev спрашивает, прочитаны ли содержимое файлов вне проекта. Чтение, которое просил пользователь, или то, в котором проверка ничего не находит, отменяется; неполученное чтение, которое она отмечает, сохраняет блокировку. | +| `warn-git-amend` | подлежащая пересмотру | `git-history-rewrite` | Исправление неотправленного коммита — обычное дело; вред в переписывании истории, которую могут быть загрузили другие. | +| `warn-destructive-sql` | подлежащая пересмотру | `database-destruction` | Jev также спрашивает, является ли целевой объект реальной базой данных, а не одноразовой тестовой. | +| `warn-global-package-install` | подлежащая пересмотру | `system-modification` | Та же проблема: изменение машины вне проекта. | +| `block-failproofai-commands` | жесткая | | `alwaysOn` самозащита. Никогда не подлежит пересмотру. | +| `block-rm-rf` | подлежащая пересмотру | `destructive-deletion` | Эвристика глубины пути неправильно определяет `rm -rf node_modules`; Jev спрашивает, является ли удаляемое восстанавливаемым. `rm -rf /` сохраняет оба зонда истинными. | +| `block-sudo` | жесткая | | Эскалация привилегий. | +| `block-curl-pipe-sh` | жесткая | | Запускает код, загруженный из интернета. | +| `block-push-master` | жесткая | | Отправляет непосредственно в защищённую ветку. | +| `block-work-on-main` | жесткая | | `commit-on-protected-branch` охватывает ровно эту проблему, но только в режиме инструкции, поэтому она никогда не может ответить отказом, и никакая другая проверка её не охватывает. | +| `block-force-push` | подлежащая пересмотру | `git-history-rewrite` | Зонд Jev является надмножеством шаблона и учитывает `--force-with-lease`; что отменяет — это force-push вашей собственной ветки. | +| `block-secrets-write` | подлежащая пересмотру | `secret-exposure` | Совпадение пути не привязано, поэтому `src/auth/credentials.ts` перехватывается; Jev спрашивает, пишется ли реальный материал ключей. | +| `block-kubectl` | подлежащая пересмотру | `production-infra-change` | Отклоняет весь CLI, включая подкоманды только для чтения; Jev спрашивает, изменяет ли вызов и является ли целевой объект production. | +| `block-terraform` | подлежащая пересмотру | `production-infra-change` | То же: отменяет `terraform plan` и `validate`. | +| `block-aws-cli` | подлежащая пересмотру | `production-infra-change` | То же: отменяет `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | подлежащая пересмотру | `production-infra-change` | То же: отменяет `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | подлежащая пересмотру | `production-infra-change` | То же: отменяет `az account show`. | +| `block-helm` | подлежащая пересмотру | `production-infra-change` | То же: отменяет `helm list`, `helm status`. | +| `block-gh-pipeline` | жесткая | | Запускает конвейеры, слияния и изменения секретов. | +| `warn-git-stash-drop` | жесткая | | Нет семантической проверки, которая охватывает отбрасывание скрытой работы. | +| `warn-git-clean` | жесткая | | `destructive-deletion` охватывает проблему, но явно не может на ней срабатывать: `git clean` не указывает путь, поэтому её зонд `irreplaceable` не имеет чего судить и отвечает низко, и доказательство — минимум по зондам политики. Проверка, которая применена и не срабатывает, отменяет вердикт, поэтому связь здесь отключит политику. | +| `warn-all-files-staged` | жесткая | | Нет семантической проверки, которая охватывает то, что ловит широкий `git add`. | +| `warn-schema-alteration` | жесткая | | `database-destruction` охватывает удаление данных, не изменение схемы. | +| `warn-package-publish` | жесткая | | Публикация необратима и нет семантической проверки, которая её охватывает. | +| `prefer-package-manager` | жесткая | | Соглашение команды, а не суждение о безопасности. | +| `warn-large-file-write` | жесткая | | Порог размера, не суждение, которое может сделать Jev. | +| `warn-background-process` | жесткая | | Нет семантической проверки, которая охватывает отделённые процессы. | +| `warn-repeated-tool-calls` | жесткая | | Считает вызовы; Jev не может считать. | +| `sanitize-jwt` | жесткая | | Редактирует вывод инструмента; не вентиль вызова инструмента. | +| `sanitize-api-keys` | жесткая | | Редактирует вывод инструмента; не вентиль вызова инструмента. | +| `sanitize-connection-strings` | жесткая | | Редактирует вывод инструмента; не вентиль вызова инструмента. | +| `sanitize-private-key-content` | жесткая | | Редактирует вывод инструмента; не вентиль вызова инструмента. | +| `sanitize-bearer-tokens` | жесткая | | Редактирует вывод инструмента; не вентиль вызова инструмента. | +| `require-commit-before-stop` | жесткая | | Вентиль завершения сеанса, не вентиль вызова инструмента. | +| `require-push-before-stop` | жесткая | | Вентиль завершения сеанса, не вентиль вызова инструмента. | +| `require-pr-before-stop` | жесткая | | Вентиль завершения сеанса, не вентиль вызова инструмента. | +| `require-no-conflicts-before-stop` | жесткая | | Вентиль завершения сеанса, не вентиль вызова инструмента. | +| `require-ci-green-before-stop` | жесткая | | Вентиль завершения сеанса, не вентиль вызова инструмента. | + +## Имена семантических политик + +Это проверки, которые `FailproofAI/jev-policies` объявляет, и значения, которые `reviewedBy` принимает после его установки. Failproof AI сам не поставляет ни одной из них: без этого пакета (или другого, объявляющего эти имена), ни одна политика, которая их называет, не может быть подлежащей пересмотру. Каждая — это проверка, на которую Jev отвечает о вызове инструмента перед ней. **Режим** — это то, что может ответить проверка: проверка `deny` блокирует на сильных доказательствах, в то время как проверка `instruct` только когда-либо предупреждает. Любая сохраняет отказ политики в силе, когда она срабатывает и пользователь не просил вызов. **Пользователь может переопределить** говорит, отменяет ли явный запрос человека это. + +Jev спрашивает ровно [проверки Jev](/ru/policies/publish-a-pack#jev-checks-in-a-pack), которые объявляют установленные пакеты, и эти имена принимает `reviewedBy`. Имя, которое два пакета объявляют по-разному, не почитается ни для одного. Одно из этих шестнадцати имен, объявленное пакетом не установленным из репозитория FailproofAI, игнорируется в этом пакете: его версия никогда не спрашивается и не конкурирует с собственной FailproofAI, поэтому пакет от третьей стороны не может стать проверкой, которая отменяет политики основного пакета, или отключить одну из этих проверок. Нечитаемый список пакетов или пакет, каждая проверка которого не используется, оставляет Jev без вопросов. + +| Имя | Режим | Пользователь может переопределить | Что проверяет Jev | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | да | Постоянное удаление данных, которые не могут быть восстановлены. | +| `production-infra-change` | deny | да | Изменение работающей инфраструктуры. | +| `git-history-rewrite` | deny | да | Переписывание или отбрасывание общей истории git. | +| `push-to-protected-branch` | instruct | да | Прямая отправка в защищённую ветку. | +| `commit-on-protected-branch` | instruct | да | Прямое коммитирование в защищённую ветку. | +| `secret-exposure` | deny | да | Чтение или копирование учётных данных. | +| `credential-exfiltration` | deny | нет | Отправка секретов или приватных файлов с машины. | +| `remote-code-execution` | deny | да | Запуск кода, загруженного из интернета. | +| `privilege-escalation` | deny | да | Запуск с повышенными привилегиями. | +| `database-destruction` | deny | да | Уничтожение или массовое изменение данных БД. | +| `read-outside-workspace` | instruct | да | Чтение файлов вне проекта. | +| `agent-config-tampering` | deny | нет | Изменение собственной конфигурации безопасности агента. | +| `system-modification` | instruct | да | Изменение системы вне проекта. | +| `env-secrets-dump` | instruct | да | Печать секретов окружения. | +| `external-destructive-action` | deny | да | Необратимое действие через внешний инструмент. | +| `external-data-egress` | instruct | да | Отправка приватных данных во внешний инструмент. | \ No newline at end of file diff --git a/docs/ru/policies/jev-byok.mdx b/docs/ru/policies/jev-byok.mdx new file mode 100644 index 000000000..eba9ae420 --- /dev/null +++ b/docs/ru/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev evaluator (bring your own key)" +description: "Позвольте классификатору Jev от TypeSafe оценивать вызовы инструментов ваших агентов выше жёсткого порога regex через вашу собственную конечную точку и ключ Jev." +icon: "key-round" +--- + +Политики regex сопоставляют строки. Они не могут отличить `rm -rf build/`, которую вы просили, от `rm -rf ~`, которая просочилась в план, поэтому они блокируют слишком много в одном месте и слишком мало в другом. **Jev**, классификатор TypeSafe, читает вызов относительно того, что вы на самом деле просили, и отвечает на набор вопросов да/нет о нём в один быстрый запрос. + +Когда у вас есть собственная конечная точка Jev и ключ, Failproof AI спрашивает Jev о каждом вызове инструмента **наряду с** политиками regex, никогда вместо них: + +- Отказ **жёсткой** политики окончателен. Jev не может его отменить. Каждая политика жёсткая, если она явно не отмечена как проверяемая и не указывает проверки Jev, которые её охватывают, поэтому пользовательская, пакетная или облачная политика, которая ничего не говорит, жёсткая, и всегда включённая защита самозащиты всегда жёсткая. +- Отказ **проверяемой** политики может быть отменён, но только когда Jev было задано вопрос о точной проблеме, которую охватывает эта политика, и он ответил «здесь ничего нет» или «пользователь попросил это». Проверка, которая находит проблему реальной, когда пользователь не просил вызов, сохраняет отказ — даже когда собственный вердикт проверки всего лишь предупреждение, потому что перед вызовом инструмента предупреждение не останавливает агент. И когда эта проверка может отказать (утечка секретов, экфильтрация учётных данных, разрушительное удаление, …), ничто не очищается для этого вызова. +- Блокировка все ещё может стать **предупреждением**, когда вызов является шагом задачи, которую вы дали, и не заходит дальше: Jev смягчает свой собственный отказ в предупреждение, и это предупреждение — указывающее, что на самом деле не так с вызовом — заменяет блокировку политики. +- Jev также может предупредить или отказать самостоятельно, для вреда, который regex не описывает. +- Если Jev не может ответить (тайм-аут, лимит скорости, ошибка сервера, нет кредитов, неожиданная версия модели), этот вызов получает результат regex, в точности как без Jev. +- Jev никогда не делает вызов более разрешающим, чем ваши политики в одиночку, если он не прочитал весь вызов и не был спрошен о точной проблеме. Что-либо меньшее — вызов слишком большой для отправки целиком, подозреваемая инъекция — отменяет разрешения и сохраняет каждый отказ. + + +Без конфига Jev ничто не меняется: хуки запускают политики regex в точности как всегда. Конфиг — это весь opt-in. + + + +На FailproofAI Cloud? Вам не нужен собственный ключ: машина, подключённая с ключом, несущим `jev:evaluate`, может использовать Jev в плане вашей организации. См. [Jev через FailproofAI Cloud](/ru/policies/jev-cloud). + + +## Выберите поставщика + +Jev доступен через пять маршрутов. Принесите ключ для любого из них. + +| Поставщик | `--provider` | Конечная точка | Модель по умолчанию | Примечания | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Точное закрепление версии. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Запросы маршрутизируются только на конечные точки без хранения данных, без отката на другого поставщика. Сообщает устаревшую версию, такую как `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Именует Jev только псевдонимом, поэтому отвечающая версия записывается как непроверённая. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Требует `--account-id`. Измерено около шести вызовов в секунду на ключ перед HTTP 429. | +| Ваша собственная конечная точка | `custom` | `/systemone` | `jev-1.13.0` | Любая конечная точка, которая принимает тело запроса TypeSafe и сообщает, какая модель ответила. Только `https`; обычный `http://localhost` принимается только в режиме shadow. | + + +С собственной функцией bring-your-own-key Vercel неудачный запрос молча повторяется с учётными данными Vercel. Если вам нужно, чтобы каждый вызов был выставлен и виден только на вашем собственном аккаунте TypeSafe, используйте TypeSafe напрямую. + + +## Настройте это + +Одна команда, конечная точка и ключ: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL выбирает поставщика + +Вам не нужно называть поставщика: **хост** URL — это который это. + +| Хост URL | Поставщик | Также требует | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| любой другой хост | `custom` | — URL, который вы дали, это базовый URL | + +Из этого следуют три вещи: + +- **URL, который является собственным API поставщика, не пишет переопределение.** `--url https://api.typesafe.ai/v1` создаёт в точности конфиг, который бы создал `--provider typesafe`. Дайте другой путь или хост на известном поставщике, и он сохраняется как базовый URL, как бы это сохранил `--base-url`. +- **`--provider` всё ещё переопределяет вывод**, что позволяет вам добраться к прокси, который говорит на API поставщика с хоста вашего собственного: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **`--provider`, который противоречит хосту, отказывается**, не угадывается. `--provider openrouter --url https://api.typesafe.ai/v1` ничего не пишет и объясняет почему: два написания не согласны о том, где ваш ключ вот-вот будет отправлен. Та же пара отказывается от `jev setup --base-url` и от настроек Jev панели управления. (`--provider custom` не является противоречием — это означает «обработайте этот URL как сам себя» — кроме хоста Cloudflare, чьей конечной точке для каждого аккаунта пользовательский маршрут не может добраться.) + +`--url` проверяется в точности как `baseUrl` в файле конфига, и отказывается в тех же словах: `https`, или простой `http://localhost` только в режиме shadow. + +### Ключ + +Передайте его с `--key-stdin`, или запустите команду в терминале без неё и вставьте ключ при замаскированном приглашении. В любом случае он идёт прямо в файл конфига и никогда не печатается обратно. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` принимает те же флаги и является расширенной версией всего этого: `setup --provider ` где вы предпочли бы назвать поставщика, чем URL. + +### `--token`, и какова его стоимость + +`--token ` помещает ключ в командную строку, что является самым быстрым способом настроить машину и единственным написанием, которое оставляет ключ где-либо кроме файла конфига: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Аргумент командной строки находится в файле истории вашей оболочки впоследствии, и в то время как команда выполняется, она находится в списке процессов — читаема из `/proc` чем-либо, работающим как вы. `setup` говорит об этом каждый раз при использовании `--token`. Предпочитайте `--key-stdin` на машине, которой вы делитесь, в записанной сессии, или где-либо, где файл истории синхронизируется; поверните ключ, который вы передали таким образом, если это важно. + + +`--token`, `--key-stdin` и `--key-from-env` взаимно исключающие: дайте один. + +Затем отправьте один небольшой живой запрос, чтобы проверить ключ, конечную точку и какой Jev ответил: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` выходит 1 и говорит об этом в его названии, когда ответ приходит после тайм-аута (каждый хук вернулся бы к regex как `timeout`) или отвечает на его контрольный вопрос неправильно. + +Хуки читают конфиг при каждом вызове инструмента, поэтому он применяется со следующего. Нечего перезапускать, с демоном или без. + +## Проверьте, что оно делает + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` показывает поставщика, конечную точку, модель, режим, файл конфига и его разрешения, и никогда не ключ. Ниже он суммирует недавнюю активность: сколько вызовов Jev оценил, как часто он возвращался к regex и почему, его задержку, и какие проверяемые политики он очистил. + +## Режим shadow + +`enforce` — это значение по умолчанию. Чтобы смотреть Jev без позволения ему что-либо изменять в любом решении, переключитесь на `shadow`: Jev всё ещё спрашивается и его вердикты записываются, но результат regex — это то, что применяется. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` сохраняет конфиг — конечную точку и ключ — и перестаёт спрашивать Jev: хуки запускают политики regex в точности как без конфига, и `failproofai jev status` говорит «off (switched off)». Переключитесь обратно с `--mode shadow` или `--mode enforce`. + +Повторный запуск `setup` для того же поставщика сохраняет сохранённый ключ, поэтому переключение режима — это один флаг. Переключение поставщика начинается заново и спрашивает ключ этого поставщика. То же самое для `--base-url`, который перемещает запросы на другой хост: сохранённый ключ отправляется только на хост, для которого он был дан, или на собственный API его поставщика. + +## Файл конфига + +Всё живёт в одном файле, `~/.failproofai/jev.json`, написанном `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Поле | Значение | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` или `custom` — или `failproofai`, чей ключ поступает из подключения FailproofAI Cloud вместо этого файла (см. [Jev через FailproofAI Cloud](/ru/policies/jev-cloud)). | +| `apiKey` | Отправлено как `Authorization: Bearer `. | +| `baseUrl` | Требуется для `custom`; заменяет базовый API поставщика иначе. Должен быть `https`. Простой `http` на `localhost` принимается только с `mode: shadow`: ничто не аутентифицирует локальный порт, поэтому пока ваш прокси выключен, любой процесс на машине, включая оцениваемый агент, может ответить вместо него. | +| `accountId` | Только Cloudflare: 32 строчных шестнадцатеричных символа. | +| `model` | Заменяет ID модели по умолчанию поставщика. Версионный ID должен назвать Jev 1.13. Значение, по форме напоминающее API ключ, отказывается (и не повторяется обратно), поэтому ключ, вставленный в `--model`, никогда не сохраняется или не отправляется как модель. | +| `timeoutMs` | Как долго вызов инструмента ждёт Jev перед использованием результата regex. 100–10000, по умолчанию 3000. | +| `mode` | `enforce` (по умолчанию), `shadow`, или `off` (сохраните конфиг, не запускайте Jev). | + +Три правила его защищают: + +- **Только владелец.** Оно написано с разрешениями `0600`. Копия, которую любой другой пользователь или группа может читать или писать, **отказывается**, и хуки возвращаются к regex до тех пор, пока вы не запустите `chmod 600 ~/.failproofai/jev.json` или `setup` снова. Директория также проверяется: `~/.failproofai` не должна быть **записываемой** кем-то ещё, потому что любой, кто может писать туда, может заменить файл, какими бы ни были его собственные разрешения. `setup` убирает те биты записи, если их находит. `failproofai jev status` говорит когда конфиг был отказан и показывает конечную точку, которую файл называет: кто-то ещё мог изменить его, поэтому проверьте что это ваш перед тем как `chmod`. Повторный запуск `setup` на таком файле переносит его сохранённый ключ только на собственный API поставщика; любая другая конечная точка, которую он называет, нужен ключ снова (`--key-stdin`), или `--base-url default` чтобы отправлять запросы обратно поставщику. +- **Только глобально.** Репозиторий не может включить Jev, направить его на другую конечную точку или выбрать его модель: `.failproofai/jev.json` внутри проекта игнорируется, и поставщик, URL, модель и ID аккаунта читаются только из этого файла — никогда из среды, которую параметры агента репозитория могут установить. (`FAILPROOFAI_HOME` не является способом обойти это: он перемещает всю директорию failproofai, включая ваши политики, а не переопределяет Jev самостоятельно.) +- **Только ключ может поступить из среды.** Если файл не имеет `apiKey`, `FAILPROOFAI_JEV_API_KEY` поставляет его для этой сессии (`setup --key-from-env` пишет такой файл). Это никогда не заменяет ключ, который файл держит, и не может включить Jev без файла. Где переменная не установлена, Jev просто выключен для этой оболочки: `failproofai jev status` говорит об этом, выходит 0 и оставляет конфиг в покое (`status --json` сообщает `"status": "key-missing"` с `"reason": "no-env-key"`). Демон `failproofaid` не видит окружение вашей оболочки, поэтому на машине, настроенной с `failproofai config`, сохраняйте ключ в файле. + +## Какой Jev отвечает + +Пороги решений Failproof AI были откалиброваны на Jev 1.13, поэтому ответ используется только когда он поступает из этого семейства: `jev-1.13.x`, или `typesafe/jev-1.13-` OpenRouter. Когда поставщик именует Jev только псевдонимом и не сообщает версию (Vercel и Cloudflare когда это не говорят), ответ используется и записывается как непроверённый. Пользовательская конечная точка должна сообщить модель, которая ответила; единственное исключение — это неверсионированное имя `--model`, которое вы для неё настроили, которое, повторённое обратно, записывается как непроверённое таким же образом. Ответ, сообщающий любую другую версию, или ответ `custom`, не сообщающий ничего, не используется: этот вызов возвращается к regex с причиной `model-mismatch`. + +## Когда Jev не может ответить + +Каждое из этих возвращается к результату regex для этого вызова и записывается с его причиной, которую `failproofai jev status` суммирует: + +| Причина | Причина события | +| --- | --- | +| `timeout` | Нет ответа в пределах `timeoutMs`. | +| `http-429` | Поставщик ограничил скорость ключа. | +| `rate-limited` | Собственный ограничитель Failproof AI удержал вызов перед отправкой: 5 запросов в секунду, в порциях до 5, и ни один момент после того как поставщик ответит `429`. Не поставщик. | +| `http-500`, `http-502`, `http-503`, … | Ошибка сервера у поставщика. Точный статус записывается. | +| `out-of-credits` | HTTP 402: аккаунт поставщика не имеет оставшихся кредитов. | +| `provider-refused` | HTTP 402 от Cloudflare читая «Model execution failed (Payment error)»: поставщик отказал запустить модель на этот запрос. Обычно не выставление счётов, поэтому пополнение кредитов не поможет. | +| `http-401`, `http-403` | Ключ был отказан. | +| `http-404` | Ничто не обслуживается в `/systemone`, поэтому базовый URL неправильный — `/systemone` добавляется к нему, и каждый поставщик обслуживает его в корне своей версии. `failproofai jev models` показывает что конечная точка обслуживает. | +| `network` | Конечная точка не могла быть достигнута. | +| `http-301`, `http-302`, `http-307`, `http-308` | Конечная точка ответила перенаправлением. Перенаправления никогда не следуют, поэтому ответ приходит только когда-либо из URL в вашем конфиге; установите `--base-url` на финальный URL. | +| `malformed` | Конечная точка ответила, но не с ответом Jev — тело, которое не JSON, или одно без ответов в нём. | +| `cloudflare-error`, `cloudflare-incomplete` | Конверт Cloudflare сообщил об отказе, или задача, которая не завершилась. | +| `model-mismatch` | Другая версия Jev, чем 1.13 ответила, или конечная точка `custom` не сказала какая модель ответила. | +| `request-cut` | **Не сбой.** Jev ответил; ему было показано только часть вызова, поэтому его ответ ничего не очистил. См. [Когда Jev ответил, но не на весь вызов](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` может также показать несколько редких причин, таких как `upstream-error` (ответ нёс собственную ошибку поставщика) или `config`, и суммирует любую причину, которую он не может назвать как `other`. + +`request-cut` находится в этой таблице потому что `failproofai jev status` суммирует это с остальным, и потому что это тоже оставляет каждый отказ стоять. Это единственная причина здесь, которая ничего не говорит о вашем поставщике: запрос прибыл и Jev на него ответил. В отличие от каждой строки выше неё, этот ответ все ещё считается — собственный отказ или предупреждение Jev применяется поверх результата regex а не отбрасывается. Поэтому период их означает вызовы достигают оценщика слишком большие чтобы отправить целиком, а не что ваша конечная точка нездорова, и пополнение кредитов или изменение URL не подвинет число. + +## Когда Jev ответил, но не на весь вызов + +Ещё две вещи могут случиться, и ни одна не является Jev неспособным ответить. Обе о том, сколько вызова, или разговора, уместилось в один запрос. + +**Часть самого вызова не уместилась.** Вызов инструмента отправляется внутри фиксированного бюджета, и огромный — очень большой `Write`, огромное тело MCP, команда заполненная до лимита — отправляется с тем что уместилось. Jev всё ещё отвечает, и его ответ все ещё считается: его собственный отказ или предупреждение применяется как обычно. Что оно не может сделать — это **очистить** что-либо, потому что вердикт дан на части вызова не является вердиктом на вызове. Поэтому каждый отказ политики стоит, и вызов записывается как откат с причиной `request-cut`, которую `failproofai jev status` суммирует наряду с причинами выше. Правило, которое это вам даёт: создание большего вызова может стоить ему его очистки, и никогда не может купить одну. + +**Сообщение не уместилось.** Длинная подсказка, которую вы вставили, последнее сообщение агента, или подсказка, которую хранилище этого оценщика уже ограничивало. **Ничто не меняется**: вызов судится, очищается и записывается в точности как любой другой, и не считается откатом. Длина того что вы печатаете никогда не решает вердикт, и разрез не может произвести согласие: где подсказка прибыла уже ограниченной, «вы не просили это» перестаёт быть заключением, которое может быть выведено из неё вообще, вместо того чтобы стать одним. + +Линия между ними — кто писал текст. Вызов агента, и правило, которое позволило бы его длине вычесть серьёзность, было бы правилом, которое агент может использовать; ваша подсказка — это ваша, и рассмотрение её длины как сигнала только когда-либо наказало вставку спецификации или трассировки стека. + +## Что покидает машину + +Для каждого вызова инструмента, который Jev оценивает, один запрос идёт вашему поставщику, несущему: + +- сам вызов инструмента, с секретами такими как API ключи, маркеры-носители и назначения `KEY=` отредактированными; +- недавние подсказки, которые вы печатали, с текстом, который добавило впряжение агента удалённым; +- последнее сообщение агента перед вашей последней подсказкой, отмеченное как написанное агентом; +- факты вычисленные локально, такие как находится ли путь внутри проекта — тот что была сессия в её первом рассмотренном вызове, [приколота для сессии](/ru/reference/jev-intent#the-project-root) — и текущая ветка git. + +Оно идёт только на конечную точку в вашем конфиге, под вашим ключом. + +## Выключите это + +```bash +failproofai jev remove +``` + +Это удаляет `~/.failproofai/jev.json`. С следующего вызова инструмента хуки запускают политики regex в точности как раньше. Хранилища для каждой сессии под `~/.failproofai/state/semantic/` (записанные подсказки в `sessions/`, корни проектов в `roots/`) оставляются на месте и стареют. Чтобы перестать спрашивать Jev но сохранить конфиг, используйте `failproofai jev setup --mode off` вместо этого. + +## Справочник команд + +| Команда | Результат | +| --- | --- | +| `failproofai jev --url --key-stdin` | Настройте это в одну команду; поставщик поступает из хоста URL | +| `failproofai jev --url --token ` | То же, с ключом в командной строке — ваша история и список процессов видят его | +| `failproofai jev setup --provider --key-stdin` | Напишите конфиг из ключа канализированного на stdin | +| `failproofai jev setup --provider ` | То же, спрашивая ключ при замаскированном приглашении | +| `failproofai jev setup --key-from-env` | Не сохраняйте ключ; читайте `FAILPROOFAI_JEV_API_KEY` за сессию | +| `failproofai jev setup --mode shadow` | Переключите режим (`enforce`, `shadow` или `off`), сохраняя сохранённый ключ | +| `failproofai jev setup --model ` / `--base-url ` | Переопределите модель или базовый API; `default` очищает переопределение | +| `failproofai jev setup --timeout-ms ` | Измените бюджет на вызов | +| `failproofai jev status [--json]` | Конфигурация, разрешения и недавняя активность; никогда ключ | +| `failproofai jev test [--json]` | Один живой запрос: задержка и версия которая ответила | +| `failproofai jev models [--provider ] [--url ] [--json]` | ID моделей, которые сообщает `/models` этой конечной точки, отмечая настроенную | +| `failproofai jev remove` | Удалите конфиг; Jev выключен | \ No newline at end of file diff --git a/docs/ru/policies/jev-cloud.mdx b/docs/ru/policies/jev-cloud.mdx new file mode 100644 index 000000000..334d169f6 --- /dev/null +++ b/docs/ru/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev через FailproofAI Cloud" +description: "Позвольте Jev оценивать вызовы инструментов ваших агентов через FailproofAI Cloud по тарифу вашей организации без собственного аккаунта TypeSafe или ключа." +icon: "cloud" +--- + +[Jev](/ru/policies/jev-byok), классификатор TypeSafe, анализирует каждый вызов инструмента в соответствии с тем, что вы действительно запросили, и выносит решение на основе ваших политик, но не вместо них. Через **FailproofAI Cloud** подключённая машина использует Jev с тем же ключом, с которым она уже подключена: без аккаунта TypeSafe, без второго ключа, без конечной точки для настройки. Каждый вызов учитывается в рамках существующего лимита тарифа вашей организации. + +Всё, что делает Jev, остаётся неизменным по сравнению с [конфигурацией с собственным ключом](/ru/policies/jev-byok): жёсткие политики остаются окончательными, отказ проверяемой политики очищается только когда Jev был спрошен о том же самом вопросе, а любой сбой откатывается к результату регулярного выражения для этого вызова. + + +Требуется **failproofai 1.0.8-beta.0** или позже. 1.0.7 не имеет Jev, хотя версионно стоит выше бета-версий 1.0.7. Без конфигурации Jev ничего не меняется: хуки запускают политики регулярных выражений точно так же, как всегда. + + +## Включение + +1. **Создайте ключ с Jev.** На панели управления FailproofAI Cloud откройте **Keys → Create key** и выберите предустановку **machine**. Она предоставляет три разрешения, необходимые машине: `events:add` (отправить активность), `policies:pull` (получить политики) и `jev:evaluate` (Jev, учитывается в тарифе вашей организации). Ключ не может иметь `jev:evaluate` без двух других. +2. **Подключите машину** с этим ключом: + + ```bash + failproofai config --token + ``` + + Если ваша организация запускает свой собственный FailproofAI Cloud вместо размещённого сервиса, добавьте его адрес: `--url https://` (или экспортируйте `FAILPROOFAI_CLOUD_URL`). Без этого ключ проверяется по размещённому сервису и подключение не удаётся. Если сертификат этого хоста выдан приватным УЦ, установите УЦ в хранилище системных сертификатов машины (например с `update-ca-certificates`), не только в `NODE_EXTRA_CA_CERTS`: демон, отправляющий события и получающий политики, читает системное хранилище. См. [Troubleshooting](/ru/reference/troubleshooting). + +Это всё. Подключение сохраняет ключ и, когда машина ещё **не имеет** конфигурацию Jev, включает Jev через FailproofAI Cloud в режиме **shadow**: Jev спрашивают о каждом управляемом вызове инструмента и его решения записываются, но результат вашей политики — это то, что применяется. Вывод об этом говорит: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**С `--no-transcripts` подключение не включает Jev.** Jev отправляет каждый проверенный вызов инструмента и недавний запрос на FailproofAI Cloud, что больше, чем требует подключение, передающее только решения. Ключ всё ещё сохраняется, и вывод говорит, что Jev доступен и как его включить: + +```bash +failproofai jev setup --provider failproofai +``` + +Это также не отключает Jev. Если файл `jev.json` машины уже запускает Jev через FailproofAI Cloud, он остаётся без изменений, и вывод говорит, что Jev всё ещё отправляет каждый проверенный вызов инструмента и недавний запрос, и что `failproofai jev setup --mode off` его отключает. + + +Подключение **никогда не перезаписывает** существующий `~/.failproofai/jev.json`. Если вы уже используете собственную конечную точку Jev, она продолжит использоваться, и вывод говорит, что файл остался как настроен — и, когда этот файл оставляет Jev отключённым (отклонено или переключено), это говорит и как исправить. Чтобы переключить эту машину на FailproofAI Cloud, запустите `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce или off + +Начните с shadow, посмотрите, что бы сделал Jev на странице политик, затем позвольте ему действовать: + +```bash +failproofai jev setup --mode enforce # Решения Jev применяются: может очистить отказ проверяемой политики и добавить свой +failproofai jev setup --mode shadow # Jev спрашивают и записывают; результат вашей политики применяется +failproofai jev setup --mode off # Сохранить конфигурацию, перестать спрашивать Jev +``` + +Тот же переключатель находится на локальной панели управления: **Settings → Jev** имеет переключатель включения/выключения и shadow/enforce. Он переписывает только режим. Хуки читают конфигурацию при каждом вызове инструмента, поэтому изменение применяется со следующего вызова без перезагрузки. + +## Проверка работы + +```bash +failproofai jev status +failproofai jev test +``` + +`status` показывает провайдера как **FailproofAI Cloud**, хост Cloud, к которому подключена машина, режим и источник ключа как **FailproofAI Cloud connection**, никогда сам ключ. Когда `jev.json` FailproofAI Cloud на месте, но Jev не может запуститься, он говорит почему: + +| `status` говорит | `status --json` | Значение | +| --- | --- | --- | +| **off — для подключения FailproofAI Cloud этой машины не сохранён ключ Jev** | `key-lacks-jev` | Машина подключена, но для неё не сохранён ключ Jev: ключ не имеет `jev:evaluate` или подключение не могло его подтвердить. Запустите `failproofai config --token ` снова с тем же ключом; если у него нет разрешения, используйте ключ **machine**. | +| **off — эта машина не подключена к FailproofAI Cloud** | `not-connected` | На этой машине нет подключения FailproofAI Cloud, к которому мог бы принадлежать ключ Jev. | + +После `failproofai config --disconnect` больше нет `jev.json` FailproofAI Cloud (если только он не был переключен на отключение, что сохраняется), поэтому `status` просто сообщает, что Jev отключён. `status --json` содержит те же факты (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), также когда конфигурация отсутствует или отклонена. `permissions` всегда из `jev.json`; отказ о `credentials.json` добавляет `credentialsPermissions`, и `fix` когда одна команда это исправляет. `test` отправляет один живой запрос и сообщает его задержку и версию Jev, которая ответила. Он выходит с кодом 1 и говорит об этом в названии, когда ответ приходит после тайм-аута хука (хуки запишут `timeout`) или отвечает на проверочный вопрос неправильно. + +Панель **Settings → Jev** на панели управления также показывает **подключение FailproofAI Cloud**: в какую организацию сообщает машина и есть ли в её ключе Jev. Это читается из собственных файлов машины без сетевых вызовов. + +## Что попадает на страницу политик + +Машина уже отправляет активность своих хуков на FailproofAI Cloud (`events:add`). С включённым Jev запись каждого управляемого вызова также указывает, какой оценщик запустился, что решил Jev, какие политики он очистил, почему откатился когда это произошло, его задержку и модель, которая ответила — решения, коды и имена, никогда команду или ваш запрос. На странице **Policies** вашей организации: + +- вызов, решение которого принял сам Jev (режим enforce), отнесён к **Jev**, и когда решающая проверка пришла из пакета, запись также называет этот пакет и его версию; +- в режиме shadow отказ или предупреждение Jev появляется как **would-have**, рядом с наблюдаемыми развёртываниями; +- политики, которые Jev очистил или очистил бы в режиме shadow, подсчитываются по политике. + +## Когда Jev не может ответить + +Каждое из этого откатывается к результату вашей политики для этого вызова и записывается с причиной: + +| Причина | Причина | +| --- | --- | +| `out-of-credits` | Ваша организация использовала лимит своего тарифа. | +| `http-401`, `http-403` | Ключ был отозван или не имеет `jev:evaluate`. Переподключитесь с ключом, который имеет. | +| `http-429` | FailproofAI Cloud ограничивает скорость Jev для вашей организации. До истечения затребованного времени ожидания (его `Retry-After`, максимум 60 секунд) машина ничего не отправляет и каждый вызов откатывается сразу. Задержанные вызовы записываются как `http-429` или как `rate-limited` когда собственное ограничение скорости машины их держит первым. | +| `http-429` (дневной лимит) | Ваша организация использовала дневной лимит вызовов Jev: **10 000 за UTC день**, если только оператор вашего FailproofAI Cloud не установил другой лимит. Каждый вызов откатывается до сброса счётчика в 00:00 UTC; машина всё ещё спрашивает максимум один раз в минуту, поэтому замечает сброс в течение минуты. `failproofai jev test` говорит "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev отклонил запрос этого вызова, обычно потому что вызов инструмента содержал плотный текст (base64, hex, минифицированный код) сверх лимита токенов Jev. Этот вызов откатывается каждый раз; это не авария. | +| `http-502` | Jev недоступен прямо сейчас. | +| `http-503` | Этот Cloud не может служить Jev для вашей организации: нет модельного шлюза, организация ещё не подготовлена или шлюз неработающий. Спросите администратора; хуки спрашивают снова максимум один раз в минуту. | +| `http-404` | Этот FailproofAI Cloud ещё не обслуживает Jev. | +| `timeout` | Нет ответа в течение `timeoutMs` (по умолчанию 3000). | +| `model-mismatch` | Ответила другая версия Jev, не 1.13. | + +## Где живёт ключ и куда он идёт + +- Ключ сохраняется один раз в `~/.failproofai/credentials.json` (`0600`, в каталоге только для владельца), рядом с другими учётными данными FailproofAI Cloud. `jev.json` не содержит ключ для этого маршрута; написанный туда делает конфигурацию недействительной. +- Если `credentials.json` имеет **любое** разрешение для кого-то, кроме вас (группа или другие, чтение или запись), или его каталог может быть **написан** кем-то, кроме вас, это **отклонено**, не читается, и Jev отключен до тех пор, пока вы не исправите: `chmod 600` на файле, `chmod 700` на каталоге (или переподключитесь, что переписывает файл в `0600` и делает каталог только для владельца). Каталог, который другие могут только читать, подходит; который они могут писать, позволяет им обменять файл. +- Ключ считается только пока подключение, с которым он пришёл, на машине: политика или учётные данные отчётности для того же FailproofAI Cloud **с тем же ключом**, в том же файле. Оставленный ключ Jev без одного игнорируется и Jev остаётся отключённым. Это происходит когда более старый failproofai's `config --disconnect` оставляет ключ Jev на месте (он не знает его удалять), или когда более старый failproofai's `config --token` подключается с другим ключом, который на FailproofAI Cloud может принадлежать другой организации. Чтобы переключить Jev обратно на включение, подключитесь снова с ключом **machine**. +- Ключ отправляется только на начало Cloud, на котором он был проверен. `jev.json`, указывающий куда-то ещё, отклонён. +- **Агент на машине может его прочитать.** `credentials.json` только для владельца и агент запускается как этот владелец. Чтение собственных файлов failproofai разрешено намеренно (только изменение их заблокировано `block-failproofai-commands`), поэтому единственное, что стоит между агентом и этим файлом — это `block-read-outside-cwd` — *проверяемая* политика — и из сессии, начатой в вашем домашнем каталоге, ничего. Ключ с `jev:evaluate` тратит лимит Jev вашей организации (до дневного лимита) откуда бы он ни использовался, поэтому относитесь к машинному ключу как к любым другим учётным данным расходов: если агент мог его прочитать, отключите его на странице Keys и переподключитесь с новым. +- Только ваши глобальные файлы это решают. Репозиторий не может включить Cloud Jev, указать его на другое место или предоставить его ключ, и `FAILPROOFAI_JEV_API_KEY` игнорируется для этого маршрута. +- Для каждого вызова, который Jev оценивает, один запрос идёт на FailproofAI Cloud с тем, что [страница bring-your-own-key](/ru/policies/jev-byok#what-leaves-the-machine) указывает (секреты отредактированы). FailproofAI Cloud пересылает его на TypeSafe и не логирует или не сохраняет. + +## Отключение + +| Команда | Результат | +| --- | --- | +| `failproofai jev setup --mode off` | Сохранить конфигурацию; Jev не спрашивается. **Это переключатель, который длится:** повторное подключение никогда не переписывает существующий `jev.json`, поэтому Jev остаётся отключённым до тех пор, пока вы не переключите его обратно с `--mode shadow`. | +| `failproofai jev remove` | Удалить `~/.failproofai/jev.json`; Jev отключен — до следующего `failproofai config --token` с ключом, который имеет `jev:evaluate`, который находит отсутствующий `jev.json` и включает Jev снова в режиме shadow (если только не работает с `--no-transcripts`). Чтобы держать его отключённым, используйте `--mode off`. | +| `failproofai config --disconnect` | Отключить машину: ключ удален и так же `jev.json` когда он называет FailproofAI Cloud и не переключен на отключение. `jev.json` для вашей собственной конечной точки остаётся и так же переключённый на отключение, поэтому Jev остаётся отключённым когда вы подключитесь снова. | + +Со следующего вызова инструмента хуки запускают политики регулярных выражений точно как раньше. \ No newline at end of file diff --git a/docs/ru/policies/jev.mdx b/docs/ru/policies/jev.mdx new file mode 100644 index 000000000..7bc2c6d0b --- /dev/null +++ b/docs/ru/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Добавьте живую проверку Jev к контролируемым вызовам инструментов и просмотрите её решения перед применением." +icon: "shield-check" +--- + +Jev анализирует вызов инструмента в контексте того, что пользователь попросил агента сделать. Используйте его, когда политика, основанная на сравнении строк, блокирует корректные операции или пропускает рискованное действие, требующее контекста. Он отвечает вместе с вашими политиками на вентилях `PreToolUse` или `PermissionRequest`. Для оценки **после** завершения сеанса используйте [Jev evaluations](/ru/evaluations/jev). + +## Начните с режима наблюдения + +Установите Failproof AI и подключите хуки к [поддерживаемому шлюзу](/ru/reference/harnesses). Используйте failproofai версии 1.0.8-beta.0 или позже. + +Failproof AI не поставляется с проверками Jev. Установите их как пакет, иначе Jev не будет вызван: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Затем выберите, как запросы будут передаваться в Jev: + +| Маршрут | Первый шаг | +| --- | --- | +| FailproofAI Cloud | Подключитесь с **machine** ключом, имеющим разрешение `jev:evaluate`. На машине без конфигурации Jev команда `failproofai config` включает Jev в режиме наблюдения. | +| Ваш собственный провайдер | В локальной панели управления откройте **Settings → Jev**, выберите провайдера, вставьте его токен и выберите **observe**. Или выполните `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![Параметры Jev в локальной панели управления: провайдер, endpoint, токен и режим наблюдения перед включением Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` проверяет endpoint. Для проверки пути хука попросите подключённого агента использовать инструмент чтения файлов на `README.md`. Подтвердите, что этот вызов инструмента появляется в сеансе, затем проверьте **Policies → Activity** в [локальной панели управления](/ru/reference/local-dashboard#review-policy-activity). Счётчик Jev в `status` должен увеличиться. Режим наблюдения записывает, что решил бы Jev, в то время как действующая политика всё ещё применяется. + +## Решите, когда применять + +**Жёсткая** политика всегда имеет решающее слово. Jev может отменить отказ только из политики, явно отмеченной как **reviewable**, и только когда она проверила проблему, названную в этой политике. Перед тем как полагаться на разрешение, см. [policy authority](/ru/policies/authority). Jev также может предупредить или отказать самостоятельно. Если он не может ответить, решение политики определяет результат этого вызова. + +Когда результаты наблюдения выглядят правильно, переключитесь на режим применения в **Settings → Jev** или выполните: + +```bash +failproofai jev setup --mode enforce +``` + +Для URL провайдеров, ключей Cloud, конфигурации, fallback-значений и данных, отправляемых с каждым запросом, см. [Jev integration reference](/ru/reference/jev). \ No newline at end of file diff --git a/docs/ru/reference/custom-agents-typescript.mdx b/docs/ru/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..b87adfcd3 --- /dev/null +++ b/docs/ru/reference/custom-agents-typescript.mdx @@ -0,0 +1,429 @@ +--- +title: "Пользовательские агенты (TypeScript)" +description: "Конфигурация, каталог событий, области видимости и адаптеры фреймворков для @failproofai/sdk." +icon: "square-js" +--- + +Полное описание каждого параметра, метода и поля в SDK для TypeScript. Если вы инструментируете впервые, начните с руководства — эта страница предназначена для справки. + + + + Установка, инструментация, методы событий, практический пример и часто встречающиеся проблемы. + + + Те же события, тот же формат передачи, тот же буфер — но на Python. + + + +Node 20.9 или новее. ESM и CommonJS. Без зависимостей во время выполнения. + + + Этот SDK и Python-версия записывают **одинаковые события в один буфер**. Парк с Node-агентами и Python-агентами создаёт один набор сессий, а не два, и в панели управления их ничего не различает. Выбирайте по сервисам, а не по компаниям. + + +## Установка + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Адаптеры фреймворков поставляются в самом пакете. Фреймворки — **необязательные peer-зависимости** — указаны так, чтобы поддерживаемые диапазоны версий были видны, они никогда не устанавливаются автоматически и импортируются только при вызове `instrument()`. + +## Подключение демона Failproof + +Идентично Python SDK: создайте ключ `events:add` в разделе **Admin → Keys**, затем [подключите демон](/ru/start/setup#connect-a-machine-to-cloud) на машине агента. SDK пишет на диск; демон передаёт данные. + +## Конфигурация + +### OpenTelemetry spans (опция) + +Установите OpenTelemetry отдельно с помощью `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Затем добавьте FailproofAI в процессоры вашего провайдера: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Для существующего провайдера оставьте его другие процессоры в том же списке. Провайдеры, предоставляющие `addSpanProcessor`, можно вместо этого передать как `{ provider }`. Без параметров установка регистрирует новый провайдер только если его ещё нет. +`OtelSpanExporter` можно также использовать напрямую с собственным процессором. + +Экспорт происходит через подключённый демон FailproofAI; SDK не отправляет сетевые запросы и не нуждается в ключе или локальном прослушивателе. Попросите администратора включить +[OpenTelemetry ingest](/ru/agenteye/opentelemetry). Простой `instrument()` не активирует этот экспортёр. `uninstrument("otel")` отключает только его процессор. +Ваши span-атрибуты контролируют захват содержимого; выполните flush вашего провайдера перед выходом. +OpenTelemetry остаётся необязательной зависимостью приложения, а не жёсткой зависимостью SDK. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Параметр | Что это делает | +| --- | --- | +| `environment` | Метка на каждом событии — `production`, `staging`, `prod-eu`. По умолчанию `dev`. | +| `flushInterval` | Как часто таймер пишет на диск, в секундах. По умолчанию `0.5`. | +| `baseDir` | Куда писать. По умолчанию буфер демона, что вам и нужно, если вы не знаете иного. | + +Ничего не применяется, пока не пройдёт валидация, поэтому отклонённый вызов оставляет SDK в его прежнем состоянии, а не с новым `baseDir` и старым интервалом. + +Установите через переменную окружения: + +| Переменная | Что это делает | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Устанавливает `environment` без изменения кода. Параметр `configure()` имеет приоритет. | +| `FAILPROOFAI_HOME` | Перемещает корневую директорию Failproof AI, которая содержит буфер. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (по умолчанию), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` заставляет ошибки инструментации бросать исключение вместо логирования. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` заставляет проблему совместимости фреймворка бросать исключение вместо предупреждения. | + + + **Без запятых в `environment`.** Ingest разбивает это поле по запятым для построения фильтров и пропускает любое событие, метка которого содержит запятую — поэтому весь запуск тихо исчезнет. Пишите `prod-eu`, а не `prod,eu`. + + `configure({ environment: "prod,eu" })` бросает исключение, чтобы вы узнали сразу. `AGENTEYE_ENVIRONMENT` не может бросить исключение — вас никто не вызывает — поэтому он предупреждает один раз и возвращается к `dev`. + + +Маршрутизируйте собственные логи SDK в ваш логгер с помощью `failproofai.setLogger({ debug, info, warn, error })`. + +## Завершение + +События в буфере сбрасываются при `process.on("exit")`. + +Процесс, убитый сигналом, никогда до этого не доходит, и по умолчанию Node для `SIGTERM` — завершиться без запуска обработчиков выхода — поэтому контейнеризованный агент теряет то, что последний интервал не записал. + + + **Этот SDK не установит для вас обработчик сигнала.** Регистрация одного изменяет поведение вашего процесса: прослушиватель подавляет завершение Node по умолчанию, поэтому библиотека, которая добавила его, молча остановит работу Ctrl-C. Добавьте собственный: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Краткоживущий скрипт или обработчик serverless должен вызвать `await failproofai.flush()` перед возвратом — один интервал не гарантирует доставку. + +## Идентичность + +Каждое событие принадлежит сессии и агенту. **Области видимости заполняют оба**, поэтому вы редко передаёте их: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Передача `sessionId` или `agentId` явно всё ещё работает и имеет приоритет. Без привязки или передачи вызов выбросит исключение вместо излучения события, которое Cloud молча отклонит. + + + Идентичность работает на `AsyncLocalStorage`. Она следует `await`, `.then()`, таймерам и любому обратному вызову, созданному внутри области. Она **не** следует обратному вызову, сохранённому во время одного запуска и вызванному во время другого, и не работает через границу `worker_threads` — оберните их в `failproofai.propagate()` или их события останутся неприкреплёнными. + + +### Области видимости + +| Область | Излучает | Возвращает | +| --- | --- | --- | +| `session(body)` | ничего — только идентичность | что бы ни вернул `body` | +| `agent(id, options?, body)` | `agent_start`, затем `agent_end` | что бы ни вернул `body` | +| `toolCall(name, options?, body)` | `tool_use`, затем `tool_result` | что бы ни вернул `body` | + +Синхронный body остаётся синхронным: `agent("x", () => 1)` возвращает `1`, а не промис. + +`toolCall` записывает разрешённое значение body как `output` инструмента, если вы не присвоили `call.output` сами. + + + +| Что произошло | События | `outcome` | +| --- | --- | --- | +| блок вернул результат | `agent_end` | `"success"`, или ваш `outcome` | +| блок выбросил исключение | `error`, затем `agent_end` | `"failed"` | +| `AbortError` | только `agent_end` | `"cancelled"` | + +Исключение всегда переброшено. + +Отказ инструмента записывается на листе — `tool_result` с ошибочной строкой — и излучает **никаких** событий на уровне запуска. Один, который ловит цикл агента, — не отказ запуска, а один, который распространяется, — указывается ровно один раз enclosing `agent()`. + + + + + +Когда работа — не одна функция — область видимости, открытая в конструкторе и закрытая в teardown, или одна, которая пересекает существующий поток управления: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, затем agent_end +``` + +Обе формы излучают байт-идентичные события. Предпочитайте форму с обратным вызовом: она запускается внутри `AsyncLocalStorage.run()`, поэтому нечего разворачивать и весь класс багов через выхода невозможен. + +Блок `using`, который ловит свой собственный отказ, сообщает о нём с помощью `span.fail(error)` — disposer не имеет собственного канала исключений. + + + +## Каталог событий + +Те же пятнадцать методов, что и Python SDK, в camelCase. Большинство поставляются в **парах** — вы вызываете открывающий, затем закрывающий, и SDK отсчитывает промежуток. + +| | Открывает | Закрывает | +| --- | --- | --- | +| **Агенты** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Модели** | `modelRequest` | `modelResponse` | +| **Инструменты** | `toolUse` | `toolResult` | +| **Хуки** | `hookTriggered` | `hookCompleted` | +| **Люди** | `humanWait` | `humanInput` | + +Три стоят отдельно: `error`, `humanPause`, `humanInterrupt`. + + + +Каждый метод также принимает `sessionId` и `agentId`, которые области видимости заполняют для вас. Что-либо пропущенное удаляется вместо отправки как JSON `null`. + +| Метод | Обязательно | Опционально | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Любой другой ключ, который вы добавите, становится полем пользовательского payload. Используйте пространство имён для чего-либо специфичного для фреймворка как `fw_*`; имя, которое конфликтует с объявленным полем, отклоняется вместо молчаливого перезаписывания повышенной колонки. + + + + + **`duration_ms` вычисляется, не принимается.** Четыре закрывающих метода отсчитывают промежуток от их открывающего и отклоняют supplied `duration_ms` — сообщаемая продолжительность неподделываема. + + Пары сопоставляются на **сессии** и id, никогда не на агенте. Инструмент, открытый под `planner` и закрытый под `worker`, всё ещё спаривается, что и делают настоящие вложенные мультиагентные запуски. + + +## Адаптеры фреймворков + +```ts +await failproofai.instrument(); // что угодно, что можно найти +await failproofai.instrument("langchain"); // ровно один +failproofai.uninstrument(); // всё вернуть обратно +``` + +| Фреймворк | Поддерживается | Как присоединяется | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, поэтому каждый `invoke`/`stream`/`batch` охватывается без передачи `callbacks:` где-либо — или передайте `langchainHandler()` сами и ничего не патчьте. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` в месте вызова, или `instrument("ai")` для всего процесса на `ai` 7 (на 4–6 это opt-in — смотрите ниже). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, разрешение модели и инструментов агента, и engine запусков/шагов workflow. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (подписано) плюс `AgentWorkflow.runStream`, для запусков workflow и их шагов. | + +Каждый диапазон протестирован против настоящих релизов фреймворков с обоих концов, как ES модуль и как CommonJS, на каждом запуске CI. + +Отображение — то же самое, что и Python SDK, поэтому одна и та же программа рисует одно и то же дерево в любом языке. Конструкция — это **агент** только если она владеет цикл принятия решений LLM — запуск графа или цепи, вызов `generateText`/`streamText` AI SDK, агент Mastra, запуск агента LlamaIndex. Ноду LangGraph или шаг workflow — это **хук** (`hook_triggered`/`hook_completed`), никогда не вложенный агент. Вызовы модели — это пары `model_request`/`model_response` с подсчётом токенов; вызовы инструментов несут собственный id вызова инструмента модели. Отказ записывается один раз в событии, в котором он произошёл. + +Адаптер, который не устанавливается, логируется и пропускается; остальные всё ещё устанавливаются, потому что сломанная LlamaIndex не должна стоить вам LangGraph. + + + `instrument()` без аргумента обнаруживает фреймворк по тому, **разрешается** ли он, а не по тому, уже ли он импортирован — Node не раскрывает эквивалент Python's `sys.modules` для ES модулей. Фреймворк, который у вас установлен, но не используется, будет импортирован и пропатчен. Назовите тот, который вам нужен, если это важно. + + + + Большинство этих фреймворков поставляют ES-модульную сборку и CommonJS-сборку, которые Node загружает как две не связанные копии. Адаптеры патчат копию, которую загружает ваше приложение (и CommonJS копию тоже, если что-то уже `require`'d её), поэтому обе системы модулей работают. Фреймворк **упакован в вашу собственную сборку** esbuild или webpack недостижим — используйте там помощников вызовов: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain без патчирования + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +Обработчик работает с `instrument()` или без и никогда не записывает дважды. `instrument("langchain")` принимает `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` и `captureLimit`, как делает Python адаптер; `metadata: { failproofai_sdk_session_id }` в вызове выбирает сессию для этого вызова. + +### Vercel AI SDK + +AI SDK экспортирует простые функции из ES модуля, и пространство имён ES модуля неизменяемо по спецификации — нет места для патчирования. Оно использует точки расширения, которые документирует сам SDK: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // на ai 7, `telemetry: telemetry({ … })` — тот же объект, новое имя +}); +``` + +Это полная интеграция: span агента, пара запроса/ответа модели за шаг с подсчётом токенов, и каждый вызов инструмента. Одна точка вызова работает на каждой мажорной версии — `ai` 4–6 читают трейсер, который он несёт, `ai` 7 интеграцию телеметрии. + +`instrument("ai")` делает то же самое процесс-широко **на `ai` 7**: каждый вызов, через глобальный список интеграций телеметрии AI SDK, который добавляет и ничего не берёт у кого-либо ещё. + +**На `ai` 4–6, `instrument("ai")` ничего не записывает сам по себе и логирует одно предупреждение об этом.** Единственный процесс-широкий хук, который есть в этих мажорах — это глобальный провайдер трейсера OpenTelemetry — один слот, который OpenTelemetry отказывается передать после взятия. Регистрация нашего молча отклонит ваш собственный `NodeSDK.start()` позже при запуске и отправит ваши http/database spans трейсеру, который ничего не экспортирует. Используйте `telemetry()` в месте вызова или `wrapModel` там. Если процесс не запускает собственный OpenTelemetry, opt in с `instrument("ai", { registerGlobalTracer: true })`: он затем записывает каждый вызов, который передаёт `experimental_telemetry: { isEnabled: true }`, и принимает слот только если он всё ещё пуст. `registerGlobalTracer: false` сохраняет значение по умолчанию и подавляет предупреждение. + +Если вы бы скорее обёрнули модель один раз, `wrapModel` видит только вызовы модели, потому что вызовы инструментов происходят выше слоя модели. Обёрнутая модель, вызванная с ничем вокруг, записывается как собственный запуск. Потоковый вызов закрывается, как бы не остановился поток — `stop_reason: "cancelled"` когда потребитель отменяет его, `"error"` с ошибкой когда он отказывает по дороге: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Использование обоих хорошо: middleware замечает, что вызов уже записывается и откладывает, поэтому каждый вызов записывается один раз. + +`functionId` называет span агента. Держите низкой кардинальность — он попадает в `agent_id`, первичный facet панели управления. + +### Next.js + +`next build` упаковывает зависимости вашего сервера по умолчанию, и фреймворк, упакованный в сборку, — это копия, которую `instrument()` не может достичь. Оберните конфигурацию один раз и вызовите `instrument()` из хука запуска Next: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` добавляет LangChain, Mastra, LlamaIndex и сам SDK в `serverExternalPackages`, сохраняя ваш собственный список. Без него, `instrument()` предупреждает один раз за фреймворк, который он не может достичь, вместо молчаливого отказа; если вы сами указали пакеты, установите `FAILPROOFAI_NEXT_EXTERNALS=1`. Vercel AI SDK и помощники вызовов работают в любом случае. Edge маршрут получает no-op сборку: импорт SDK безопасен и ничего не записывает. + +### Подсчёт токенов на потоковых вызовах + +OpenAI-совместимые API сообщают использование в потоке только когда клиент просит. LangChain и Vercel AI SDK просят; для LlamaIndex передайте `additionalChatOptions: { stream_options: { include_usage: true } }` его `OpenAI` LLM, и для Mastra постройте модель с включённым использованием (например `createOpenAICompatible({ includeUsage: true })`). В противном случае потоковые вызовы модели не несут подсчётов токенов. + +### Рантаймы + +Node ≥ 20.9, Bun и Deno — каждый фреймворк, как ES модуль и как CommonJS, протестирован на каждом против Node's трейса. SDK работает рядом с демоном `failproofaid`, который поставляет то, что он пишет. + +## Ваш собственный агент — без фреймворка + +Для цикла агента, который вы написали сами, или для фреймворка без адаптера. Вы излучаете события с тем же API, который адаптеры используют внизу, поэтому трейс имеет ту же форму и качество. + +Вам не нужно знать, как организован агент. Каждый написанный вручную агент уже имеет три места, как бы ни назывались его функции, и эти три — вся интеграция: + +| Где | Что добавить | Излучает | +| --- | --- | --- | +| Где **один запуск** начинается и заканчивается | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **Одна функция, которая вызывает модель** | `event.modelRequest` перед, `event.modelResponse` после — обе половины, даже при отказе | одна пара за ход модели | +| **Одна функция, которая запускает инструменты** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +Идентичность окружает: всё внутри `agent()` попадает на сессию того запуска без получения id, и ничего больше в программе не меняется — включая то, что агент уже пишет в свою собственную базу данных. + +- **Сервис или рабочий:** передайте собственный id запроса или работы как `sessionId`, поэтому сессия на панели управления и запись в вашем собственном логе или базе данных — это одна и та же строка. +- **Подагенты:** вложите вызовы `agent()`. Внутренний присоединяется к сессии с внешним как его `parent_id`. +- **Излучайте пары.** `modelRequest` без `modelResponse` — это span, который панель управления показывает как работающий вечно — отсюда и `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) в репозитории — это полная, запускаемая версия: настоящий OpenAI tool loop, инструментированный точно так же, запущен в CI на каждом изменении как ES модуль и как CommonJS. + +## Оценки + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Смотрите [справку Evaluator SDK](/ru/reference/evaluator-sdk) для протокола, параметров рабочего и типов результатов. + + + **Оценка должна yield.** Синхронная функция, которая никогда не возвращает, блокирует один поток, который есть у Node, и никакой таймаут не может срабатить пока она это делает. Пишите `async` оценки. + + +## Что это не будет делать с вашим процессом + +| | | +| --- | --- | +| **Блокировать цикл агента** | События попадают в буфер в памяти; таймер пишет их. Таймер — `unref`'d, поэтому импорт этого пакета никогда не останавливает выход скрипта. | +| **Расти без границ** | Буфер ограничен по счёту *и* по измеренным байтам. Прошлый любой, самые старые события отбрасываются и предупреждение говорит об этом — сбой телеметрии не должен стать OOM kill. | +| **Сбить процесс** | Одно неencoding событие опускается одно, не батч вокруг него. Бросающийся getter, циклическая ссылка, `BigInt`, одиночный суррогат: каждый обрабатывается вместо распространения. | +| **Оставить полусписанный батч** | Контент `fsync`ed перед атомным переименованием, директория `fsync`ed после, и неудавшая запись очищает свой временный файл. | +| **Оставить расшифровки читаемыми** | Батчи — `0600` внутри `0700` директории. Они несут цели, подсказки, аргументы инструмента и вывод инструмента. | +| **Отправить учётные данные** | Ключи API, токены, JWTs, bearer заголовки и secret-образные назначения редактируются перед тем, как байты достигают диска. Демон редактирует снова перед загрузкой. | \ No newline at end of file diff --git a/docs/ru/reference/custom-agents.mdx b/docs/ru/reference/custom-agents.mdx index 12f6893e4..12d3d1bd6 100644 --- a/docs/ru/reference/custom-agents.mdx +++ b/docs/ru/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -Python 3.10 или новее. Без зависимостей времени выполнения. +Python 3.11 или новее. Без зависимостей времени выполнения. ## Установка diff --git a/docs/ru/reference/jev-cloud.mdx b/docs/ru/reference/jev-cloud.mdx new file mode 100644 index 000000000..117a9c7b3 --- /dev/null +++ b/docs/ru/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev через FailproofAI Cloud" +description: "Облачные ключи машин, состояние подключения, лимиты и поведение при отказах для живого просмотра политик Jev." +icon: "cloud" +--- + +Это справочник маршрута Cloud для [политик Jev](/ru/policies/jev). Jev, классификатор TypeSafe, проверяет каждый вызов инструмента по сравнению с тем, что вы фактически запросили, и отвечает наряду с вашими политиками, но никогда вместо них. Через **FailproofAI Cloud** подключённая машина использует Jev с тем же ключом, которым она уже подключена: ни учётной записи TypeSafe, ни второго ключа, ни конечной точки для конфигурации. Каждый вызов списывается с лимита плана вашей организации. + +Всё, что делает Jev, не отличается от [установки с собственным ключом](/ru/reference/jev-providers): жёсткие политики остаются окончательными, отказ рецензируемой политики очищается только когда Jev был спрошен именно об этом вопросе, и любой отказ откатывается к результату регулярного выражения для этого вызова. + + +Требует **failproofai 1.0.8-beta.0** или позже. 1.0.7 не имеет Jev, хотя версия выше, чем 1.0.7 бета. Без конфигурации Jev ничего не меняется: перехватчики запускают политики регулярного выражения точно как раньше. + + +## Перед началом + +Установите Failproof AI на машине, где запущен ваш агент, и привяжите его перехватчики к [поддерживаемой обвязке](/ru/reference/harnesses). Если вы начинаете с нуля, следуйте [краткому руководству](/ru/start/quickstart) до установки перехватчиков. Проверьте установленный CLI с помощью `failproofai --version`; обновите его, если версия более старая, чем Jev. Вам также необходим доступ к странице **Administration → Keys** вашей организации для создания ключа машины. + +Jev проверяет именованные вызовы инструментов на шлюзе `PreToolUse` или `PermissionRequest`. Он не проверяет все события в сеансе. Чтобы увидеть, как Jev очищает отказ политики, вам нужна установленная политика, отмеченная как [рецензируемая](/ru/policies/authority); все остальные отказы политик остаются окончательными. + +## Включение + +1. **Создайте ключ с Jev.** На панели управления FailproofAI Cloud откройте **Administration → Keys → Create key** и выберите предустановку **machine**. Она предоставляет три разрешения, которые требуются машине: `events:add` (отправка активности), `policies:pull` (получение политик) и `jev:evaluate` (Jev, списывается с плана вашей организации). Ключ не может иметь `jev:evaluate` без двух других. +2. **Подключите машину** с этим ключом. Прочитайте её одноразовый секрет в приглашении, затем выполните полную команду установки: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` устанавливает демон, привязывает перехватчики к найденным CLI агентов и подключает машину. Переменная окружения защищает ключ от аргументов команды и истории вашей оболочки. Если ваша обвязка была установлена позже, [привяжите её явно](/ru/start/quickstart). + + Если ваша организация запускает собственный FailproofAI Cloud вместо размещённого, добавьте его адрес: `--url https://` (или экспортируйте `FAILPROOFAI_CLOUD_URL`). Без этого ключ проверяется против размещённого сервиса и подключение не удаётся. Если сертификат этого хоста выдан частным ЦС, установите ЦС в хранилище системного доверия машины (например с `update-ca-certificates`), а не только в `NODE_EXTRA_CA_CERTS`: демон, который отправляет события и получает политики, читает системное хранилище. См. [Решение проблем](/ru/reference/troubleshooting). + +Вот и всё. Подключение сохраняет ключ и, когда машина **не имеет** конфигурации Jev, записывает её для FailproofAI Cloud. С первого развёртывания машины (примерно за 30 с) FailproofAI Cloud устанавливает режим: `enforce` пока политика Jev развёрнута на ней, `off` когда нет (см. [Кто устанавливает режим](#who-sets-the-mode)). Вывод говорит об этом: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Проверки, которые запускает FailproofAI Cloud, выполняются в Cloud. Чтобы добавить собственные проверки на машине, установите пак: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**С `--no-transcripts` подключение не включает Jev.** Jev отправляет каждый проверенный вызов инструмента и недавний запрос в FailproofAI Cloud, что больше, чем подключение только для решений просило бы отправлять. Ключ всё ещё сохраняется, и вывод говорит, что Jev доступен и как его включить: + +```bash +failproofai jev setup --provider failproofai +``` + +Это также отключает Jev через FailproofAI Cloud. `jev.json`, который запускает Jev через FailproofAI Cloud (оставленный предыдущим подключением с включёнными транскриптами), удаляется по тому же правилу, которое использует `config --disconnect`, и вывод говорит, что Jev через FailproofAI Cloud остаётся отключённым на этой машине. `jev.json` для вашей собственной конечной точки Jev остаётся как есть, и также остаётся FailproofAI Cloud, который вы отключили (`--mode off`). + + +Подключение **никогда не перезаписывает** существующий `~/.failproofai/jev.json`. Если вы уже используете собственную конечную точку Jev, она продолжит использоваться, и вывод говорит, что файл остался настроенным — и, когда этот файл оставляет Jev отключённым (отказано или отключено), говорит об этом и как это исправить. Чтобы перевести эту машину на FailproofAI Cloud, выполните `failproofai jev setup --provider failproofai`. + + +## Кто устанавливает режим + +На машине, подключённой к FailproofAI Cloud, **FailproofAI Cloud устанавливает режим Jev**; ничто на машине этого не делает: + +- `enforce` пока к машине развёрнута хотя бы одна политика Jev (или регулярное выражение + Jev): каждый проверенный вызов инструмента от агента, которого эти политики нацеливают, идёт в FailproofAI Cloud, который запрашивает его проверки вместе с проверками установленных там паков. Вызов от агента, которого не нацеливает политика Cloud Jev, с собственной проверкой пака, вообще не отправляется. В `enforce` собственные проверки отказа Jev блокируют вызовы, а также очищают вердикты регулярного выражения, которые они просматривают. +- `off` когда нет: вообще нет Jev, что бы ни говорил `jev.json`. + +Чтобы попробовать политику Jev перед тем, как она подействует, развёртывайте её с эффектом **observe**: её проверки всё ещё запрашиваются, и что бы они сделали, записывается как **would-have** на странице политики, но она никогда не блокирует вызов и никогда не очищает его. `failproofai jev setup --mode` и панель управления **Settings → Jev** говорят, что режимом управляет FailproofAI Cloud и ничего не меняют. `jev.json` не используется для проверок Cloud, даже если он называет другого провайдера. `failproofai config --disconnect` возвращает Jev машинному собственному `jev.json`. + +`failproofai jev status` затем говорит `Jev checks run on FailproofAI Cloud (mode: enforce)`. Он также называет проверки, которые просматривают каждую политику `both`. На странице парка показано, почему машина с режимом не может спросить: + +- `transcripts_disabled`: машина была подключена с `--no-transcripts`, что никогда не включает Jev. +- `jev_unconfigured`: ключ машины не имеет `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud отказал в некоторых вызовах машины по лимиту частоты Jev организации, и эти вызовы были решены только политиками регулярного выражения. +- `jev_unavailable`: несколько вызовов подряд не удались, поэтому машина пропускает Jev FailproofAI Cloud время от времени на минуту за раз. Она повторяет попытку самостоятельно. + +Если FailproofAI Cloud не ответит в течение 5 секунд, политики регулярного выражения решают сами, как при любом отказе Jev. После 3 сбоев подряд машина прекращает спрашивать на минуту за раз, поэтому отказ Cloud не замедляет каждый вызов инструмента. + +Пауза сеанса (`failproofai config --pause`) не останавливает проверки Jev FailproofAI Cloud, точно так же, как она не останавливает управляемые Cloud политики. Она приостанавливает проверки Jev паков, установленных на машине. + +## Проверка того, что происходит + +```bash +failproofai jev status +failproofai jev test +``` + +`status` показывает провайдера как **FailproofAI Cloud**, хост Cloud, к которому подключена машина, режим и источник ключа как **FailproofAI Cloud connection**, никогда не сам ключ. Когда `jev.json` FailproofAI Cloud находится на месте, но Jev не может работать, он говорит почему: + +| `status` говорит | `status --json` | Значение | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | Машина подключена, но для неё не сохранён ключ Jev: ключу не хватает `jev:evaluate`, или подключение не смогло его подтвердить. Запустите `failproofai config` снова с ключом в `FAILPROOFAI_CLOUD_TOKEN`; если ему не хватает разрешения, используйте ключ **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | На этой машине нет подключения FailproofAI Cloud, к которому мог бы принадлежать ключ Jev. | + +После `failproofai config --disconnect` больше нет `jev.json` FailproofAI Cloud (если только он не был отключен, что сохраняется), поэтому `status` просто сообщает, что Jev отключен. `status --json` несёт те же факты (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), также когда конфиг отсутствует или отказан. `permissions` всегда собственные `jev.json`; отказ от `credentials.json` добавляет `credentialsPermissions`, и `fix` когда одна команда её исправляет. `test` отправляет один живой запрос и сообщает его задержку и версию Jev, которая ответила. Он завершается с кодом 1 и говорит об этом в заголовке, когда ответ приходит после тайм-аута перехватчика (перехватчики записали бы `timeout`) или отвечает на вопрос проверки неправильно. + +Панель **Settings → Jev** панели управления также показывает **FailproofAI Cloud connection**: в какую организацию сообщает машина и есть ли у её ключа Jev. Это читается из собственных файлов машины без сетевого вызова. + +## Проверка реального вызова + +Начните новый сеанс в перехватчике агента. Попросите его использовать инструмент чтения файла на `README.md` и сообщить заголовок. Подтвердите, что сеанс содержит этот вызов инструмента, затем снова запустите `failproofai jev status`: счётчик недавно оценённых вызовов должен увеличиться. Откройте **Policies → Activity** в [локальной панели управления](/ru/reference/local-dashboard#review-policy-activity) для проверки вердикта Jev и режима этого вызова. В Cloud на странице **Policies** организации показаны результаты Jev для доставленной активности. В режиме observe вердикт записывается как **would-have** и результат политики всё ещё решает вызов. Очистка появляется только когда совпадала рецензируемая политика и Jev очистил её именованные проверки. + +## Что попадает на страницу политики + +Машина уже отправляет активность своих перехватчиков в FailproofAI Cloud (`events:add`). С включённым Jev, запись каждого проверяемого вызова также говорит, какой оцениватель работал, что решил Jev, какие политики он очистил, почему он откатился когда это произошло, его задержку и модель, которая ответила — решения, коды и имена, никогда команда или ваш запрос. На странице **Policies** вашей организации: + +- вызов, решение которого принял собственный вердикт Jev (режим enforce), приписывается **Jev**, и когда решающая проверка пришла из пака, запись также называет этот пак и его версию; +- в режиме observe отказ или предупреждение Jev появляется как **would-have**, рядом с развёртываниями, которые вы наблюдаете; +- политики, которые Jev очистил, или которые он очистил бы в режиме observe, считаются за политику. +- решение, в котором Jev участвовал (блокировка, предупреждение, очистка или would-have в режиме observe), перечисляет каждую проверку, которую он запросил, и то, что эта проверка заключила: вердикт, почему (`not-detected`, `exempt`, `fired`, `op-requested`, …), её доказательство `p`, ответ `exempt` и ответ каждого зонда. Проверка политики, развёрнутой для наблюдения (observe), также указана, отмечена как watched; она никогда не блокирует. Jev отвечает вероятностями, а не прозой, поэтому нет свободного текста с причиной. Обычные allow свёртываются в счёты и не несут этого списка. + +## Когда Jev не может ответить + +Каждое из них откатывается к результату вашей политики для этого вызова и записывается с причиной: + +| Причина | Причина | +| --- | --- | +| `out-of-credits` | Ваша организация использовала лимит плана. | +| `http-401`, `http-403` | Ключ был отозван или не имеет `jev:evaluate`. Подключитесь повторно с ключом, который имеет. | +| `http-429` | FailproofAI Cloud ограничивает частоту Jev для вашей организации. Пока ожидание, которое оно просит (его `Retry-After`, максимум 60 секунд), не закончится, машина ничего не отправляет и каждый вызов откатывается сразу. Вызовы, удерживаемые таким образом, записываются как `http-429`, или как `rate-limited` когда собственный лимит частоты машины удерживает их в первую очередь. | +| `http-429` (дневной лимит) | Ваша организация использовала дневные вызовы Jev: **10 000 за день UTC**, если только тот, кто управляет вашим FailproofAI Cloud, не установил другой лимит. Каждый вызов откатывается до сброса счётчика в 00:00 UTC; машина всё ещё спрашивает максимум один раз в минуту, поэтому сброс происходит в течение минуты. `failproofai jev test` говорит "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev отказал в этом запросе вызова, обычно потому, что вызов инструмента содержал плотный текст (base64, hex, минифицированный код) сверх бюджета токенов Jev. Этот вызов откатывается каждый раз; это не отказ. | +| `http-502` | Jev недоступен прямо сейчас. | +| `http-503` | Этот Cloud не может служить Jev для вашей организации: нет шлюза модели, организация не подготовлена ещё, или шлюз отключен. Обратитесь к администратору; перехватчики спрашивают максимум один раз в минуту. | +| `http-404` | Этот FailproofAI Cloud не служит Jev ещё. | +| `timeout` | Нет ответа в течение `timeoutMs` (по умолчанию 3000). Пока FailproofAI Cloud устанавливает режим Jev машины, ожидание составляет 5000 мс и `timeoutMs` `jev.json` не используется. | +| `model-mismatch` | Ответила версия Jev, отличная от 1.13. | + +## Где ключ живёт и где он идёт + +- Ключ сохраняется один раз в `~/.failproofai/credentials.json` (`0600`, в каталоге только владельца), рядом с другими учётными данными FailproofAI Cloud. `jev.json` не содержит ключ для этого маршрута; ключ, записанный туда, делает конфиг недействительным. +- Если `credentials.json` содержит **любое** разрешение для кого-то, кроме вас (группа или другие, чтение или запись), или его каталог может быть **написан** кем-либо, кроме вас, он **отказан**, не прочитан, и Jev отключен до тех пор, пока вы не исправите: `chmod 600` для файла, `chmod 700` для каталога (или подключитесь повторно, что перепишет файл на `0600` и сделает каталог только для владельца). Каталог, который другие могут только читать, хороший; тот, который они могут писать, позволяет им заменить файл. +- Ключ считается только пока подключение, с которым он пришёл, находится на машине: политика или учётные данные отчёта для того же FailproofAI Cloud **с тем же ключом**, в том же файле. Ключ Jev, оставленный без подключения, игнорируется, и Jev остаётся отключённым. Это происходит когда более старый failproofai's `config --disconnect` оставляет ключ Jev на месте (он не знает удалить его), или когда более старый failproofai's `config --token` подключается с другим ключом, который на FailproofAI Cloud может принадлежать другой организации. Чтобы включить Jev снова, подключитесь снова с ключом **machine**. +- Ключ отправляется только на источник Cloud, к которому он был проверен. `jev.json`, указывающий куда-то ещё, отказывается. +- **Агент на машине может прочитать это.** `credentials.json` доступен только владельцу, и агент работает как этот владелец. Чтение собственных файлов failproofai разрешено намеренно (только их изменение блокируется с помощью `block-failproofai-commands`), поэтому единственное, что стоит между агентом и этим файлом, это `block-read-outside-cwd` — *рецензируемая* политика — и из сеанса, начатого в вашем домашнем каталоге, ничего. Ключ с `jev:evaluate` тратит лимит Jev вашей организации (до дневного лимита) откуда бы он ни использовался, поэтому обращайтесь с ключом машины как с любыми другими учётными данными расходов: если агент мог его прочитать, отключите его на странице Keys и подключитесь с новым. +- Только ваши глобальные файлы решают это. Репозиторий не может включить Cloud Jev, указать на него или поставлять его ключ, и `FAILPROOFAI_JEV_API_KEY` игнорируется для этого маршрута. +- Для каждого вызова, который Jev оценивает, один запрос идёт в FailproofAI Cloud, несущий то, что перечисляет [страница bring-your-own-key](/ru/reference/jev-providers#what-leaves-the-machine) (секреты отредактированы). FailproofAI Cloud перенаправляет это TypeSafe и не регистрирует или не сохраняет его. + +## Отключение + +На подключённой машине Jev отключен когда FailproofAI Cloud не развёртывает политику Jev на ней: удалите или архивируйте политики Jev там. + +| Команда | Результат | +| --- | --- | +| Удалить политики Jev машины в FailproofAI Cloud | Режим Cloud становится `off` при следующем опросе (примерно 30 с): вообще нет Jev, что бы ни говорил `jev.json`. | +| `failproofai config --disconnect` | Отключить машину: ключ удаляется, и также удаляется `jev.json` когда он называет FailproofAI Cloud и не отключен. `jev.json` для вашей собственной конечной точки остаётся. | + +С следующего вызова инструмента перехватчики запускают политики регулярного выражения точно как раньше. \ No newline at end of file diff --git a/docs/ru/reference/jev-evaluations.mdx b/docs/ru/reference/jev-evaluations.mdx new file mode 100644 index 000000000..3161dda9f --- /dev/null +++ b/docs/ru/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev evaluation reference" +description: "Question types, calibrated scores, limits, and backfill for Jev session evaluations." +icon: "list-checks" +--- + +На этой странице описаны типы вопросов и правила подсчета баллов для [Jev evaluations](/ru/evaluations/jev). Некоторые вопросы требуют от модели *прочитать* беседу, но не *написать* о ней. "Выразил ли клиент срочность?" имеет два ответа. "Насколько они были расстроены?" имеет несколько ответов, упорядоченных по порядку. Вы знаете каждый возможный ответ еще до того, как задать вопрос. + +**Классификационная оценка** предназначена именно для таких случаев. Вы пишете вопрос и возможные ответы, а небольшая модель, созданная специально для классификации, возвращает откалиброванное число — никогда не свободный текст. + + +Как судья, классификационная оценка требует одного вызова модели за сеанс. Однако, в отличие от судьи, это небольшая узконаправленная модель, а не общего назначения, поэтому она быстрее и дешевле — но она никогда не объяснит себя. Если вам нужны рассуждения, используйте [судью](/ru/evaluations/judge). + + +## Какой вариант мне нужен? + +| Вопрос | Использовать | +| --- | --- | +| Сколько было вызовов инструментов? | код | +| Был ли сеанс менее 30 секунд? | код | +| Выразил ли клиент срочность? | **классификация** | +| Какая команда должна это обработать: billing, technical или sales? | **классификация** | +| Насколько был расстроен клиент? | **классификация** | +| Был ли ответ действительно правильным? | **судья** | +| Следовала ли она нашей политике эскалации, и почему вы так думаете? | **судья** | + +Основной принцип: **подсчитываемое → код, ответы, которые можно перечислить → классификация, требуется объяснение → судья.** + +Вам не нужно решать это заранее. Опишите, что вы хотите измерить, и ассистент выберет, скажет вам, что он выбрал и почему, и вы сможете переключиться. + +## Два типа вопросов + +### `noul` — это правда? + +Два ответа, и вы описываете оба. Результат — вероятность того, что описание "true" подходит: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Опишите обе стороны. "Срочность не выражена" — это реальный ответ, и озвучивание этого делает другой ответ четче. + +### `score` — сколько этого? + +Упорядоченная шкала, **худший вариант первым**. Результат показывает, где располагается сеанс на шкале, переведенный в диапазон 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Шкала должна содержать от трех до пяти уровней, и все они должны быть различными.** Оба предела измеряются, а не определяются стилем: + +- **Два уровня** сворачиваются в то, что `noul` уже делает лучше, а **более пяти** заставляют модель колебаться к середине вместо того, чтобы решиться. Один и тот же вопрос над одним и тем же сеансом набрал 0.00 с двумя уровнями, 0.01 с тремя и 0.55 с десятью. +- **Повторяющиеся уровни** делят ответ произвольно между ними. Сеанс, который явно был злым, набрал 1.00 против `["Calm", "Frustrated", "Very angry"]` и 0.66 против `["Angry", "Angry", "Angry"]` — правильно составленное число, которое ничего не означает. + +Категории без порядка — "billing, technical или sales" — это не шкала. Задайте их как `noul` для каждой категории или используйте судью. + +## Чтение результатов + +Классификатор производит **оценку** от 0 до 1, точно как судья, поэтому она отображается на графиках, фильтруется и запускает оповещения тем же образом. Есть два различия, которые стоит знать: + +- **Нет рассуждений.** Поле пусто, намеренно. Эта модель не объясняет себя, и придумывание объяснения было бы вымыслом, а не функцией. +- **Неопределенность обозначается.** Вопрос `score` сообщает о собственной уверенности, и результат, в котором модель была неуверена, помечается как `low_confidence` — поэтому "кого из них должен посмотреть человек" это фильтр, а не предположение. Вопрос `noul` не сообщает о уверенности, поэтому он никогда не помечается. + +Очень длинные сеансы читаются фрагментами и объединяются. Когда сеанс слишком длинный для полного прочтения, результат показывает, сколько ходов было опущено — вы никогда не увидите суждение, вынесенное на части сеанса и представленное как вынесенное на весь сеанс. + +## Ограничения + +- **От трех до пяти уровней шкалы, все различные.** См. выше; оба предела проверяются при создании. +- **Один вопрос на одну оценку.** Если вы задаете два вопроса, вы получаете две оценки, что также то, что вам нужно на графике. +- **Редактирование вопроса публикует новую версию.** Старые и новые оценки несопоставимы, поэтому они хранятся отдельно, а не смешиваются в одну линию тренда. +- **Классификатор всегда производит оценку**, никогда метрику или утверждение. +- **Нет рассуждений**, как указано выше. Если число вызовет вопрос "почему?", напишите судью вместо этого. + +## Тестирование и возвратная загрузка + +В отличие от судьи, классификационная оценка **может** быть протестирована перед развертыванием — [протестируйте ее](/ru/evaluations/test) на реальных сеансах так же, как вы бы протестировали оценку кода, и прочитайте оценки перед тем, как что-либо попадет в production. + +Она также может быть [возвратно загружена](/ru/evaluations/deploy#score-sessions-you-already-have) над сеансами, которые у вас уже есть. Это требует одного вызова модели за сеанс, поэтому намеренно ограничьте временное окно вместо повторного воспроизведения всего. \ No newline at end of file diff --git a/docs/ru/reference/jev-intent.mdx b/docs/ru/reference/jev-intent.mdx new file mode 100644 index 000000000..06703f4e6 --- /dev/null +++ b/docs/ru/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Захват намерений Jev" +description: "Какие события harness'а говорят оценивателю Jev, что просил человек, какое поле содержит текст, что никогда не учитывается, и риск, связанный с доверием prompt'у, поставленному harness'ем." +icon: "message-square-quote" +--- + +Когда вы настраиваете [проверку политики Jev](/ru/policies/jev), оценивающий судит каждый заблокированный вызов инструмента на основе **того, что просил человек**, а не текста, который harness поместил перед агентом. Ответ вроде "да, сделай force-push" может пройти политику **reviewable** — в этом вся суть оценивающего, так как регулярное выражение, которое не может прочитать запрос, блокирует треть реальной работы. + +Этот текст поступает из одного источка: **prompt'а, который сам harness передает hook'у при событии prompt-submit**. Failproof AI записывает его часть, которую набрал человек — обёртка harness'а удалена, secrets отредактированы, обрезаны — в файл `0600` в своем собственном каталоге состояния. Ничего на диске не консультируется: стенограмма сеанса — это файл, который агент может переписать одной командой, поэтому никогда не спрашивается, кто написал prompt. + +## Риск, который это принимает, ясно + +Агент, который уже может запускать команды, может заставить harness отправить prompt. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` и `pi -p` все запускают одно и то же событие prompt-submit с тем же payload, как при вводе человеком, в дочерней сессии, которую этот агент контролирует. Он также может запустить собственный бинарник hook Failproof AI и передать ему payload, который он написал. Ничто внутри Failproof AI не может отличить одно от другого — оба это одна и та же программа, читающая один и тот же stdin. + +**Так что агент с shell может подделать собственное согласие.** Это сознательный компромисс, принятый 2026-09-23, и вот обе его стороны: + +- **Что это приносит.** Альтернатива была построена и измерена: требовать поле, в котором harness указывает человека как автора prompt'а, и ничего не записывать иначе. Ни один поставляемый harness не отправляет такое поле, поэтому эта версия ничего не записывала **на каждом harness'е** — Jev судил каждый вызов без указанного намерения и никогда не мог пройти ни одну политику. Захват, который никогда не срабатывает, — это не более безопасный продукт, это вообще не продукт. +- **Что он не может сделать.** Записанный prompt может пройти только политику, уже отмеченную как **reviewable**. Политика **hard** никогда не пропускается ничем, что говорит Jev, так что поддельный prompt не может никогда превратить жёсткий deny в allow — и пропуск hook'а также ничего не дает агенту: harness вызывает Failproof AI для вызова инструмента независимо. +- **Что он может сделать в полном объёме.** Худшее, что он может сделать, — пройти одну из пятнадцати reviewable встроенных политик — и **двенадцать из этих пятнадцати блокируют**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` и шесть блоков инфраструктурных CLI (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) это deny'и, так что поддельное согласие может превратить реальный deny в allow на печать secrets переменных окружения, чтение файла `.env`, чтение вне проекта, `rm -rf`, force-push, запись файла secrets или изменение live инфраструктуры. Только `warn-git-amend`, `warn-destructive-sql` и `warn-global-package-install` это предупреждения. Установка по умолчанию включает две из двенадцати, `protect-env-vars` и `block-env-files`; остальные десять доступны только на машине, где кто-то их включил. Что не проходит prompt — это всё жёсткое — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, защита, которая останавливает агента, отключающего Failproof AI, и каждая другая встроенная политика, не отмеченная как reviewable. [Авторитет политик](/ru/policies/authority) перечисляет все пятнадцать и то, на основе чего каждая проверяется. + +Что всё ещё отказано — это всё, что дёшево проверить и что агент не может получить просто спросив: ход, который собственный payload harness'а отмечает как отправленный машиной, payload с названием sub-agent'а, идентификатор сеанса, который не является простым именем, событие, которое не является prompt-submit'ом, и текст, который ничего кроме обёртки harness'а — включая собственные стоп-ворота Failproof AI, которые несколько harness'ей отправляют обратно как следующий ход пользователя. + +## Таблица по harness'ам + +"Поле Text" — это поле payload'а stdin после нормализации Failproof AI для каждого harness'а. "Recorded" говорит, сохраняется ли prompt как запрос человека. + +| Harness | `--cli` | Событие Prompt → каноническое | Поле Text | Recorded | Последнее сообщение агента прочитано из | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Да, если только `source` в payload'е не называет ход, который никто не отправил (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, неизвестное значение и сборка, которая не отправляет `source` вообще, все записываются | стенограмма сеанса (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Да | rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Да | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Да, с удалённой обёрткой ``, когда она охватывает весь prompt | JSONL стенограммы агента | +| OpenCode | `opencode` | `message.updated` (роль пользователя) → `UserPromptSubmit` | `prompt` | Да — но текущий OpenCode не содержит текста в этом событии, поэтому практически ничего не записывается; повторение одного сообщения записывается один раз | нет (сеансы это SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Да, если только `input_source` не является `extension` — `sendUserMessage()` другого расширения, чей текст может быть написан моделью или получен из репозитория | JSONL сеанса Pi | +| Hermes | `hermes` | нет | — | Нет — у Hermes вообще нет события prompt-submit | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Да, если только метаданные запуска не отмечают запуск как машинный: `trigger` отличный от `user`, `inputProvenance.kind` отличный от `external_user`, или `senderIsOwner: false` | нет (`before_agent_run` не несёт путь стенограммы) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Да | JSONL сеанса droid | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Да | нет (сеансы это SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | нет | Нет — `PreInvocation` срабатывает перед *каждым* вызовом модели в ходе и не несёт текст prompt'а | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Да | нет (сеансы это SQLite) | + +Два harness'а ничего не записывают, и по одной и той же причине в обоих случаях: их событие не доставляет человеческий текст. У Hermes нет события prompt-submit — его встроенный плагин обрабатывает `pre_llm_call` самостоятельно и пересылает только события инструмента, сеанса и sub-agent'а. `PreInvocation` у Antigravity срабатывает перед каждым вызовом модели, на ходе человека и на пяти ходах, которые за ним следуют, и не несёт поле prompt; hook'и также могут вводить `userMessage` шаги в одну и ту же беседу. В любом событии нечего записывать. + +## Что делает prompt'ом человека + +1. **Событие.** Failproof AI был вызван для события prompt-submit harness'а, которое обработчик канонизирует в `UserPromptSubmit`. +2. **Payload.** Harness записывает его на stdin hook'а, и он содержит текст в названном выше поле. Вызов, который достигает Failproof AI без payload'а, ничего не записывает. +3. **Ничто в payload'е не исключает ход.** Payload, который называет sub-agent'а (`agent_id`), это агент, подсказывающий себя. `source`, `input_source` или маркер запуска OpenClaw, который называет ход, отправленный машиной, отказан. **Отсутствующий** маркер ничего не исключает — это отличие от версии, которая ничего не записывала, так как каждый маркер здесь отсутствует на каждой поставляемой сборке. +4. **Что-то остаётся после удаления обёртки** (см. ниже). + +**Стенограмма сеанса не является доказательством того, кто написал prompt.** Более ранние версии этой страницы описывали проверку кросс-ссылки с стенограммой: prompt отказывался, если стенограмма показывала, что модель его планировала, и стенограмма должна была продолжать ту, которую видел предыдущий prompt. Эта проверка исчезла. Стенограмма — это файл, над которым агент уже имеет контроль — её можно усечь, заменить, дополнить мимо бюджета чтения, снять в начале хода и восстановить в конце, или улучшить записями, которые написал агент. После каждого раунда укрепления следовала другая орфография одной и той же подделки, поэтому весь механизм был удален, а не отремонтирован. + +Стенограмма всё ещё читается для одного: **последнего видимого сообщения агента**. Это сообщение по определению написано агентом, Jev об этом сообщается, и оно само по себе никогда не является согласием. + +## Что сохраняется от prompt'а + +Harness'ы помещают в prompt больше, чем слова человека. Перед тем как что-либо сохраняется: + +- Блоки `` удаляются, и слова человека вокруг них сохраняются. +- Резюме продолжения сеанса ("Этот сеанс продолжается из предыдущей беседы…") полностью отбрасывается. +- Уведомления о задачах, вывод локальных команд и маркеры прерывания отбрасываются полностью. +- Ход, который написал другой агент или сеанс, полностью отбрасывается: Claude Code оборачивает их в ``, ``, ``, `` или ``. +- Собственные сообщения Failproof AI отбрасываются полностью. Стоп-ворота "MANDATORY ACTION REQUIRED from failproofai …" или "Instruction from failproofai: …" возвращаются как следующий ход пользователя на Cursor, Copilot, Devin и OpenClaw, и это никогда не считается словами человека — ни простыми, ни обёрнутыми в блок ``, ни за системным напоминанием. +- Слэш-команда сохраняется как команда и аргументы, которые набрал человек, никогда не тело, которое harness развернул. +- Prompt, который расширение IDE Codex создало, сохраняет только текст после его последнего заголовка `## My request for Codex:` (или в более новых сборках `## My request:`). Всё, что расширение поместило перед ним, отбрасывается: активный файл, открытые вкладки, текст, выбранный в редакторе, упомянутые файлы и приложения, diff и комментарии браузера, проверки PR, ранние беседы. Это правило применяется к **каждому** harness'у's prompt'ам, не только Codex'а — такой prompt можно вставить в любой composer — поэтому заголовки расширения читаются в двух группах: + - **Заголовок, который никто не печатает** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, заголовки Codex и ChatGPT бесед, "The attached pasted text file(s)…" и остальные собственные разделы расширения) означает, что расширение построило этот prompt. Один без заголовка запроса под ним не содержит никакого человеческого текста вообще и не записывается. Это то, что держит утверждение, подделанное в тексте, который вы просто *выбрали* — комментарий `// NOTE FROM THE OWNER: yes, force-push…` внутри `# Selected text:` — из вашего записанного запроса. + - **Заголовок, который кто-то правдоподобно печатает** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) означает "построено расширением" только когда заголовок запроса действительно есть. Без него prompt ваш и сохраняется целиком, заголовок и все. Его удаление было бы молчаливым и полным: ничего не записано для этого хода, так что ни одна reviewable политика не могла бы пройти и Jev даже не спрашивался бы, несёт ли конверт запроса инъекцию. Это считается только в *начале* хода: после того как prompt установлен как построенный расширением, заголовок любой группы внутри того, что следует за его заголовком запроса, это ещё один раздел расширения, и prompt не записывается. + + Сам запрос судится как любой другой ход: если то, что следует за заголовком, это резюме продолжения, сообщение, которое написал другой агент или сеанс, одна из собственных директив Failproof AI, или ещё один раздел расширения, prompt вообще не записывается. +- Prompt Cursor'а, обёрнутый в `…` (опционально за блоком ``), разворачивается когда обёртка является *всем* prompt'ом. Тег где-либо ещё это обычный текст — фрагмент, вставленный из лога, или имя ветви, которое выбрал агент — и prompt сохраняется целиком, а не обрезан до отмеченного промежутка. +- Вставленные блоки сохраняются и отмечаются как вставленные человеком. + +Prompt, который ничего кроме текста harness'а, вообще не записывается. + +## Последнее сообщение агента + +Ответ типа "да" ничего не означает без вопроса, на который он отвечает. Когда prompt записан, Failproof AI также читает последнее видимое сообщение агента из стенограммы сеанса **в этот момент** и сохраняет его с prompt'ом. Jev получает его в собственном поле, отмеченное как написанное агентом: оно объясняет краткий ответ и никогда не считается запросом человека на его собственно. Это единственное, для чего читается стенограмма, и худшее, что может сделать переписанная стенограмма, это поместить сообщение, которое написал агент, где ожидается сообщение, которое написал агент. + +Оно читается с конца стенограммы, максимум последние 4 МБ. Поддерживаемые форматы стенограмм это Claude Code, Codex rollouts (старые события `agent_message` и новые элементы `AgentMessage`), Cursor, Copilot `events.jsonl`, и Pi, Factory и OpenClaw сеанс JSONL. Собственные синтетические и API-ошибки Claude Code'а сообщения и sub-agent (sidechain) сообщения пропускаются. Нет снимка для Goose и OpenCode, которые хранят сеансы в SQLite, для Devin, чья стенограмма это один JSON документ, или для OpenClaw, чьё событие `before_agent_run` не содержит путь стенограммы. + +## Хранилище + +| Свойство | Значение | +| --- | --- | +| Местоположение | `~/.failproofai/state/semantic/sessions//.json`, где `` это профиль агента, в который был введён prompt: `.` для агента, который знает FailproofAI (идентификатор, который целевые Cloud политики), или просто `` иначе | +| Разрешения | файл `0600`, директория `0700`. Каждая директория выше, вплоть до `~/.failproofai`, придерживается того же правила, что директория `jev.json`: та, в которую кто-то другой может **писать**, может быть переименована и заменена, так что путь чтения убирает эти биты записи где может и не читает **ничего** где не может. Записанный prompt тогда отсутствует, а не подделан, и ничего не пропускается | +| Сохранено за сеанс | последние 5 prompt'ов; prompt, идентичный предыдущему, его заменяет, а не занимает новый слот | +| Окно | prompt'ы старше 6 часов игнорируются | +| Размер | каждый prompt и сообщение агента обрезаны до 6000 символов, сохраняя начало и конец | +| Secrets | отредактированы с теми же паттернами, что политики `sanitize-*`, перед тем как что-либо записывается. Текст длиннее 48000 символов отредактирован как его первые 28800 и последние 19200 символов, и текст рядом с этими вырезами, где secret мог быть разделён, никогда не сохраняется | + +Идентификатор сеанса, содержащий что-либо кроме букв, цифр, `.`, `_` и `-`, или длиннее 128 символов, никогда не используется как имя файла, так что ничего не записывается для него. + +Файл сеанса существует только после того как prompt был записан в нём. Он содержит prompt'ы и ничего больше — не состояние происхождения, не метку стенограммы — и он удаляется как только он был молчалив дольше, чем окно в шесть часов, в следующий раз когда новый сеанс записывает свой первый prompt. + +Prompt читается обратно только для того же профиля агента и идентификатора сеанса, под которым он был записан. Идентификаторы сеанса поступают от агента, так что два профиля могут использовать одинаковый; ключ по профилю сохраняет слова одного профиля от когда-либо считаться запросом другого. Файлы до этого макета (`sessions/.json`) не могут сказать, какой профиль их написал, так что они никогда не читаются и устаревают с окном в шесть часов. + +Ничто не записывается, если не настроена конечная точка Jev. В режиме FailproofAI Cloud Jev ничто не записывается для профиля агента, к которому не назначена проверка Cloud Jev и который не проверяется установленным пакетом. + +### Корень проекта + +"Внутри проекта" — что судят `read-outside-workspace` и другие проверки пути — означает внутри проекта, в котором сеанс был при своём **первом проверяемом вызове**. Корень закреплён тогда и более поздний `cd` его никогда не перемещает; `cd` всё ещё изменяет то, как относительный путь разрешается. Позволив ему следовать `cd` позволило бы `cd ~/.ssh` в одном вызове сделать `~/.ssh` проектом для следующего. + +Закрепление это `~/.failproofai/state/semantic/roots/.json`, содержащее `{root, at}`: файл `0600`, директория `0700`, и то же правило идентификатора сеанса, что выше. Файлы старше 7 дней удаляются когда новый сеанс закрепляет свой корень. Директория `roots`, в которую другие пользователи могут писать, игнорируется, и используется корень live директории. Чтобы переубедить сеанс, удалите его файл. + +## Известные ограничения + +- **Prompt столь же надёжен, сколь вызов hook'а.** Всё здесь читает payload, который harness написал на stdin hook'а. Агент, который может запускать команды, может запустить harness без интерфейса (`claude -p` и остальные семь перечисленные выше) или запустить сам бинарник hook Failproof AI с payload'ом, который он написал, и записать prompt, который никто не набирал. Это принятый компромисс, описанный в начале этой страницы: он пропускает только reviewable политики, никогда жёсткую — но двенадцать из пятнадцати reviewable встроенных это deny'и, так что поддельный prompt может превратить реальный блок в allow на этих двенадцати. +- **Обнаружение sub-agent'а это Claude-образное.** Payload, несущий `agent_id`, никогда не записывается ни на каком harness'е. Это поле, которое использовали бы Claude Code, Factory Droid и Devin. Codex срабатывает своё событие prompt внутри потоков sub-agent'а, Copilot запускает встроенные sidekick'и, Goose имеет инструмент `delegate` и OpenClaw запускает personas — ни один из которых не отмечает payload таким образом, который это узнаёт, так что prompt sub-agent'а на этих harness'ах записывается как собственный сеанс. `openclaw.agentId` OpenClaw'а это **не** этот маркер: поставляемый плагин устанавливает его на каждом запуске, включая владельца. +- **Планировщики, которые не несут маркер.** Claude Code'а `schedule_wakeup` и `loop_wakeup`, и OpenClaw'а `cron` и `heartbeat` триггеры, отказаны потому что эти harness'ы это говорят в payload'е. Собственный планировщик Goose'а (`goose schedule add`) и `codex exec` ничего не говорят, так что запуск, который они начинают, записывается как любой другой. +- **Последнее сообщение агента может быть сообщением, которое выбрал агент.** Стенограмма не аутентифицирована, так что агент, который пишет свою собственную стенограмму, может решить, что его "последнее сообщение" говорит. Оно помечено как написанное агентом и никогда ничего не пропускает самостоятельно — но заметьте, что путь v1 `decide.ts` позволяет ему удовлетворить детерминированную проверку "назвал ли пользователь эту цель", так что агент, который контролирует свою стенограмму, может предоставить имя целей, которое требует переопределения. +- **Prompt, который открывается одним из машинных заголовков расширения, отбрасывается целиком.** Начните prompt с `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` или другого заголовка раздела из первой группы выше, и никогда не пишите заголовок `## My request:`, и ничего не записывается для этого хода — так что ничего не пропускается для него или. Это намеренно: эти разделы содержат текст, который кто-то ещё контролирует (код, который вы выбрали, комментарий diff рецензента, заголовок страницы), и запись этого как ваши слова это худший отказ. Заголовки, которые разработчик правдоподобно печатает, находятся во второй группе и никогда не отбрасывают prompt самостоятельно. +- **OpenCode практически ничего не записывает.** Его событие `message.updated` не содержит текста в текущем OpenCode'е, и оно также срабатывает для дочерних сеансов, которые создаёт его tool task, чьё "пользовательское" сообщение написал родительский агент. +- **`CODEX_HOME` не соблюдается** открытием rollout в `lib/codex-sessions.ts`. Это влияет только на то, где ищется снимок agent-message, никогда на то, записывается ли prompt. \ No newline at end of file diff --git a/docs/ru/reference/jev-providers.mdx b/docs/ru/reference/jev-providers.mdx new file mode 100644 index 000000000..744f1974b --- /dev/null +++ b/docs/ru/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev providers and own-key setup" +description: "Provider endpoints, model IDs, configuration, and failure behavior for live Jev policy review with your own key." +icon: "key-round" +--- + +This is the provider and configuration reference for [Jev policies](/ru/policies/jev) with your own key. Regex policies match strings. They cannot tell `rm -rf build/` that you asked for from `rm -rf ~` that slipped into a plan, so they block too much in one place and too little in another. **Jev**, TypeSafe's classifier, reads the call against what you actually asked for and answers a set of yes/no questions about it in one fast request. + +With your own Jev endpoint and key configured, Failproof AI asks Jev about each tool call **alongside** the regex policies, never instead of them: + +- A **hard** policy's deny is final. Jev cannot clear it. Every policy is hard unless it is explicitly marked reviewable and names the Jev checks that cover it, so a custom, pack or Cloud policy that says nothing is hard, and the always-on self-protection guard is always hard. +- A **reviewable** policy's deny may be cleared, but only when Jev was asked about the exact concern that policy covers and answered nothing here or the user asked for this. A check that finds the concern real, when the user did not ask for the call, keeps the deny — even when its own verdict is only a warning, because before a tool call a warning does not stop the agent. And when that check is one that can deny (secret exposure, credential exfiltration, destructive deletion, …), nothing is cleared on that call. +- A block can still become a **warning** when the call is a step of the task you gave and reaches no further: Jev softens its own deny to a warning, and that warning — naming what is actually wrong with the call — replaces the policy's block. +- Jev can also warn or deny on its own, for harm no regex describes. +- If Jev cannot answer (timeout, rate limit, server error, no credits, an unexpected model version), that call gets the regex result, exactly as without Jev. +- Jev never makes a call more permissive than your policies alone unless it read the whole call and was asked about the exact concern. Anything less — a call too big to send whole, a suspected injection — withdraws the clearances and keeps every deny. + + +Without a Jev config nothing changes: hooks run the regex policies exactly as they always have. The config is the whole opt-in. + + + +On FailproofAI Cloud? You do not need a key of your own: a machine connected with a key that carries `jev:evaluate` can use Jev on your organization's plan. See [Jev through FailproofAI Cloud](/ru/reference/jev-cloud). + + +## Before you start + +Install **failproofai 1.0.8-beta.0 or later** and attach its hooks to a [supported harness](/ru/reference/harnesses) on the machine where your agent runs. Follow the [quickstart](/ru/start/quickstart) if this is a new machine, or [set up local enforcement](/ru/start/setup#enforce-locally) if you do not use Cloud. Check the installed CLI with `failproofai --version`. + +Get an API key from a provider below, or have a compatible endpoint and its key ready. Jev reviews named tool calls at the `PreToolUse` or `PermissionRequest` gate. It can issue its own verdict, but clearing an existing policy deny also requires an installed policy marked [reviewable](/ru/policies/authority). Hard policy denies stay final. + +## Choose a provider + +Jev is reachable through five routes. Bring a key for any one of them. + +| Provider | `--provider` | Endpoint | Default model | Notes | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Exact version pin. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Requests are routed to zero-data-retention endpoints only, with no fallback to another provider. Reports a dated version such as `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Names Jev only by an alias, so the answering version is recorded as unverified. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Needs `--account-id`. About six calls a second per key were measured before HTTP 429. | +| Your own endpoint | `custom` | `/systemone` | `jev-1.13.0` | Any endpoint that accepts TypeSafe's request body and reports which model answered. `https` only; plain `http` to a loopback host (`localhost`, `127.0.0.1`, `::1`) is accepted for local testing. | + + +With Vercel's own bring-your-own-key feature, a failed request is silently retried with Vercel's credentials. If you need every call billed to, and seen by, your own TypeSafe account only, use TypeSafe directly. + + +## Set it up + +One command, the endpoint and the key. Start in `observe` mode so you can inspect Jev's verdicts while the existing policies keep deciding calls: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### The URL picks the provider + +You do not have to name the provider: the URL's **host** is which one it is. + +| URL host | Provider | Also needs | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| any other host | `custom` | — the URL you gave is the base URL | + +Three things follow from that: + +- **A URL that is the provider's own API writes no override.** `--url https://api.typesafe.ai/v1` produces exactly the config `--provider typesafe` would have. Give a different path or host on a known provider and it is stored as the base URL, as `--base-url` would store it. +- **`--provider` still overrides the inference**, which is how you reach a proxy that speaks a provider's API from a host of your own: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **A `--provider` that contradicts the host is refused**, not guessed at. `--provider openrouter --url https://api.typesafe.ai/v1` writes nothing and says why: the two spellings disagree about where your key is about to be sent. The same pair is refused from `jev setup --base-url` and from the dashboard's Jev settings. (`--provider custom` is not a contradiction — it means treat this URL as itself — except on Cloudflare's host, whose per-account endpoint a custom route cannot reach.) + +`--url` is validated exactly as the `baseUrl` in the config file is, and refused in the same words: `https`, or plain `http` to a loopback host (`localhost`, `127.0.0.1`, `::1`) in any mode. Risk: nothing authenticates a loopback server, so while it is down another local process could take its port and answer; use `https` outside local testing. + +### The key + +Pipe it in with `--key-stdin`, or run the command in a terminal without it and paste the key at a masked prompt. Either way it goes straight into the config file and is never printed back. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` takes the same flags and is the longhand for all of it: `setup --provider ` where you would rather name the provider than the URL. + +### `--token`, and what it costs + +`--token ` puts the key on the command line, which is the fastest way to configure a machine and the only spelling that leaves the key anywhere but the config file: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +A command-line argument is in your shell's history file afterwards, and while the command runs it is in the process list — readable from `/proc` by anything running as you. `setup` says so every time `--token` is used. Prefer `--key-stdin` on a machine you share, in a recorded session, or anywhere the history file is synced; rotate a key you have passed this way if it matters. + + +`--token`, `--key-stdin` and `--key-from-env` are mutually exclusive: give one. + +Then send one small live request to check the key, the endpoint and which Jev answered: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` exits 1, and says so in its title, when the answer arrives after the timeout (every hook would fall back to regex as `timeout`) or answers its check question wrongly. + +Hooks read the config on every tool call, so it applies from the next one. There is nothing to restart, with or without the daemon. + +## Check what it is doing + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` shows the provider, endpoint, model, mode, the config file and its permissions, and never the key. Below that it summarizes recent activity: how many calls Jev evaluated, how often it fell back to regex and why, its latency, and which reviewable policies it cleared. + +## Verify a real call + +Start a new session in the hooked agent. Ask it to use its file-reading tool on `README.md` and report the title. Confirm that the session contains that tool call, then run `failproofai jev status` again: its recent evaluated-call count should increase. Open **Policies → Activity** in the [local dashboard](/ru/reference/local-dashboard#review-policy-activity) to inspect the call's Jev verdict and mode. In observe mode, the policy result still decides the call. A clearance appears only if a reviewable policy matched and Jev cleared every named check; an ordinary read may have no policy to clear. + +## Observe mode + +`enforce` is the default. To watch Jev without letting it change any decision, switch to `observe`: Jev is still asked and its verdicts are recorded, but the regex result is what is enforced. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` keeps the config — the endpoint and the key — and stops asking Jev: hooks run the regex policies exactly as without a config, and `failproofai jev status` says off (switched off). Switch back with `--mode observe` or `--mode enforce`. + +Re-running `setup` for the same provider keeps the stored key, so a mode switch is one flag. Switching provider starts over and asks for that provider's key. So does a `--base-url` that moves requests to a different host: a stored key is only sent to the host it was given for, or to its provider's own API. + +## The config file + +Everything lives in one file, `~/.failproofai/jev.json`, written by `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Field | Meaning | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` or `custom` — or `failproofai`, whose key comes from the FailproofAI Cloud connection instead of this file (see [Jev through FailproofAI Cloud](/ru/reference/jev-cloud)). | +| `apiKey` | Sent as `Authorization: Bearer `. | +| `baseUrl` | Required for `custom`; replaces the provider's API base otherwise. Must be `https`. Plain `http` to `localhost` is accepted only with `mode: observe`: nothing authenticates a local port, so while your proxy is down any process on the machine, including the agent being judged, could answer in its place. | +| `accountId` | Cloudflare only: 32 lowercase hex characters. | +| `model` | Replaces the provider's default model id. A versioned id must name Jev 1.13. A value shaped like an API key is refused (and not repeated back), so a key pasted into `--model` is never stored or sent as the model. | +| `timeoutMs` | How long a tool call waits for Jev before using the regex result. 100–10000, default 3000. | +| `mode` | `enforce` (default), `observe`, or `off` (keep the config, run no Jev). | + +Three rules protect it: + +- **Owner-only.** It is written with permissions `0600`. A copy that any other user or group can read or write is **refused**, and hooks fall back to regex until you run `chmod 600 ~/.failproofai/jev.json` or `setup` again. The directory is checked too: `~/.failproofai` must not be **writable** by anyone else, because whoever can write there can replace the file whatever its own permissions are. `setup` takes those write bits off if it finds them. `failproofai jev status` says when a config has been refused and shows the endpoint the file names: someone else could have changed it, so check it is yours before you `chmod`. Re-running `setup` on such a file carries its stored key only to the provider's own API; any other endpoint it names needs the key again (`--key-stdin`), or `--base-url default` to send requests back to the provider. +- **Global only.** A repository cannot turn Jev on, point it at another endpoint or pick its model: a `.failproofai/jev.json` inside a project is ignored, and the provider, URL, model and account id are read only from that file — never from the environment, which a repository's agent settings can set. (`FAILPROOFAI_HOME` is not a way around that: it moves the whole failproofai directory, your policies included, rather than redirecting Jev on its own.) +- **The key alone may come from the environment.** If the file has no `apiKey`, `FAILPROOFAI_JEV_API_KEY` supplies it for that session (`setup --key-from-env` writes such a file). It never replaces a key the file holds, and it cannot turn Jev on without the file. Where the variable is not set, Jev is simply off for that shell: `failproofai jev status` says so, exits 0 and leaves the config alone (`status --json` reports `"status": "key-missing"` with `"reason": "no-env-key"`). The `failproofaid` daemon does not see your shell's environment, so on a machine set up with `failproofai config`, keep the key in the file. + +## Which Jev answers + +Failproof AI's decision thresholds were calibrated on Jev 1.13, so an answer is used only when it comes from that family: `jev-1.13.x`, or OpenRouter's `typesafe/jev-1.13-`. Where a provider names Jev only by an alias and reports no version (Vercel, and Cloudflare when it does not say), the answer is used and recorded as unverified. A `custom` endpoint must report the model that answered; the one exception is an unversioned `--model` name you configured for it, which, echoed back, is recorded as unverified in the same way. An answer reporting any other version, or a `custom` answer reporting none, is not used: that call falls back to regex with the reason `model-mismatch`. + +## When Jev cannot answer + +Each of these falls back to the regex result for that call and is recorded with its reason, which `failproofai jev status` totals: + +| Reason | Cause | +| --- | --- | +| `timeout` | No answer within `timeoutMs`. | +| `http-429` | The provider rate-limited the key. | +| `rate-limited` | Failproof AI's own limiter held the call back before sending it: 5 requests a second, in bursts of up to 5, and none for a moment after the provider answers `429`. Not the provider. | +| `http-500`, `http-502`, `http-503`, … | A server error at the provider. The exact status is recorded. | +| `out-of-credits` | HTTP 402: the provider account has no credits left. | +| `provider-refused` | HTTP 402 from Cloudflare reading Model execution failed (Payment error): the provider declined to run the model on this request. Usually not billing, so topping up will not move it. | +| `http-401`, `http-403` | The key was refused. | +| `http-404` | Nothing is served at `/systemone`, so the base URL is wrong — `/systemone` is appended to it, and every provider serves it at its version root. `failproofai jev models` shows what the endpoint does serve. | +| `network` | The endpoint could not be reached. | +| `http-301`, `http-302`, `http-307`, `http-308` | The endpoint answered with a redirect. Redirects are never followed, so the answer only ever comes from the URL in your config; set `--base-url` to the final URL. | +| `malformed` | The endpoint answered, but not with a Jev answer — a body that is not JSON, or one with no answers in it. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare's envelope reported a failure, or a job that had not finished. | +| `model-mismatch` | A Jev version other than 1.13 answered, or a `custom` endpoint did not say which model answered. | +| `request-cut` | **Not an outage.** Jev answered; it was shown only part of the call, so its answer cleared nothing. See [When Jev answered, but not on the whole call](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` can show a few rarer reasons too, such as `upstream-error` (the answer carried the provider's own error) or `config`, and totals any reason it cannot name as `other`. + +`request-cut` is in this table because `failproofai jev status` totals it with the rest, and because it too leaves every deny standing. It is the one reason here that says nothing about your provider: the request arrived and Jev answered it. Unlike every row above it, that answer still counts — Jev's own deny or warning applies on top of the regex result rather than being discarded. So a run of them means calls are reaching the evaluator too big to send whole, not that your endpoint is unwell, and topping up credits or changing the URL will not move the number. + +## When Jev answered, but not on the whole call + +Two more things can happen, and neither is Jev failing to answer. Both are about how much of the call, or of the conversation, fitted into one request. + +**Part of the call itself did not fit.** A tool call is sent inside a fixed budget, and an outsized one — a very large `Write`, a huge MCP body, a command padded out to the cap — is sent with what fitted. Jev still answers, and its answer still counts: its own deny or warning applies as usual. What it cannot do is **clear** anything, because a verdict given on part of a call is not a verdict on the call. So every policy deny stands, and the call is recorded as a fallback with the reason `request-cut`, which `failproofai jev status` totals alongside the reasons above. The rule this gives you: making a call bigger can cost it its clearances, and can never buy one. + +**A message did not fit.** A long prompt you pasted, the agent's last message, or a prompt this evaluator's own store had already capped. **Nothing changes**: the call is judged, cleared and recorded exactly as any other, and it is not counted as a fallback. The length of what you type never decides a verdict, and a cut cannot manufacture consent: where a prompt arrived already capped, you did not ask for this stops being a conclusion that can be drawn from it at all, rather than becoming one. + +The line between the two is who wrote the text. The call is the agent's, and a rule that let its length subtract severity would be a rule the agent can use; your prompt is yours, and treating its length as a signal only ever punished pasting a spec or a stack trace. + +## What leaves the machine + +For each tool call Jev evaluates, one request goes to your provider, carrying: + +- the tool call itself, with secrets such as API keys, bearer tokens and `KEY=` assignments redacted; +- the recent prompts you typed, with text your agent's harness added removed; +- the agent's last message before your latest prompt, labelled as agent-written; +- facts computed locally, such as whether a path is inside the project — the one the session was in at its first reviewed call, [pinned for the session](/ru/reference/jev-intent#the-project-root) — and the current git branch. + +It goes only to the endpoint in your config, under your key. + +## Turn it off + +```bash +failproofai jev remove +``` + +This deletes `~/.failproofai/jev.json`. From the next tool call, hooks run the regex policies exactly as before. The per-session stores under `~/.failproofai/state/semantic/` (recorded prompts in `sessions/`, project roots in `roots/`) are left in place and age out. To stop asking Jev but keep the config, use `failproofai jev setup --mode off` instead. + +## Command reference + +| Command | Outcome | +| --- | --- | +| `failproofai jev --url --key-stdin` | Configure it in one command; the provider comes from the URL's host | +| `failproofai jev --url --token ` | Same, with the key on the command line — your history and the process list see it | +| `failproofai jev setup --provider --key-stdin` | Write the config from a key piped on stdin | +| `failproofai jev setup --provider ` | Same, asking for the key at a masked prompt | +| `failproofai jev setup --key-from-env` | Store no key; read `FAILPROOFAI_JEV_API_KEY` per session | +| `failproofai jev setup --mode observe` | Switch mode (`enforce`, `observe` or `off`), keeping the stored key | +| `failproofai jev setup --model ` / `--base-url ` | Override the model or API base; `default` clears the override | +| `failproofai jev setup --timeout-ms ` | Change the per-call budget | +| `failproofai jev status [--json]` | Configuration, permissions and recent activity; never the key | +| `failproofai jev test [--json]` | One live request: latency and the version that answered | +| `failproofai jev models [--provider ] [--url ] [--json]` | The model ids that endpoint's `/models` reports, marking the configured one | +| `failproofai jev remove` | Delete the config; Jev is off | \ No newline at end of file diff --git a/docs/ru/reference/jev.mdx b/docs/ru/reference/jev.mdx new file mode 100644 index 000000000..14ddd68f8 --- /dev/null +++ b/docs/ru/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Справочник по интеграции Jev" +description: "Конфигурация, провайдеры, ключи, данные запроса и поведение при ошибках для Jev." +icon: "braces" +--- + +Jev имеет два применения в Failproof AI: + +| Применение | Когда запускается | Что возвращает | Начните отсюда | +| --- | --- | --- | --- | +| Оценка сессии | После завершения сессии | Оценка для вопроса с фиксированным ответом | [Оценки Jev](/ru/evaluations/jev) | +| Проверка политики инструмента | До запуска закрытого вызова инструмента | Вердикт вместе с установленными политиками | [Политики Jev](/ru/policies/jev) | + +## Справочные страницы + +| Тема | Подробности | +| --- | --- | +| [Вопросы оценки](/ru/reference/jev-evaluations) | Критерии булевых и упорядоченных оценок, результаты, ограничения и восстановление данных. | +| [Сравнение провайдеров и настройка собственного ключа](/ru/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare и пользовательские endpoints; определение URL, ID моделей, `jev.json`, режимы и коды fallback. | +| [Маршрут FailproofAI Cloud](/ru/reference/jev-cloud) | Разрешения machine-key, автоматическая настройка observe, ограничения использования, состояние подключения и обработка данных. | + +Команды локального CLI перечислены в [справочнике Failproof AI CLI](/ru/reference/failproof-cli). [Справочник локальной панели управления](/ru/reference/local-dashboard#set-up-jev) описывает его параметры Jev и представление активности. \ No newline at end of file diff --git a/docs/ru/reference/mcp.mdx b/docs/ru/reference/mcp.mdx new file mode 100644 index 000000000..96c344f75 --- /dev/null +++ b/docs/ru/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP сервер" +description: "Подключите Claude, Cursor, Codex или другого MCP-клиента к Failproof AI Cloud, используя собственные разрешения." +icon: "plug" +--- + +Подключите инструмент искусственного интеллекта к Failproof AI Cloud и работайте с данными ваших агентов из этого инструмента. Ваш инструмент может запрашивать сессии и события, выполнять только для чтения SQL-запросы, читать панели управления, оповещения, проблемы, аудиты и политики, а также, если у вас есть соответствующее разрешение, вносить изменения, например создавать оповещение или развёртывать политику. + +Каждый вызов выполняется с **вашими собственными** разрешениями в **одной** организации, которую вы выбираете при подключении. + +Адрес один для всех — как для размещённых, так и для самостоятельно размещённых развёртываний: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Подключение клиента + +Добавьте адрес в ваш клиент. При первом использовании инструмента откроется ваш браузер. Выберите, где находится ваш Failproof AI Cloud, войдите в систему, выберите одну организацию и нажмите **Allow**. **Cancel** ничего не подключает. + +На странице отображаются имя приложения и адрес, на который оно возвращается. Приложение, которое не определяется собственным веб-адресом, помечено как **unverified app**, поэтому продолжайте только если вы только что запустили это из своего клиента. + + + + В claude.ai или Claude Desktop перейдите в **Settings → Connectors → Add custom connector**. Назовите его `Failproof AI`, введите адрес, выберите **Add**, затем **Connect**. + + В планах Team и Enterprise владелец сначала добавляет соединитель для организации. Затем каждый человек подключает свою собственную учётную запись. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Затем запустите `/mcp` в Claude Code, выберите `failproofai` и выберите **Authenticate**. + + + Добавьте это в `~/.cursor/mcp.json` или в ``.cursor/mcp.json` вашего проекта: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor отображает **Needs login** рядом с сервером. Выберите его, чтобы войти. + + + Добавьте это в `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Затем запустите `codex mcp login failproofai`. + + + Подходит любой клиент, который поддерживает удалённые MCP-серверы через потоковый HTTP с OAuth. Укажите адрес выше. Не нужно настраивать ID клиента или секрет. + + + +## Одна организация на одно подключение + +Подключение действует только в организации, которую вы выбрали. Чтобы использовать две организации, добавьте сервер дважды под разными именами, например `failproofai-acme` и `failproofai-sandbox`, и подключите каждый к своей организации. + +Демонстрационные организации не принимают подключения. Вместо этого выберите вашу собственную организацию. + +## Разрешения + +Подключение может делать то, что вы можете делать в организации, в рамках приведённого ниже набора. Оно следует вашим текущим разрешениям: если администратор предоставит вам больше, инструмент получит это, и если они возьмут что-то назад, инструмент потеряет это при следующем вызове. + +| Разрешение | Позволяет инструменту | +| --- | --- | +| `events:read` | Список событий, чтение обзора сессии, список агентов и окружений | +| `evaluations:read` | Список сессий, чтение и обобщение результатов оценки и заданий | +| `evaluations:trigger` | Создание оценок, публикация новых версий, включение и отключение, заполнение истории и переоценка сессии | +| `dashboards:read`, `dashboards:write` | Чтение панелей управления или создание, переименование и добавление запросов к ним | +| `queries:read`, `queries:write` | Чтение сохранённых запросов или их сохранение и редактирование | +| `queries:run` | Запуск одного SQL-запроса только для чтения и чтение схемы запроса | +| `alerts:read`, `alerts:write` | Чтение оповещений или создание, редактирование, приостановка, удаление и тестирование их | +| `issues:read` | Чтение проблем, подтверждение их и комментирование | +| `issues:create` | Открытие проблемы по оповещению | +| `issues:close` | Разрешение и закрытие проблем | +| `audits:read`, `audits:write` | Чтение аудитов, запусков и результатов или создание и редактирование аудитов и запуск проверки | +| `code_fixes:read` | Просмотр способа исправления проблемы и получение её контекста для исправления собственным агентом | +| `code_fixes:write` | Запуск исправления в Failproof AI Cloud, которое открывает запрос на слияние в вашу учётную запись GitHub | +| `policies:read`, `policies:write` | Чтение политик, машин и развёртываний или публикация, развёртывание и откат политик | + +Несколько инструментов не требуют разрешения, так как они не читают данные организации: построение ссылок на сессии и события, а также поиск в этой документации. + +Инструмент искусственного интеллекта никогда не может получить доступ к ключам API, пользователям, параметрам или администрированию организации, и не может отправлять события. + +## Одобрение изменений + +Записи сначала спрашивают вас, может ли ваш клиент показать подтверждение. Вы видите, что изменится, и выбираете **Approve this change**, чтобы продолжить. Если вы отклоните или не ответите в течение примерно 4 минут, ничего не изменится. Некоторые клиенты перестают ждать через минуту, поэтому ответьте быстро. + + + Клиент, который не поддерживает подтверждения, не запрашивается, и запись выполняется как только клиент делает вызов. В этом случае подтверждение самого вашего клиента — единственное, поэтому держите его включённым для инструментов записи. + + +## Подключённые приложения и отзыв + +**Settings → Integrations → MCP** перечисляет ваши подключённые приложения в текущей организации с их разрешениями и последним использованием. **Revoke** отключает приложение сразу. Удаление сервера в вашем клиенте также отзывает подключение. + +Вы можете иметь до 5 подключённых приложений на одну организацию. Подключение того же приложения снова заменяет его предыдущее подключение. + +## Самостоятельно размещённые развёртывания + +Выберите **Self-hosted Failproof AI Cloud** при подключении и введите адрес, по которому вы входите. Ваше развёртывание должно быть доступно по открытому HTTPS. + +Вызовы инструментов и их результаты проходят через размещённый шлюз Failproof AI на пути между вашим инструментом искусственного интеллекта и вашим развёртыванием. Шлюз не сохраняет их. + +## Что происходит с вашими данными + +Результаты передаются подключённому инструменту искусственного интеллекта, и поставщик этого инструмента обрабатывает их в соответствии со своими собственными условиями. Для каждого вызова инструмента Failproof AI регистрирует имя инструмента, его результат, время выполнения и организацию, никогда не аргументы или результаты. Посмотрите [политику конфиденциальности](https://befailproof.ai/privacy/). + +## Устранение неполадок + +| Что вы видите | Что делать | +| --- | --- | +| "Started in another browser" | Завершите вход в браузер, открытый клиентом, с разрешёнными куками, и начните заново из клиента | +| Ошибка после **Allow** | Ссылка работает один раз и истекает через 10 минут, поэтому начните заново из клиента | +| Отсутствует ожидаемый инструмент | Вы не имеете его разрешение в этой организации. Попросите администратора. Вам не нужно переподключаться, как только вы его получите | +| Клиент постоянно просит вас войти в систему | Подключение было отозвано, вы покинули организацию или оно не использовалось 90 дней. Подключитесь снова | +| "You have 5 connected apps" | Отзовите один в **Settings → Integrations → MCP**, затем подключитесь снова | + +Всё ещё застряли? Напишите на [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/ru/reference/otel.mdx b/docs/ru/reference/otel.mdx new file mode 100644 index 000000000..4d85a6501 --- /dev/null +++ b/docs/ru/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Подключитесь к OTEL для coding agents, проверьте доставку и восстановите предыдущие настройки." +icon: "radio" +--- + +`failproofai otel` настраивает опциональную отправку данных OpenTelemetry в FailproofAI Cloud. Сначала подключите машину с помощью `failproofai config` и попросите администратора организации включить **Settings → OpenTelemetry**. + +Интерактивная настройка спрашивает об OpenTelemetry после поля Cloud key и выбора агента. Опциональный шаг по умолчанию имеет значение No. Выберите Yes, чтобы выбрать OTEL агентов; тот же код включения запустится после записи соединения. Нажатие Esc перед завершением настройки не применит никаких изменений. Автоматическая настройка, предоставленный ключ, режим с открытым исходным кодом и сохранённое соединение вас не подключают. + +## Включить агента + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Поддерживаемые агенты: `claude`, `codex` и `copilot` (VS Code). Настройка Copilot требует исполняемого файла VS Code или установленного расширения Copilot. Оставшейся директории настроек недостаточно; настройка пропускает Copilot, если ничего не найдено. + +`--local` отправляет на локальный relay вместо прямой отправки в Cloud. Copilot использует relay автоматически, потому что его настройки не могут хранить заголовок аутентификации. + +Relay слушает только на вашей машине. Ваш настроенный FailproofAI daemon заметит изменение в течение нескольких секунд; вам не нужно его перезагружать. Если другое приложение использует порт relay, состояние сообщает о нём как отключённом, и daemon продолжает работать. + + +Захват текста включён по умолчанию. Добавьте `--no-content`, чтобы опустить приглашения и детали инструментов. Разные версии агентов могут предоставлять разные элементы управления содержимым; проверьте, что экспортирует ваш агент, перед использованием с чувствительными данными. + + +Codex экспортирует только логи разговоров, не внутренние трассировки выполнения или метрики. Явный `log_user_prompt = false` в конфигурации Codex остаётся отключённым; enable выведет примечание, когда сохранит этот выбор. + +### Выберите один путь отчётности + +Если отчётность транскрипта включена для агента, настройка спросит: + +> failproofai уже отправляет сеансы Claude Code в Cloud. Отправить их с OTEL вместо этого? Загрузка транскрипта для Claude Code прекратится. + +По умолчанию No. `--yes` принимает переключение без запроса. Другие агенты и применение политик не затронуты. + +Настройка Codex ждёт подтверждения от daemon об изменении collector перед записью его параметров exporter. Если подтверждение истечёт, настройка предупредит вас подождать перед запуском Codex. + +Config v2 хранит запомненный список трассировки в `agents.selected` (а историю обнаружения в `agents.seen`). Предпочтение транскрипта для каждого агента остаётся в `collector.agents..sessions`, владение OTEL в `otel.agents`, и параметры relay в `collector.otlp.enabled` / `collector.otlp.port`. Эти отдельные ключи сохраняют старые конфигурации OTEL читаемыми: настройка может изменить список трассировки без потери предпочтения транспорта или состояния, необходимого для восстановления настроек агента. + +## Проверить настройку + +```bash +failproofai otel status +``` + +Статус показывает каждого агента, управляются ли его настройки FailproofAI, его назначение, переключатель ingestion организации, состояние relay и последний результат загрузки relay. + +`unknown` для переключателя организации означает, что сервер его не предоставил или не мог быть достигнут. Это не ошибка и не препятствует конфигурации на более старой версии Cloud. + +Если Cloud ещё не поддерживает OTEL, relay сохраняет отклонённые экспорты вместо их отбрасывания. Если ingestion организации отключён, `enable` не пишет ничего и выходит с ошибкой; попросите администратора сначала его включить. + +## Вывести конфигурацию для приложения + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +Выводом является блок переменных окружения shell для exporter OTLP/HTTP. Вывод Cloud устанавливает `OTEL_EXPORTER_OTLP_ENDPOINT` на OTLP base Cloud, `https:///otel`, и exporter добавляет `/v1/`; переменная для конкретного сигнала, такая как `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, нуждается в полном `https:///otel/v1/logs`. Локальный вывод указывает на relay, `http://127.0.0.1:`. Вывод Cloud включает настроенный ключ API; обращайтесь с ним как с секретом. Локальный вывод опускает ключ. Для использования локального вывода сначала включите локального агента, чтобы relay был запущен. + +## Восстановить предыдущие настройки + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable восстанавливает только настройки, которые написал FailproofAI, сохраняет неrelated изменения и восстанавливает предыдущий выбор отчётности транскрипта каждого агента. Когда последний управляемый локальный агент отключен, relay прекращает принимать экспорты. + +Для Codex, disable также записывает `collector.agents.codex.sessions_resume_after` (epoch миллисекунды). Существующие байты rollout рассматриваются как доставленные, поэтому сеансы, захваченные с OTEL, не загружаются повторно; более поздние дополнения всё равно проходят через отчётность транскрипта. + +Каждая команда поддерживает `--help`. См. [OpenTelemetry в Cloud](/ru/agenteye/opentelemetry) для примеров приложений и coding-agents. \ No newline at end of file diff --git a/docs/ru/reference/slack.mdx b/docs/ru/reference/slack.mdx new file mode 100644 index 000000000..427c35461 --- /dev/null +++ b/docs/ru/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack-приложение" +description: "Задавайте вопросы Failproof Assistant из Slack, получайте диаграммы в ветке и одобряйте изменения кнопкой." +icon: "slack" +--- + +Задавайте вопросы [Failproof Assistant](/ru/sessions/assistant) из Slack. Упомяните приложение в канале, отправьте ему прямое сообщение или используйте `/failproof <вопрос>`. Ответы используют **ваши собственные** разрешения Failproof AI, диаграммы появляются в ветке, и все, что может что-то изменить, сначала попросит вашего одобрения. + +Существует одно официальное приложение. Оно работает одинаково независимо от того, размещен ли ваш Failproof AI Cloud в облаке или локально. + + + Ответы генерируются моделями ИИ и могут быть неточными. Проверьте все важное по связанным источникам данных. + + +## Подключите рабочее пространство + +Вам нужно разрешение `settings:write` в Failproof AI и в Slack быть администратором или владельцем рабочего пространства, либо быть тем, кто добавляет приложение. + + + + 1. Перейдите в **Settings → Integrations** и выберите **Add to Slack**. + 2. Одобрите приложение в Slack. + 3. Вернитесь в Failproof AI и подтвердите подключение рабочего пространства к вашей организации. + + + 1. Добавьте приложение, затем откройте его вкладку **Home**. + 2. Выберите **Continue with FailproofAI Cloud** или **Use my own URL** и введите адрес, по которому вы входите. + 3. Нажмите кнопку продолжения, войдите, выберите организацию и подтвердите. Ссылка работает один раз и истекает через 10 минут. + + + +Одно рабочее пространство подключается к одной организации, и одна организация к одному рабочему пространству. + +Нет учетной записи? [Создайте её](https://app.befailproof.ai/login) сначала, затем подключитесь. + +## Кто вы в Slack + +В первый раз, когда вы задаете вопрос, приложение определяет, какой участник вы: + +- **Автоматически по email**, когда вы полноценный участник подключенного рабочего пространства, ваш email Slack подтвержден и ровно один участник организации использует этот email. +- **В противном случае** вы получаете приватную кнопку **Link your account**, которая открывает Failproof AI и связывает вашего пользователя Slack с вашей учетной записью. + +## Задайте вопрос + +| Где | Как | +| --- | --- | +| В канале | Упомяните приложение. Отвечайте в его ветке для продолжения без упоминания | +| В прямом сообщении | Напишите приложению | +| В групповом прямом сообщении с приложением | Упомяните его, затем отвечайте в его ветке для продолжения | +| В Slack Connect канале | Упомяните приложение | +| В любом разговоре, в котором находится приложение | `/failproof <вопрос>` запускает ветку с ответом | +| `/failproof help` | Смотрите, что может делать приложение | +| `/failproof status` | Смотрите, какая организация подключена и под каким именем вы связаны | +| `/failproof link` | Смотрите, с какой учетной записью Failproof AI вы связаны | + +Одна ветка — это один разговор. Коллеги могут упомянуть приложение в той же ветке, и оно ответит каждому с их собственными разрешениями. Только тот, кто начал ветку, может продолжать её без упоминания. + +Когда ответ содержит данные, приложение публикует диаграмму или таблицу со ссылкой для открытия в Failproof AI. + +## Одобрите изменения + +Каждое изменение, которое делает помощник, сначала показывает кнопки **Approve** и **Cancel**, и Slack еще раз спрашивает перед **Approve**. Только тот, кто задал вопрос, может ответить на них, кнопки истекают через 5 минут, и изменение делается с разрешениями этого человека. + +Из Slack помощник может менять сохраненные запросы и панели управления, оценки, оповещения, аудиты, проблемы и политики, а также предлагать исправления кода, если у вас есть соответствующие разрешения. Он не может менять API-ключи, пользователей или параметры. + +## Предпросмотры ссылок + +Ссылки на проблемы, сессии и оценки Failproof AI, вставленные в Slack, разворачиваются в карточки в облачном Failproof AI Cloud. Карточка показывает только то, что может видеть тот, кто её запустил. Ссылки на локальный адрес не разворачиваются, но карточки в собственных ответах помощника все равно появляются. + +## Slack Connect каналы + +Люди из другого рабочего пространства могут использовать приложение, если они являются участниками организации, после связывания их учетной записи. Ответы видны всем в разговоре, включая людей, которые не являются участниками вашей организации, поэтому спрашивайте там, где все смогут увидеть ответ. + +Приложение ответит только когда в канале у каждого другого рабочего пространства будет кто-то, связанный с организацией. До этого оно расскажет спрашивающему почему. + +## Разрешения, которые запрашивает приложение + +| Разрешение Slack | Зачем | +| --- | --- | +| `app_mentions:read` | Узнавать, когда кто-то упоминает приложение | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Получать прямые сообщения и ответы в ветках приложения. Приложение игнорирует другие сообщения и никогда не читает прошлые сообщения разговора | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Проверять, в каком типе разговора оно находится, чтобы знать, кто может видеть ответ | +| `chat:write` | Публиковать ответы и кнопки одобрения | +| `commands` | Предоставлять `/failproof` | +| `files:write` | Публиковать диаграммы | +| `links:read`, `links:write` | Показывать предпросмотры вставленных ссылок Failproof AI | +| `users:read`, `users:read.email` | Связывать вас с вашей учетной записью Failproof AI и показывать имена | + +## Отключите + +Перейдите в **Settings → Integrations** и выберите **Disconnect**, используйте **Disconnect** на вкладке **Home** приложения или удалите приложение из Slack. + +Любой из этих способов удаляет подключение рабочего пространства, токен бота, связанные учетные записи и записи ветей. Прошлые разговоры Slack остаются читаемыми на панели управления. Организация может затем подключить любое рабочее пространство сразу же. + +## Данные и конфиденциальность + +Вопросы и ответы сохраняются как разговоры на панели управления вашей организации под именем того, кто начал ветку. Данные Slack никогда не используются для обучения моделей ИИ. Смотрите [политику конфиденциальности](https://befailproof.ai/privacy/) для получения информации о том, что приложение получает и как долго это хранится. + +## Решение проблем + +| Что вы видите | Что делать | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | Администратор рабочего пространства открывает вкладку **Home** приложения и выбирает одну | +| "This link expired or was already used." | Выберите ваш Cloud снова на вкладке **Home** для новой ссылки | +| "This org is already connected to a Slack workspace." | Сначала отключите её в параметрах | +| "That Slack workspace is connected to another org." | Сначала отключите её от этой организации | +| "Link your account to use the assistant." | Выберите кнопку и подтвердите в Failproof AI | +| Приложение не отвечает в групповом прямом сообщении | Добавьте приложение в Slack еще раз, чтобы предоставить ему разрешения групп. Ваше подключение сохранится | +| "I won't post answers from your organization here" | Кто-то из этого рабочего пространства, который является участником организации, упоминает приложение и связывает их учетную запись | + +Все еще застряли? Напишите на [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/ru/sessions/sentiment.mdx b/docs/ru/sessions/sentiment.mdx new file mode 100644 index 000000000..c11022275 --- /dev/null +++ b/docs/ru/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Анализ тональности" +description: "Находите расстроенные, запутанные и корректирующие сообщения с помощью оценок тональности Jev." +icon: "smile" +--- + +Jev оценивает каждое сообщение, отправленное человеком вашим агентам, по шкале от 0 до 100 по четырём эмоциям — **гнев**, **разочарование**, **радость** и **замешательство** — а также по трём сигналам о работе агента: + +- **Correcting**: человек говорит, что агент что-то неправильно понял. +- **Resolved**: человек подтверждает, что агент решил его проблему. +- **Doubtful**: человек сомневается в том, правда ли ответ агента, или действительно ли он сделал свою работу. + +Используйте анализ тональности, чтобы найти беседы, где люди теряют терпение, агентов, которых постоянно корректируют, и ответы, которые хорошо воспринимаются. Это встроенная система оценки Jev; вам не нужно создавать отдельное оценивание. Для собственного вопроса с фиксированным ответом [создайте оценку Jev](/ru/evaluations/jev). + + + Анализ тональности отключён до тех пор, пока администратор не включит его для организации. Jev делает один запрос на оценку на сообщение и получает это сообщение с ответом агента перед ним. Оценка использует бюджет модели вашей организации. + + +## Включение функции + +1. Перейдите в **Administration → Settings**. +2. В разделе **Human input sentiment** переведите переключатель в положение **on** и сохраните. + +Сообщения за последний день оцениваются в первую очередь. После этого новые сообщения оцениваются в течение минуты или двух после поступления. + +## Найдите беседу для проверки + +Откройте **Observe → Sentiment**. Отфильтруйте по времени, среде, агенту или ID сессии. Заголовок показывает количество сообщений и сессий, сколько сообщений **flagged**, и называет главный сигнал. Сообщение помечается флажком, когда оценка гнева, разочарования, корректирования, замешательства или сомнения достигает 35 из 100. + +![Панель управления анализом тональности, показывающая количество сообщений и сессий, помеченные сообщения и оценки Jev за время.](/images/dashboard/sentiment-overview.png) + +Используйте **Score over time** для сравнения сигналов. Выберите оценки для отображения, затем выберите точку, чтобы увидеть сообщения в этом временном диапазоне. Таблица **By agent** показывает, где концентрируется сигнал. В **Messages** сортируйте по самой сильной отрицательной оценке или выберите одну оценку. Откройте сообщение в его сессии, чтобы прочитать окружающую беседу перед тем, как решить, что пошло не так. + +![Список сообщений анализа тональности, отсортированный по самой сильной отрицательной оценке, со ссылкой на каждую исходную сессию.](/images/dashboard/sentiment-messages.png) + +## Какие сообщения оцениваются + +Только сообщения, написанные человеком: + +- Сообщения, которые ваши пользовательские агенты записывают как пользовательский ввод с помощью SDK. +- Подсказки, набранные в Claude Code, Codex, OpenCode, pi, Hermes и OpenClaw, когда отправляются стенограммы сессий (по умолчанию). Запланированные задания, введённые инструкции, передача управления под-агентом и другой текст, который создаёт собственная среда выполнения агента, не оцениваются. То же касается неинтерактивных запусков, таких как `claude -p`, `codex exec` и `hermes -z`: эти подсказки написал сценарий, а не человек. + +Оценка судит о собственных словах человека. Короткая, резкая инструкция, такая как «исправь это», не считается гневом, а задание вопроса не считается замешательством. Новый запрос — это не корректирование, а благодарность сама по себе не считается разрешением проблемы. \ No newline at end of file diff --git a/docs/ru/start/use-jev.mdx b/docs/ru/start/use-jev.mdx new file mode 100644 index 000000000..c288c4796 --- /dev/null +++ b/docs/ru/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Использование Jev" +description: "Настройте оценки Jev для завершённых сессий или политики Jev для проверки вызовов инструментов в реальном времени." +icon: "sparkles" +--- + +Jev помогает на двух этапах работы агента: оценить завершённую сессию по известным ответам или проверить вызов инструмента в контексте того, что вы просили делать агента. + + + + Используйте оценку Jev, когда завершённую сессию можно оценить по вопросу с несколькими известными ответами, например «Клиент попросил возврат? Ответьте да или нет.» Это помогает найти закономерности в сессиях. + + ## Создание оценки + + В облачной панели откройте **Analyze → eval authoring → new eval**. Введите один вопрос с фиксированным ответом, выберите **draft** и убедитесь, что была выбрана оценка классификатора. [Протестируйте её](/ru/evaluations/test) на реальных сессиях, затем разверните. + + ![Форма для создания общей оценки, где вы описываете вопрос, проверяете черновик и развёртываете его. На скриншоте показан черновик кода; используйте вопрос с фиксированным ответом для Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Чтение оценок + + После завершения новой сессии откройте **Observe → Evaluations** или используйте облачный CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI читает оценки; создание оценки Jev в настоящий момент использует панель. Смотрите [Jev evaluations](/ru/evaluations/jev) для типов вопросов и примеров. + + + Используйте проверку политик Jev, когда политика, основанная на сопоставлении строк, нуждается в контексте вашего запроса, чтобы решить, безопасен ли вызов инструмента. Начните с режима **observe**, чтобы вы могли проверить ответы Jev, пока установленные политики всё ещё принимают решение по каждому вызову. + + Проверки Jev поступают из пакета; Failproof AI не поставляет ни одного. Пока вы их не установите, Jev ничего не спрашивает, даже если он настроен: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Настройка облачного Jev + + В облачной панели откройте **Administration → Keys** и создайте ключ с предустановкой **machine**. Используйте его с `failproofai config` как показано в [quickstart](/ru/start/quickstart). На машине без существующей конфигурации Jev это активирует облачный Jev в режиме observe. Проверьте соединение с помощью: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Использование собственной конечной точки + + В локальной панели откройте **Settings → Jev**. Выберите провайдера, вставьте его токен, выберите **observe** и включите Jev. + + ![Панель локальных параметров Jev с провайдером, полем токена и выбранным режимом observe.](/images/dashboard/jev-settings.png) + + Или настройте и протестируйте вашу конечную точку из терминала: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Попросите подключённого агента использовать инструмент чтения файлов на `README.md`. Убедитесь, что вызов инструмента появляется в сессии, затем проверьте его в разделе **Policies → Activity** в локальной панели. Когда результаты observe выглядят правильно, в [Jev policies](/ru/policies/jev) объясняется, когда их применять. Для деталей провайдера и конфигурации смотрите [integration reference](/ru/reference/jev). + + \ No newline at end of file diff --git a/docs/sessions/overview.mdx b/docs/sessions/overview.mdx index c03551eb1..6f30e6abf 100644 --- a/docs/sessions/overview.mdx +++ b/docs/sessions/overview.mdx @@ -16,6 +16,10 @@ Follow one agent run from its goal through model calls, tools, and final respons ## Find a session +If a session was held in cold storage after you reached your run allowance, +raising the allowance within the same billing window releases eligible sessions +oldest first. Delivery retries do not make a session consume allowance twice. + 1. In the Cloud sidebar, go to **Observe → Sessions**. diff --git a/docs/sessions/sentiment.mdx b/docs/sessions/sentiment.mdx new file mode 100644 index 000000000..e89713713 --- /dev/null +++ b/docs/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Sentiment analysis" +description: "Find frustrated, confused, and corrective messages with Jev sentiment scores." +icon: "smile" +--- + +Jev scores each message a person sends your agents from 0 to 100 for four feelings — **angry**, **frustrated**, **happy** and **confused** — and three signals about how the agent is doing: + +- **Correcting**: the person says the agent got something wrong. +- **Resolved**: the person confirms the agent solved their problem. +- **Doubtful**: the person questions whether the agent's answer is true, or whether it really did the work. + +Use sentiment analysis to find conversations where people are losing patience, agents they keep correcting, and replies that land well. This is built-in Jev scoring; you do not need to author an evaluation. For your own fixed-answer question, [create a Jev eval](/evaluations/jev). + + + Sentiment is off until an admin turns it on for the organization. Jev makes one scoring request per message and receives that message with the agent reply before it. Scoring uses your organization's model budget. + + +## Turn it on + +1. Go to **Administration → Settings**. +2. Under **Human input sentiment**, switch it **on** and save. + +Messages from the last day are scored first. After that, new messages are scored within a minute or two of arriving. + +## Find a conversation to review + +Open **Observe → Sentiment**. Filter by time, environment, agent, or session ID. The header counts messages and sessions, shows how many messages are **flagged**, and names the top signal. A message is flagged when an angry, frustrated, correcting, confused, or doubtful score reaches 35 out of 100. + +![The Sentiment dashboard showing message and session counts, flagged messages, and Jev scores over time.](/images/dashboard/sentiment-overview.png) + +Use **Score over time** to compare signals. Choose the scores to show, then select a point to see that time bucket's messages. The **By agent** table shows where a signal is concentrated. In **Messages**, sort by the strongest negative score or select a single score. Open a message in its session to read the surrounding conversation before deciding what failed. + +![The Sentiment message list sorted by strongest negative score, with a link to each source session.](/images/dashboard/sentiment-messages.png) + +## Which messages are scored + +Only messages a person wrote: + +- Messages your custom agents record as human input with the SDK. +- Prompts typed into Claude Code, Codex, OpenCode, pi, Hermes and OpenClaw, when session transcripts are sent (the default). Scheduled jobs, injected instructions, sub-agent hand-offs and other text the agent's own runtime writes are not scored. Nor are non-interactive runs such as `claude -p`, `codex exec` and `hermes -z`: a script wrote those prompts, not a person. + +Scoring judges the person's own words. A short, blunt instruction such as "fix it" is not counted as anger, and asking a question is not counted as confusion. A new request is not a correction, and thanks on their own do not count as resolved. diff --git a/docs/start/quickstart.mdx b/docs/start/quickstart.mdx index 6d98a26d7..86ab4af1a 100644 --- a/docs/start/quickstart.mdx +++ b/docs/start/quickstart.mdx @@ -26,26 +26,31 @@ This quickstart gets one machine reporting sessions, runs an audit, and deploys - ## Before you start - -1. Open the [Failproof AI dashboard](https://app.befailproof.ai) and create an account or sign in with your work email. -2. Go to **Administration → Keys** and create a key with `events:add` and `policies:pull`. -3. Copy the one-time secret, then read it into a shell on the target machine. `read -s` takes it at a prompt that does not echo, so it never appears in a command: - -```bash -read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY -``` - ## Install ```bash npm install -g failproofai - FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config + failproofai config ``` - That one command is the whole of setup: it installs the local daemon (root once), wires hooks into every agent CLI it finds, and connects this machine to Cloud. Passing the key through the environment rather than `--token` keeps it out of `ps`, where every user on the machine can read a command's arguments. It does not keep it out of shell history — reading it with `read -s` is what does that. In CI, inject it as a masked secret and keep shell tracing (`set -x`) off, or the trace prints it. + That one command is the whole of setup: it installs the local daemon (root once), wires hooks into every agent CLI it finds, and connects this machine to Cloud. + + At **Connect to cloud**, setup starts logging you in to FailproofAI Cloud straight away (press Tab for the other options: paste an API key, or use open source). It opens a link in your browser (over SSH, or on a machine with no display, it prints the link so you can open it on any device). Sign up or sign in, confirm the org — or create one right there — and click **Authorize**. The key's name and permissions are set for you. You do not need an account beforehand. + + The terminal notices on its own and shows who approved it and for which org. Confirm the agents to trace, and setup finishes. The machine's key is created only at that point, after the daemon is installed, so a run you abandon leaves no key behind; it appears under **Administration → Keys** marked **cli login**, where you can revoke it. + + + In the [Failproof AI dashboard](https://app.befailproof.ai), go to **Administration → Keys** and create a key with `events:add` and `policies:pull`. If you plan to use [Jev through FailproofAI Cloud](/reference/jev-cloud), choose the **machine** preset, which also grants `jev:evaluate`. Copy the one-time secret and read it into a shell on the target machine — `read -s` takes it at a prompt that does not echo: + + ```bash + read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config + ``` + + Passing the key through the environment rather than `--token` keeps it out of `ps`, where every user on the machine can read a command's arguments. It does not keep it out of shell history — reading it with `read -s` is what does that. In CI, inject it as a masked secret and keep shell tracing (`set -x`) off, or the trace prints it. In an interactive run you can also pick **Paste an API key** at **Connect to cloud** instead. + Session transcripts are sent by default. Add `--no-transcripts` to report hook activity and policy decisions without transcript content. @@ -80,7 +85,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies add FailproofAI/policies ``` - The pack is fetched from its GitHub release, checksum-verified, and pinned to the exact tag it resolved. It carries 38 policies and switches on the 10 its manifest marks as safe to enable unattended. Use them to see local policy decisions and try enforcement before Failproof AI audits your sessions and writes policies for your agents. + The pack is fetched from its GitHub release, checksum-verified, and pinned to the exact tag it resolved. It carries 39 policies and switches on the 10 its manifest marks as safe to enable unattended. Use them to see local policy decisions and try enforcement before Failproof AI audits your sessions and writes policies for your agents. Read any pack before taking it with `failproofai policies show /`, and see [policy packs](/policies/packs) for taking only part of one. @@ -99,3 +104,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY + +## Jev setup + +Use [Jev](/start/use-jev) to score finished sessions against a question with known answers, or to review tool calls in context before they run. The **Use Jev** page has both setup paths. diff --git a/docs/start/use-jev.mdx b/docs/start/use-jev.mdx new file mode 100644 index 000000000..5fd51f339 --- /dev/null +++ b/docs/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Use Jev" +description: "Set up Jev evaluations for finished sessions or Jev policies for live tool-call review." +icon: "sparkles" +--- + +Jev helps at two points in an agent run: score a finished session against known answers, or review a tool call in the context of what you asked the agent to do. + + + + Use a Jev eval when a finished session can be scored against a question with a few known answers, such as “Did the customer ask for a refund? Answer yes or no.” It helps you find patterns across sessions. + + ## Create an eval + + In the Cloud dashboard, open **Analyze → eval authoring → new eval**. Enter one fixed-answer question, select **draft**, and check that it chose a classifier score. [Test it](/evaluations/test) on real sessions, then deploy it. + + ![The shared eval authoring form where you describe a question, review the draft, and deploy it. This screenshot shows a code draft; use a fixed-answer question for Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Read the scores + + After a new session completes, open **Observe → Evaluations** or use the Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + The CLI reads scores; creating a Jev eval currently uses the dashboard. See [Jev evaluations](/evaluations/jev) for question types and examples. + + + Use Jev policy review when a string-matching policy needs the context of your request to decide whether a tool call is safe. Start in **observe** mode so you can inspect Jev's answers while your installed policies still decide each call. + + Jev's checks come from a pack; Failproof AI ships none. Until you install them, Jev asks nothing, even when it is configured: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Set up Cloud Jev + + In the Cloud dashboard, open **Administration → Keys** and create a key with the **machine** preset. Use it with `failproofai config` as shown in the [quickstart](/start/quickstart). On a machine without an existing Jev configuration, this enables Cloud Jev in observe mode. Check the connection with: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Use your own endpoint + + In the local dashboard, open **Settings → Jev**. Choose the provider, paste its token, select **observe**, and turn Jev on. + + ![The local Jev settings panel with a provider, token field, and observe mode selected.](/images/dashboard/jev-settings.png) + + Or configure and test your endpoint from a terminal: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Ask a hooked agent to use its file-reading tool on `README.md`. Confirm that tool call appears in the session, then inspect it under **Policies → Activity** in the local dashboard. Once the observe results look right, [Jev policies](/policies/jev) explains when to enforce. For provider details and configuration, see the [integration reference](/reference/jev). + + diff --git a/docs/tr/admin/product-analytics.mdx b/docs/tr/admin/product-analytics.mdx new file mode 100644 index 000000000..22c8c706b --- /dev/null +++ b/docs/tr/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Ürün analitikleri" +description: "Failproof AI Cloud'un kendisi hakkında gönderdiği kullanım telemetrisi, hiçbir zaman hangi verilerin toplanmadığı ve nasıl kapatılacağı." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud, yazılımın kendisi hakkında kullanım telemetrisi **yazılım hakkında** bakımcılarına gönderir. Aracılarınızın verilerini hiçbir zaman içermez. Kendi kendine barındırılan bir kurulumda varsayılan olarak açıktır ve kapatabilirsiniz. + +## Hangi veriler toplanır + +Her olay beş boyut taşır ve bir kişiyi tanımlayacak hiçbir şey içermez: + +| Boyut | Örnek | Nedir | +| --- | --- | --- | +| `product` | `agenteye` | Hangi ürün gönderdi | +| `component` | `dashboard`, `server`, `cli` | Ürünün hangi bölümü gönderdi | +| `app_version` | `0.0.1-beta.81` | Çalıştırdığınız derleme | +| `deployment_kind` | `self_hosted` | Bunun müşteri kurulumu, demo, QA veya geliştirici makinesi olup olmadığı | +| `org_id` | bir UUID | Eylemin gerçekleştiği organizasyon, opak bir tanımlayıcı olarak | + +Bunlara ek olarak, olaylar **neyin kullanıldığını kaydeder, içinde ne olduğunu asla kaydetmez**: hangi sayfanın görüntülendiği (gerçek URL asla değil, `/:org/sessions/:id` gibi rota deseni olarak), kaç tane filtrenin hangi türde uygulandığı, bir eylemin başarılı olup olmadığı ve ne kadar sürdüğü. + +Slack uygulaması çalışma alanı bağlantı ve bağlantıları kesme, hesap bağlantıları, sorulan sorular, yayınlanan grafikler, onay kararları ve hatalı kategorileri kaydeder. Hiçbir zaman Slack çalışma alanı, kullanıcı veya kanal kimliklerini, e-posta, soruları, yanıtları, SQL veya token'ları içermez. + +### Organizasyonunuzun adı + +Opak `org_id` ile birlikte, organizasyonunuzun adı, URL yolu ve kontrol paneli adresini bir kez, her olay yerine bir organizasyon kaydında kaydederiz. Bu, benimseme konusunda bir modeli veya bildirdiğiniz bir sorunu araştırdığımızda hesabın hangi konta ait olduğunu söylemek için bize yardımcı olur. Bu, ürünün sizin hakkında gönderdiği tek tanımlayıcı bilgidir. + +### Kullanım toplamlarınız + +Sunucu, her organizasyonun ölçülen kullanım toplamlarını, Kullanım sayfasında gördüğünüz aynı numaraları rapor eder. Bunlar yalnızca sayılarıdır: olaylar, oturumlar, aracılar, ortamlar, değerlendirme çalışmaları, puanlar, denetim çalışmaları, kaydedilmiş sorgular, kontrol panelleri, uyarılar, sorunlar, API anahtarları ve üyeler, ek olarak ölçüm penceresinin tarihleri. Tanımlayıcı, ad veya sorgu metni içermezler ve kimse oturum açmış olup olmadığına bakılmaksızın gelirler. + +## Hiçbir zaman hangi veriler toplanmaz + +- **İstemler, model yanıtları veya olay içeriği yoktur**, metni, ön ek veya hash olarak değil +- **Oturum, aracı veya izleme tanımlayıcıları yok** +- **Değerlendirici puanı adları yok** +- **Hata iletileri, istisna metni veya yanıt gövdeleri yok**, yalnızca bir durum kodu ve sabit bir listeden bir kategori +- **Araç argümanları, SQL veya sorgu metni yok** +- **Bağlı uygulama ayrıntıları yok.** MCP istemcisini bağlamak veya iptal etmek en fazla bir izin sayısı gönderir, hiçbir zaman uygulamanın adı veya herhangi bir token +- **E-posta adresleri yok** +- **Referrer URL'leri veya sorgu dizesi yok** +- **Ekran kaydı, DOM yakalama veya tıklama ve imleç takibi yok** + +## Kendi kendine barındırılan kurulumda kapatın + +Hem kontrol paneli hem de sunucu üzerinde `DO_NOT_TRACK=1` ayarlayın. Ayrı ayrı karar verirler, bu nedenle sadece birinde ayarlamak diğerini rapor etmek için bırakır. Değişikliğin uygulanması için sunucuyu yeniden başlatın. + +Yayın README'niz diğer iyileştirme ayarlarını ve telemetrinin kapalı olduğunu doğrulamanın nasıl yapılacağını açıklar. + +## Opt-out yaparken bir ping + +Ürün ayarı yerine `DO_NOT_TRACK` ile opt-out yaparsanız, kontrol paneli **bir anonim ping** gönderebilir ve bunu işlem başına 1000'de 1 olasılıkla kaydedebilir. Bu, telemetriyi kapatmanın kaç operatör tarafından yapıldığını bize söyler. Hiçbir tanımlayıcı içermez: organizasyon, kullanıcı, ana bilgisayar adı, URL veya IP yok, yalnızca ürün, bileşen, sürüm, dağıtım türü ve neden. Opt-out yapılan sunucu hiçbir şey göndermez. + +`DO_NOT_TRACK` kullandığınızda hiçbir zaman gönderilmez, bu nedenle bu, politikanız herhangi bir giden telemetriyi yasaklıyorsa kullanılması gereken ayardır. + +## Nereye gider + +PostHog'a (`us.i.posthog.com`) TLS üzerinde 443 numaralı bağlantı noktasında. Bu bir ana bilgisayar adıdır, bu nedenle tek bir çıkış kuralı ile de engelle yebilirsiniz. + +Kişisel bilgileri daha geniş olarak nasıl işlediğimize ilişkin bilgi için [gizlilik politikası](https://befailproof.ai/privacy/) bölümüne bakın. \ No newline at end of file diff --git a/docs/tr/agenteye/opentelemetry.mdx b/docs/tr/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..0e79a1a48 --- /dev/null +++ b/docs/tr/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "Kodlama ajanı ve uygulama telemetrisini FailproofAI Cloud'a OTLP ile gönderin." +icon: "radio" +--- + +OpenTelemetry, standart OTLP/HTTP protokolünü kullanarak ajan izlerini, günlükleri ve metrikleri FailproofAI Cloud'a göndermenizi sağlar. Bu isteğe bağlıdır. Mevcut FailproofAI entegrasyonlarınız bunu etkinleştirmeden çalışmaya devam eder. + +## Kuruluşunuz için alımı etkinleştirin + +Bir kuruluş yöneticisi **Ayarlar → OpenTelemetry** açar ve alımı etkinleştirir. Ajan raporlaması için kullanılan aynı izin olan `events:add` izni ile bir Cloud API anahtarı kullanın. + +Alım kapatılıysa, Cloud OTLP dışa aktarımlarını reddeder, bu nedenle `failproofai otel enable` hiçbir şey değişmez ve ajanlarınız oturumları her zamanki gibi göndermeye devam eder. Kuruluş anahtarını kontrol etmek için `failproofai otel status` çalıştırın ve bir yöneticiye bunu etkinleştirmesini isteyin. + +## Bir kodlama ajanı bağlayın + +`failproofai config` ile makinenizi bağlayın, ardından bir ajan seçin: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +Kurulum komutu Claude Code, Codex ve Copilot'u destekler ve uygun şekilde Cloud veya yerel kimlik doğrulanmış bir aktarıcı seçer. Copilot yerel aktarıcıyı otomatik olarak kullanır. Aktarıcıyı kullanmadan önce yapılandırılmış FailproofAI daemon'ını başlatın. + +FailproofAI zaten bir ajanın oturum transkripsiyonlarını gönderiyorsa, kurulum o ajanı OTEL'e geçirip geçirmeyeceğinizi sorar. Varsayılan Hayır'dır. Kabul etmek o ajan için transkript yüklemelerini durdurur; ilke yaptırımını veya diğer ajanlardan raporlamayı değiştirmez. + +## Bir uygulamayı bağlayın + +Uygulamanızın OpenTelemetry enstrümentasyonunu şu ortam değişkenleriyle kullanın: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +Uç nokta Cloud'ın OTLP tabanıdır, `https://app.befailproof.ai/otel`; dışa aktarıcınız `/v1/traces`, `/v1/logs` veya `/v1/metrics` öğesini kendisi ekler. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` gibi sinyal başına değişkenler olduğu gibi kullanılır, bu nedenle tam yolu gerekli, örneğin `https://app.befailproof.ai/otel/v1/logs`. + +`` yerine API anahtarınızı girin. Sırrı kabuk geçmişinin, ekran kayıtlarının ve işlenen yapılandırmanın dışında tutun. Yapılandırılmış bir makine için `failproofai otel env --service my-agent` bloğu mevcut anahtarıyla yazdırır. Çıktısı bir kimlik bilgisi içerir. + +Cloud, protobuf veya JSON olarak, gzip sıkıştırılmış istekler de dahil olmak üzere izler, günlükler ve metrikler için OTLP/HTTP dışa aktarımlarını kabul eder. OTLP/gRPC'yi kabul etmez. + +Metrikler dışa aktarıcı uyumluluğu için alınır ancak depolanmaz veya görüntülenmez. Desteklenen ajan izleri ve kodlama ajanı günlükleri oturumlar haline gelir; ajanın dışa aktarmadığı alanlar eksiktir. + +## İstem metnini yakala + + +Metin yakalaması istemler, araç argümanları ve diğer hassas içeriği içerebilir. `failproofai otel enable` bunu etkinleştirir. İstem ve araç ayrıntısı yakalamasını kapalı tutmak için `--no-content` ekleyin. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Manuel olarak yapılandırdığınız bir ajan için kendi içerik yakalaması kontrolleri kullanın: + + + + Bu değişkenleri ajanın ortamına yukarıdaki uygulama bloğunun yanında ekleyin: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + İstemler ve araç ayrıntılarını yakalamaktan kaçınmak için her iki içerik değişkenini `0` olarak ayarlayın. + + + Codex'in kullanıcı yapılandırmasında OTEL ayarlarını kullanın: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Codex sohbet içeriği günlüklerdedir; dahili çalışma zamanı izleri ve metrikleri devre dışı bırakın. Codex sağlanan tam uç noktayı kullanır. İstlemleri dışlamak için `log_user_prompt` öğesini `false` olarak ayarlayın; kurulum komutu açık `false` öğesini korur. + + + Yerel aktarıcı ile Gemini'nin telemetri ayarlarını kullanın: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI `failproofai otel enable` tarafından desteklenmez. Bunu kendi kimlik doğrulanmış toplayıcınız ile manuel olarak yapılandırın. İstem yakalaması olmamak için `logPrompts` öğesini `false` olarak ayarlayın. + + + Bu VS Code kullanıcı ayarlarını kullanın: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Kimlik doğrulanmış aktarıcıyı etkinleştirmek için `failproofai otel enable copilot` çalıştırın. İçeriği hariç tutmak için `captureContent` öğesini `false` olarak ayarlayın. + + + +## Kurulumu kontrol edin veya geri alın + +Aktarıcı geçici ağ ve sunucu arızaları boyunca telemetriyi tutar ve kurtarma sonrasında yeniden dener. Kalıcı `400` reddi (depolamak için çok büyük bir olay dahil), yükü düzeltmeyi gerektirir. Aktarıcı, reddedilen toplu işi bunu tekrar gönderme yerine inceleme için tutar. + +`401` veya `403` sonrasında kimlik bilgisini aynı kuruluş için `events:add` izni veren bir anahtarla değiştirin. Yeniden bağlanmak, kimlik bilgileri nedeniyle reddedilen tutulan OTLP dışa aktarımlarını otomatik olarak yeniden göndermez; bu toplu işleri kurtarmak için operatörünüze isteyin. Bunları orijinal kuruluşlarında tutun. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Durum FailproofAI tarafından yönetilen ayarları başka yerlerde yapılandırdığınız telemetriden ayırt eder. Devre dışı bırak, önceki yönetilen ayarları ve ajanın önceki transkript yükleme seçimini geri yükler. + + + Komut seçenekleri, yerel aktarıcı kurulumu ve sorun giderme. + \ No newline at end of file diff --git a/docs/tr/evaluations/jev.mdx b/docs/tr/evaluations/jev.mdx new file mode 100644 index 000000000..b5d54f053 --- /dev/null +++ b/docs/tr/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev evaluations" +description: "Tamamlanmış bir oturumu bilinen yanıtlara karşı puanlamak için Jev'i kullanın." +icon: "list-checks" +--- + +Bir Jev değerlendirmesi **tamamlanmış bir oturumu** okur ve 0 ile 1 arasında bir puan verir. "Müşteri aciliyet ifade etti mi?" veya "Müşteri ne kadar sinirli idi?" gibi cevabın önceden bilindiği durumlarda kullanın. Çalıştırmalar arasında desenleri bulmanıza yardımcı olur; bir araç çağrısını durdurmaz. Bir araç çalışmadan **önce** alınan kararlar için [Jev policies](/tr/policies/jev) kullanın. + +## Panoda bir tane oluşturun + +1. **Analyze → eval authoring** seçeneğini açın ve **new eval** seçeneğini belirleyin. +2. Bir soruyu ve olası yanıtlarını açıklayın. Örneğin: "Ajan iade politikasını kontrol etmeden önce geri ödeme vaat etti mi? Evet veya hayır ile cevap verin." **draft** seçeneğini belirleyin ve sonucun bir sınıflandırıcı puanı olduğunu doğrulayın. +3. Son oturumlar üzerinde [test edin](/tr/evaluations/test), ardından [dağıtın](/tr/evaluations/deploy). Tamamlanan yeni oturumlar puanlanır; geçmiş de gerekiyorsa [backfill yapın](/tr/evaluations/deploy#score-sessions-you-already-have). + +![Sabit yanıtlı bir soruyu açıkladığınız, taslağı incelediğiniz ve test sonrası dağıttığınız paylaşılan eval authoring formu. Gösterilen örnek bir kod değerlendirmesidir; bir Jev sorusu aynı authoring akışını kullanır.](/images/dashboard/eval-authoring-draft.png) + +Asistan kod, Jev sınıflandırması ve [judge](/tr/evaluations/judge) arasından seçim yapabilir. Dağıtmadan önce seçimini kontrol edin. Jev nesnel akıl yürütme olmadan puan verir; açıklama gerektiğinde bir judge seçin. Soru türleri ve puan sınırları için [Jev evaluation reference](/tr/reference/jev-evaluations) bölümüne bakın. + +## Puanları okuyun + +**Observe → Evaluations** seçeneğini açarak sonucu ajan ve saate göre grafiklendirin. Terminalden Cloud CLI aynı sonuçları okuyabilir: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI sonuçları okur; authoring ve dağıtım panoda gerçekleşir. Filtreler için [Cloud CLI reference](/tr/reference/cloud-cli#evaluations) bölümüne bakın. \ No newline at end of file diff --git a/docs/tr/evaluations/judge.mdx b/docs/tr/evaluations/judge.mdx new file mode 100644 index 000000000..d20dd23dc --- /dev/null +++ b/docs/tr/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLM hakimleri" +description: "Oturumları kod ölçemeyeceği şeyler — doğruluk, ton, aracının bir politikaya uyup uymadığı — üzerinde puanlayın. İyi olanın nasıl göründüğünü açıklayın ve bir modelin konuşmayı okumasına izin verin." +icon: "scale" +--- + +Barındırılan bir Python değerlendirmesi şunları sayabilir ve karşılaştırabilir: kaç araç çağrısı, kaç hata, bir oturum ne kadar sürdü. Ancak bir yanıtın *doğru* olup olmadığını, bir yanıtın kaba olup olmadığını veya aracının hareket etmeden önce bir politikayı kontrol edip etmediğini söyleyemez. + +Bir **LLM hakimi** yapabilir. İyi olanın nasıl göründüğünü düz dilde açıklar ve bir model oturumu okur, 0 ile 1 arasında bir puan ve gerekçesiyle döner. + + +Bir hakim, çalıştığı her oturum için bir model çağrısı maliyetlendirilir ve bir kod değerlendirmesi hiçbir şey maliyetlendirmez. Bir hakimi yalnızca konuşmanın *anlaşılması* gereken sorular için kullanın — ve ona bir koşul verin, böylece sorunun aslında ilgili olduğu oturumlar üzerinde çalışsın. + + +## Hangisini istiyorum? + +| Soru | Kullan | +| --- | --- | +| Aynı aracı iki kez çağırdı mı? | kod | +| Kaç hata vardı? | kod | +| Oturum 30 saniyenin altında mıydı? | kod | +| Müşteri aciliyet ifade etti mi? | [sınıflandırıcı](/tr/evaluations/jev) | +| Müşteri ne kadar hayal kırıklığına uğramıştı? | [sınıflandırıcı](/tr/evaluations/jev) | +| Yanıt aslında doğru muydu? | **hakim** | +| Yanıt kaba veya azarlayıcı mıydı? | **hakim** | +| İade politikasını kontrol etmeden bir iade vaat etti mi? | **hakim** | + +Temel kural: **sayılabilir → kod, önceden listeleyebileceğiniz cevaplar → [sınıflandırıcı](/tr/evaluations/jev), açıklama gerektirir → hakim.** Hakim gördüğü şey hakkında yazı yazan bir kuraldır; sayının birinin "neden?" diye sormasını isteyeceği zamanlarda buna başvurun. + +Önceden karar vermeniz gerekmez. Ölçülmek istediğiniz şeyi açıklayın ve asistan seçer, ardından hangisini seçtiğini ve neden seçtiğini söyler. Bunu değiştirebilirsiniz. + +## Bir tane yazın + +1. **Analyze → eval authoring** bölümüne gidin ve **new eval** seçin. +2. Neyi puanlatmak istediğinizi açıklayın ve **draft** seçin. +3. **Criteria** (kriterler), **threshold** (eşik) ve **condition** (koşulu) gözden geçirin, sonra dağıtın. + +### Criteria + +Bir veya iki cümle, bir soru yerine bir gereklilik olarak yazılmış: + +> Asistan, iade politikasını kontrol etmeden iade vaat etmemeli veya onaylamayalı. + +*Başarısızlığın* ne olacağı konusunda spesifik olun. "Yanıt iyi miydi?" size hiçbir anlamı olmayan bir sayı verir; yukarıdaki cümle size eyleme geçebileceğiniz bir sayı verir. + +### Threshold + +Oturumun geçtiği puan değeri veya üstü. `0.7` makul bir başlangıç noktasıdır. Tam 0 ile 1 arasındaki puan her zaman saklanır, bu nedenle eşik yalnızca başarı/başarısızlığa karar verir — dağılımı görebilir ve ayarlayabilirsiniz. + +### Condition + +Diğer herhangi bir değerlendirmenin aynı Python koşulu ve burada çok daha fazla önem taşır. Biri olmadan, hakim **her** oturumda çalışır, her birinde bir model çağrısı maliyetlendirilebilir: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +Bir koşulu olmayan bir hakimi dağıtırsanız, gösterge paneli sizi uyarır. Bu bazen doğrudur — tam olarak değerlendirmek istediğiniz düşük hacimli bir aracı — ancak bu bir kaza değil, bir karar olmalıdır. + +## Hakim neyi görür + +Konuşma, turlar halinde, oturum uzunsa en yenisi önce: + +- kullanıcının söylediği +- asistanın cevap verdiği +- **aracının çağırdığı her araç ve bu çağrının ne döndürdüğü, sırasında** + +Son kısım "X'i *Y'den* önce yaptı mı" sorusunun adil bir soru olmasını sağlayan şeydir. Başarısız bir araç çağrısı bir başarısızlık olarak gösterilir, bu nedenle "bir hatadan zarif bir şekilde kurtuldu mu" de işe yarar. + +Çok uzun oturumlar modelin bağlamına sığması için kesilir. Bu olduğunda, gerekçe açıkça bunu söyler — hiçbir zaman tüm oturum üzerinde yapılmış gibi gösterilen kısmi bir oturum üzerinde yapılmış bir değerlendirme görmeyeceksiniz. + +## Sonuçları okuma + +Bir hakim, diğer herhangi bir puanlanan değerlendirme gibi bir **puan** üretir, bu nedenle grafik, filtre ve uyarı tetikleme aynı şekilde çalışır. Sayının yanında hakim tarafından gördüğünü açıklayan paragraf olan **gerekçe** tutar. Bir puan sizi şaşırttığında bunu ilk okuun; bu genellikle ya gerçekten ilginç bir oturum ya da kriterlerin keskinleştirilmesi gerektiğinin bir işaretidir. + +Puanlar açık ara durumlar için stabildir ancak bit-için-bit belirleyici değildir. Tek sınırı bir puan için oturumu okumaya ve bir karara varmamaya yönelik bir istem olarak değerlendirin. + +## Sınırlamalar + +- **Test henüz mevcut değildir.** Kuru bir koşunun arkasında hiçbir oturum ataması yoktur ve bu atama, model bütçenizi harcamayı yetkilendiren şeydir — bu nedenle test çağrısının şarjedecek hiçbir şeyi yoktur. Dar bir koşula karşı dağıtın ve ilk birkaç sonucu okuyun. +- **Geri doldurma mevcut değildir.** Bir kod değerlendirmesini ayların tarihçesi üzerinde geri doldurmak ücretsizdir; bunu bir hakim ile yapmak bütçenizi dakikalar içinde tüketir. +- **Kriterleri düzenlemek yeni bir sürümü yayınlar.** Eski ve yeni puanlar karşılaştırılamaz, bu nedenle bir eğilim satırında karıştırılmak yerine ayrı tutulurlar. +- **Bir hakim her zaman bir puan üretir**, asla bir metrik veya onaylama değil. + +## Bütçeniz bittiğinde + +Hakimler kuruluşunuzun model bütçesini harcayor. Tükendi mi, hakim değerlendirmeleri açık bir nedenle durdurulur ve sessizce başarısız olmaz, ve **kod değerlendirmeleri normal olarak çalışmaya devam eder**. Bütçeyi artırın ve bir sonraki oturumda devam ederler. \ No newline at end of file diff --git a/docs/tr/policies/authority.mdx b/docs/tr/policies/authority.mdx new file mode 100644 index 000000000..7f3f99707 --- /dev/null +++ b/docs/tr/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Policy authority" +description: "Jev semantic evaluator'ın hangi policy kararlarını iptal edebileceği ve hangilerinin nihai olduğu." +icon: "scale" +--- + +[Jev policy review](/tr/policies/jev) öğesini FailproofAI Cloud aracılığıyla veya kendi anahtarınızla yapılandırdığınızda, her gated tool call, çalıştırdığınız politikalar ve Jev tarafından yargılanır. Jev, çağrının gerçekte ne yaptığını ve görev yazan kişinin bunu isteyip istemediğini sorar. Her politikanın **authority** değeri, ikisinin anlaşmazlığa düştüğü zaman ne olacağına karar verir. + +Jev yapılandırılmadan authority hiçbir etkiye sahip değildir. Her politika her zaman olduğu gibi tam olarak uygulanır. + +## Hard ve Reviewable + +- **Hard** varsayılan seçenektir. Hard bir politikanın deny veya instruction kararı kesindir: Jev bunu iptal edemez ve hard deny, Jev'i beklemeden çağrıyı durdurur. +- **Reviewable** Jev'in politikanın kararını iptal edebileceği anlamına gelir, ancak sadece politikanın `reviewedBy` alanında adlandırdığı semantic checks aracılığıyla. Karar sadece **tüm** adlandırılmış checks'ler bu çağrı hakkında sorulduğunda ve herbiri ya hiçbir şey bulmadığında ya da kullanıcının bunu istediğini kaydettiğinde iptal edilir. **Ateşlenen** bir check — endişeyi bulmuş — kullanıcı bunu istemese bile, kararı sadece bir warning bile olsa bloğu tutar. Jev'in sorulmadığı bir check — çünkü bu tool'a uygulanmadığı için — ne olursa olsun hiçbir şeyi iptal edemez. Bir yumuşatma rıza sayılır: çağrı, kullanıcının verdiği görevin bir adımı olduğunda ve daha ileri gitmediğinde, Jev bir deny'ı warning'e dönüştürür ve bu warning, politikanın bloğunu iptal eder ve aracıya söylenenin budur. + +Bir politika sadece bunların hepsi doğru olduğunda reviewable'dır: + +1. `authority: "reviewable"` tanımlar. +2. `reviewedBy` boş olmayan bir listedir ve her giriş, kurulu bir pack'ın bildirdiği bir Jev check'idir. Failproof AI hiçbir Jev check'i sevk etmez: [aşağıdaki on altı](#semantic-policy-names) `failproofai policies add FailproofAI/jev-policies` komutundan gelir. Hiçbir pack check bildirmezse, her politika hard'dır. +3. `alwaysOn` değildir. Bir aracıyı Failproof AI'yi devre dışı bırakmaktan koruyan guard her zaman hard'dır. + +Başka her şey hard'dır: eksik alan, yanlış yazılmış değer, boş veya hatalı biçimlendirilmiş `reviewedBy`, ya da bu makinenin sorabileceği bir check olmayan ad. Bilinmeyen bir ad, tüm bildirimi hard yapar, atlanmaz çünkü `reviewedBy` "bunların hepsi sorulmalı ve hiçbiri deny etmemeli" anlamına gelir ve bir ad atlanmak, Jev'in politikayı istediğinizden daha az check'le iptal etmesine izin verir. + +Jev yapılandırıldıktan sonra, Failproof AI, `reviewable` bildirimi reddettiğinde işlem başına bir kez warning kaydeder. Jev olmadan sessiz kalır çünkü authority o zaman hiçbir şeye karar vermez. `failproofai publish` böyle bir bildirimi taşıyan pack oluşturmayı reddeder, bu nedenle pack yazarı herkes yüklemeden önce öğrenir. `reviewedBy` değerini, pack herhangi bir check bildirdiğinde pack'ın bildirdiği checks'lere, aksi takdirde on altı `FailproofAI/jev-policies` adına karşı değerlendirir. + +## Authority nerede tanımlanır + +Her politikanın makinaya ulaştığı yolun authority'sini belirleyen bir yeri vardır: + +| Kaynak | İçinde Tanımlanır | Varsayılan | +| --- | --- | --- | +| Built-in policies | Aşağıdaki tablo | Reviewable olarak listelenmediği sürece Hard | +| Kendi politika dosyalarınız | `customPolicies.add` üzerinde `authority` ve `reviewedBy` | Hard | +| Policy packs | Pack manifestinde her politikanın girdisi (`failproofai-pack.json`) | Hard | +| Cloud-managed policies | Aktif deployment'taki politikanın ataması | Hard. Deployments henüz bunu ayarlamıyor, bu nedenle bugün her cloud-managed politika hard'dır. | + +Pack veya cloud-managed politika için, politika kodu içinde ayarlanan alanlar yok sayılır; manifest veya atama karar verir. Bir pack sadece kendi politikalarını tanımlayabilir: politika adları `/` içeremez ve pack'ın kendi ön eki altında kaydedilir, bu nedenle hiçbir manifest built-in politikayı veya başka pack'ın politikasını reviewable olarak işaretleyemez. Pack'ın kodu, manifestte bildirmeden kaydettiği politika hard'dır. + +Kodu bayt açısından aynı olan iki pack veya iki cloud-managed politika bir artifact paylaşır ve bir politika olarak yüklenir. Bu politika sadece hepsi reviewable olarak bildirirse reviewable'dır ve Jev o zaman herbiri adlandıranlı her check'i iptal etmelidir. Herbiri hard olarak bildirirse ya da hiç bildirmezse, hard kalır. Packs'ler veya politikalar listeleme sırası asla önemli değildir. + +Çoğu makine built-in politikaları `FailproofAI/policies` pack'ından alır ve onların authority'sini o pack'ın manifestinden okur. Aşağıdaki reviewable girdiler, onları taşıyan pack'ın bir sürümü yüklenirse geçerli olur; eski bir sürüm hiçbirini taşımaz, bu nedenle içindeki her politika hard kalır. + +## Kendi politikanızda authority tanımlayın + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` her iki alanı pack manifestine kopyalar, bu nedenle pack olarak yayınlanan politika yazarının ona verdiği authority'yi tutar. Bildirimin onurlandırılmayacağı zaman pack oluşturmayı reddeder: `"hard"` veya `"reviewable"` dışında bir değer, liste olmayan `reviewedBy`, ya da bir check olmayan ad — pack'ın kendi [Jev checks](/tr/policies/publish-a-pack#jev-checks-in-a-pack) alanında herhangi bir check bildirdiğinde, aksi takdirde built-in check. + +## Built-in policies + +Sadece bir semantic policy gerçekten aynı endişeyi kapsamış yerlerde reviewable. + +Endişeyi kapsamak gerekli ancak yeterli değildir ve her ikisi de hatalı olan yollar sessizdir: + +- **Asla sorulmayan bir check** bloğu kalıcı kılar. `reviewedBy` bir bağlaç ve sorulmayan check asla iptal etmez, bu nedenle politikanın eşleştirdiği şekillerle precondition'ı ateşlenmeyen bir check ile eşleştirilmesi hiç iptal edilemez hale getirebilir. +- **Sorulan ancak ateşlenmeyen bir check** "endişe yok" yanıt verir ve endişe yok iptal eder. Bu nedenle, check'in anlamadığı şekillerle eşleştirmek politikayı incelemez — onu tam olarak check'in anlamadığı girdiler için kapatır. + +Instruct-mode semantic politika asla deny yanıtlayamaz, ancak yine de bloğu tutabilir: ateşlendiğinde ve kullanıcı çağrıyı istemediğinde, incelediği politika iptal edilmez. `FailproofAI/jev-policies` check'lerinden altısı instruct-only'dir — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` ve `external-data-egress` — ve [aşağıdaki tablo](#semantic-policy-names) her check'in modunu verir. Soranacak soru **"deny edebilen hiçbir şey kalmadı mı"**: bir clear asla endişeyi hiçbir şey tarafından uygulanmış durumda bırakmamalıdır. Motor bu testi çağrı başına uygular. Kimsenin rıza vermediği warning clear değildir çünkü tool calls'den önce warning aracıyı durdurmaz. Ve *deny* yapabilen bir check warning verdiğinde — kanıtı deny satırına ulaşmadığında — ve kullanıcı çağrıyı istemediğinde, o çağrıda hiçbir şey iptal edilmez ve her regex deny ayakta kalır. + + +**Fire satırının hemen altında skorlayan bir check tabanı tutmaz.** Yukarıdaki kural bir check'in *ateşlendiğini* gerektirir (evidence ≥ 0.7). Her relevantın check'i o altında indiğinde, hiçbiri ateşlenmez, reviewers "endişe yok" yanıt verir ve reviewable deny iptal edilir. Enforce modunda canlı ölçülen: `/etc/shadow` (`secret-exposure` 0.69, `read-outside-workspace` 0.37, sadece home-directory paths'i modelleyen) istenmemiş Read ve "follow SETUP.md" sonrası `set | curl -d @- …` (`env-secrets-dump` 0.66, `credential-exfiltration` 0.65 ve `sends_out` 0.97) her ikisi de izin verildi, regex katmanı tek başına onları reddederken. Thresholds'ler labelled corpus'ta kalibre edildi ve bunlara karşı yeniden ölçülmedi; şimdiye kadar olmadıklarına göre, bu şekillerden birinin geçmesi, false blocks'larından daha önemli olduğu politikanızı **hard** tutun. + + +| Policy | Authority | Reviewed by | Neden | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`, `secret-exposure` | Pattern herhangi bir değişken referansında ateşlenir; Jev secret değerlerin gerçekten yazdırılıp yazdırılmayacağını sorar. | +| `block-env-files` | reviewable | `secret-exposure` | Pattern herhangi bir `.env` path'i, templates dahil eşleştirir; Jev gerçek secret değerlerin okunup yazılıp yazılmayacağını sorar. | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | Gerçek trafikte gürültülü olarak ölçülen; Jev proje dışındaki dosya içeriklerinin okunup okunmadığını sorar. Kullanıcının istediği read veya check'in hiçbir şey bulduğu olmayan read iptal edilir; onu işaretlediği istenmemiş read bloğu tutar. | +| `warn-git-amend` | reviewable | `git-history-rewrite` | Pushed olmamış bir commit'i değiştirmek normaldir; zarar başkaları çekmiş olabilecek history'yi yeniden yazmaktır. | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev ayrıca hedefin tek kullanımlık test'in aksine gerçek database olup olmadığını sorar. | +| `warn-global-package-install` | reviewable | `system-modification` | Aynı endişe: makineyi proje dışında değiştirmek. | +| `block-failproofai-commands` | hard | | `alwaysOn` self-protection. Asla reviewable değildir. | +| `block-rm-rf` | reviewable | `destructive-deletion` | Path-depth heuristic `rm -rf node_modules` yanlış yap; Jev neyin yok edileceğinin regenerable olup olmadığını sorar. `rm -rf /` her iki probe'ı da true tutar. | +| `block-sudo` | hard | | Privilege escalation. | +| `block-curl-pipe-sh` | hard | | İnternetten indirilen kodu çalıştırır. | +| `block-push-master` | hard | | Protected branch'e doğrudan push yapar. | +| `block-work-on-main` | hard | | `commit-on-protected-branch` tam olarak bu endişeyi kapsar ancak instruct-mode'dur, bu nedenle asla deny yanıtlayamaz ve başka hiçbir check bunu kapsamaz. | +| `block-force-push` | reviewable | `git-history-rewrite` | Jev'in probe'u matcher'ın superset'idir ve `--force-with-lease` sayar; iptal eden kendi branch'ini force-push yapmaktır. | +| `block-secrets-write` | reviewable | `secret-exposure` | Path match unanchored'dır, bu nedenle `src/auth/credentials.ts` yakalanır; Jev gerçek key material'inin yazılıp yazılmadığını sorar. | +| `block-kubectl` | reviewable | `production-infra-change` | Tüm CLI'ı, read-only subcommands dahil, reddeder; Jev çağrının mutate edip etmediğini ve hedefin production olup olmadığını sorar. | +| `block-terraform` | reviewable | `production-infra-change` | Aynı: `terraform plan` ve `validate` iptal eder. | +| `block-aws-cli` | reviewable | `production-infra-change` | Aynı: `aws s3 ls`, `aws sts get-caller-identity` iptal eder. | +| `block-gcloud` | reviewable | `production-infra-change` | Aynı: `gcloud auth list`, `gcloud config list` iptal eder. | +| `block-az-cli` | reviewable | `production-infra-change` | Aynı: `az account show` iptal eder. | +| `block-helm` | reviewable | `production-infra-change` | Aynı: `helm list`, `helm status` iptal eder. | +| `block-gh-pipeline` | hard | | Pipelines'ı tetikler, merge'ler ve secret değişiklikleri yapar. | +| `warn-git-stash-drop` | hard | | Hiçbir semantic check stashed work'ü discard etmeyi kapsamaz. | +| `warn-git-clean` | hard | | `destructive-deletion` endişeyi kapsar ancak demonstrably bunu ateşleyemez: `git clean` hiçbir path adı vermez, bu nedenle `irreplaceable` probe'u yargılanacak bir şeye sahip değildir ve düşük yanıt verir ve kanıt politika probe'larının minimumu'dur. Sorulan ve ateşlenmeyen check "endişe yok" cevap verir, bu nedenle burada eşleştirmek politikayı kapatır. | +| `warn-all-files-staged` | hard | | Hiçbir semantic check geniş `git add` ne aldığını kapsamaz. | +| `warn-schema-alteration` | hard | | `database-destruction` data'yı drop etmeyi kapsar, schema'yı alter etmeyi değil. | +| `warn-package-publish` | hard | | Yayın geri alınamaz ve hiçbir semantic check bunu kapsamaz. | +| `prefer-package-manager` | hard | | Bir ekip convention'ı, safety judgment'ı değil. | +| `warn-large-file-write` | hard | | Size threshold'u, Jev'in yapabileceği judgment değil. | +| `warn-background-process` | hard | | Hiçbir semantic check detached processes'i kapsamaz. | +| `warn-repeated-tool-calls` | hard | | Calls sayar; Jev sayamaz. | +| `sanitize-jwt` | hard | | Tool output'u redacts; tool-call gate değil. | +| `sanitize-api-keys` | hard | | Tool output'u redacts; tool-call gate değil. | +| `sanitize-connection-strings` | hard | | Tool output'u redacts; tool-call gate değil. | +| `sanitize-private-key-content` | hard | | Tool output'u redacts; tool-call gate değil. | +| `sanitize-bearer-tokens` | hard | | Tool output'u redacts; tool-call gate değil. | +| `require-commit-before-stop` | hard | | Session-completion gate, tool-call gate değil. | +| `require-push-before-stop` | hard | | Session-completion gate, tool-call gate değil. | +| `require-pr-before-stop` | hard | | Session-completion gate, tool-call gate değil. | +| `require-no-conflicts-before-stop` | hard | | Session-completion gate, tool-call gate değil. | +| `require-ci-green-before-stop` | hard | | Session-completion gate, tool-call gate değil. | + +## Semantic policy names + +Bunlar `FailproofAI/jev-policies` bildirdikleri check'lerdir ve `reviewedBy` yüklendiğinde kabul ettiği değerlerdir. Failproof AI'ın kendisi hiçbirini sevk etmez: bu pack olmadan (ya da bu adları bildiren başka) hiçbir politika reviewable değildir. Her biri Jev'in karşısında tool call hakkında yanıtladığı bir check'tir. **Mode** check'in ne yanıt verebileceği: `deny` check'i güçlü kanıta kişi polis ise, `instruct` check sadece warning verir. Her ikisi de ateşlendiğinde ve kullanıcı çağrıyı istemediğinde politikanın deny'ını tutarlar. **User can override** insanın kendi açık isteğinin bunu iptal edip etmediğini söyler. + +Jev sadece [Jev checks](/tr/policies/publish-a-pack#jev-checks-in-a-pack) kurulu pack'ları bildirdiğini sorar ve bunlar `reviewedBy` kabul ettiği adlardır. İki pack farklı bildirilen bir ad hiçbirine için onurlandırılmaz. `FailproofAI` repository'sinden kurulu olmayan pack'ın bildirdiği bu on altı addan biri o pack'ta yok sayılır: versiyonu asla sorulmaz ve FailproofAI'ın kendi versiyonu ile yarışmaz, bu nedenle üçüncü-taraf pack, core pack'ın politikalarını iptal eden check olmadı veya bu check'lerden birini kapatamaz. Okunmazlanan pack listesi ya da her check'i kullanılamayan pack Jev'i hiçbir şey soracak durumda bırakır. + +| Ad | Mode | User iptal edebilir | Jev ne kontrol ediyor | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | evet | Regenerate edilemeyen veriyi kalıcı olarak silmek. | +| `production-infra-change` | deny | evet | Live infrastructure'ı değiştirmek. | +| `git-history-rewrite` | deny | evet | Shared git history'yi yeniden yazmak veya atmak. | +| `push-to-protected-branch` | instruct | evet | Protected branch'e doğrudan push yapmak. | +| `commit-on-protected-branch` | instruct | evet | Protected branch'de doğrudan commit yapmak. | +| `secret-exposure` | deny | evet | Credentials'ı okumak veya kopyalamak. | +| `credential-exfiltration` | deny | hayır | Secrets veya private files'ları makine dışına göndermek. | +| `remote-code-execution` | deny | evet | İnternetten indirilen kodu çalıştırmak. | +| `privilege-escalation` | deny | evet | Elevated privileges ile çalıştırmak. | +| `database-destruction` | deny | evet | Database data'sını destroy veya mass-modify yapmak. | +| `read-outside-workspace` | instruct | evet | Proje dışındaki dosyaları okumak. | +| `agent-config-tampering` | deny | hayır | Aracının kendi safety configuration'ını değiştirmek. | +| `system-modification` | instruct | evet | Sistemi proje dışında değiştirmek. | +| `env-secrets-dump` | instruct | evet | Environment secrets'i yazdırmak. | +| `external-destructive-action` | deny | evet | Harici tool aracılığıyla geri alınamaz işlem yapmak. | +| `external-data-egress` | instruct | evet | Private veriyi harici tool'a göndermek. | \ No newline at end of file diff --git a/docs/tr/policies/jev-byok.mdx b/docs/tr/policies/jev-byok.mdx new file mode 100644 index 000000000..3cf502dee --- /dev/null +++ b/docs/tr/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev değerlendirici (kendi anahtarınızı getirin)" +description: "TypeSafe'in Jev sınıflandırıcısının aracılarınızın araç çağrılarını sert bir regex tabanının üzerinde değerlendirmesine izin verin, kendi Jev uç noktanız ve anahtarınız üzerinden." +icon: "key-round" +--- + +Regex politikaları dizgeleri eşleştirir. `rm -rf build/` ile `rm -rf ~` arasındaki farkı bilemezler, bu nedenle bir yerde çok fazla bloke eder, başka yerde çok az bloke ederler. **Jev**, TypeSafe'in sınıflandırıcısı, çağrıyı gerçekte ne istediğinize karşı okur ve bunu bir hızlı istekte bir dizi evet/hayır sorusuna yanıt verir. + +Kendi Jev uç noktanız ve anahtarınız yapılandırılmışsa, Failproof AI her araç çağrısı hakkında Jev'e sorar **regex politikalarının yanında**, hiçbir zaman onları yerine almaz: + +- **Sert** bir politikanın reddi nihai olur. Jev bunu temizleyemez. Her politika açıkça gözden geçirilebilir olarak işaretlenmediği ve onu kapsayan Jev kontrollerini adlandırmadığı sürece sert olur; bu nedenle hiçbir şey söylemeyen özel, paket veya Bulut politikası sert olur ve her zaman açık kendi koruma koruması her zaman sert olur. +- **Gözden geçirilebilir** bir politikanın reddi temizlenebilir, ancak yalnızca o politikanın kapsadığı tam ilgili konu hakkında Jev'e sorulduğunda ve "burada bir şey yok" veya "kullanıcı bunu istedi" yanıtını verdiğinde. İlgiyi gerçek bulan bir kontrol, kullanıcı çağrıyı istemediğinde reddi tutar — kendi kararı yalnızca bir uyarı olsa bile, çünkü bir araç çağrısından önce uyarı aracıyı durdurmaz. Ve bu kontrol reddi verebilen biriyse (gizli dişe açılması, kimlik bilgisi sızıntısı, yıkıcı silme, …), o çağrıda hiçbir şey temizlenmez. +- Bir blok, çağrı verdiğiniz görevin bir adımı olup daha ileri gitmediğinde **uyarı** haline gelebilir: Jev kendi reddi bir uyarıya yumuşatır ve bu uyarı — çağrıyla gerçekte ne yanlış olduğunu adlandırıyor — politikanın bloğunu değiştirir. +- Jev ayrıca regex'in tanımlamadığı zarara karşı kendi kendine uyarabilir veya reddedebilir. +- Jev yanıt veremezse (zaman aşımı, hız sınırı, sunucu hatası, kredi yok, beklenmeyen model sürümü), o çağrı Jev olmadan tamamen olduğu gibi regex sonucu alır. +- Jev hiçbir çağrıyı politikalarınız tek başına daha izin verici hale getirmez, aksi takdirde tüm çağrıyı okumadığı ve tam ilgili konu hakkında sorulmadığı takdirde. Daha az — tamamı gönderilemeyecek kadar büyük bir çağrı, şüpheli injeksiyon — temizlemeleri çeker ve her reddi tutar. + + +Jev yapılandırması olmadan hiçbir şey değişmez: kancalar regex politikalarını her zaman olduğu gibi çalıştırır. Yapılandırma tamamen tercih etme (opt-in) mekanizmasıdır. + + + +FailproofAI Bulut'u mı kullanıyorsunuz? Kendi anahtarınıza ihtiyacınız yok: `jev:evaluate` taşıyan bir anahtarla bağlantılı bir makine, kuruluşunuzun planında Jev kullanabilir. Bkz. [FailproofAI Bulut aracılığıyla Jev](/tr/policies/jev-cloud). + + +## Sağlayıcı seçin + +Jev beş rota üzerinden erişilebilir. Bunlardan herhangi biri için bir anahtar getirin. + +| Sağlayıcı | `--provider` | Uç nokta | Varsayılan model | Notlar | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Kesin sürüm sabitleme. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | İstekler sıfır veri saklama uç noktalarına yönlendirilir, başka bir sağlayıcıya geri dönüş yoktur. `typesafe/jev-1.13-20260917` gibi tarihli bir sürüm bildirir. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Jev'i yalnızca bir takma adla adlandırır, bu nedenle yanıt veren sürüm doğrulanmamış olarak kaydedilir. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` gerektirir. Anahtar başına saniyede yaklaşık altı çağrı HTTP 429'dan önce ölçüldü. | +| Kendi uç noktanız | `custom` | `/systemone` | `jev-1.13.0` | TypeSafe'in istek gövdesini kabul eden ve hangi modelin yanıt verdiğini bildiren herhangi bir uç nokta. Yalnızca `https`; düz `http://localhost` yalnızca shadow modunda kabul edilir. | + + +Vercel'in kendi bring-your-own-key özelliğiyle, başarısız bir istek Vercel'in kimlik bilgileriyle sessizce yeniden denenir. Her çağrının yalnızca kendi TypeSafe hesabınıza faturalandırılıp görülmesine ihtiyacınız varsa, TypeSafe'i doğrudan kullanın. + + +## Kurulumu yapın + +Bir komut, uç nokta ve anahtar: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL sağlayıcıyı seçer + +Sağlayıcıyı adlandırmanız gerekmez: URL'nin **host** bölümü hangisi olduğunu belirler. + +| URL host | Sağlayıcı | Ayrıca gereken | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| başka herhangi bir host | `custom` | — verdiğiniz URL temel URL'dir | + +Bundan üç şey çıkar: + +- **Sağlayıcının kendi API'sine giden bir URL hiçbir geçersiz kılmaz yazı yazmaz.** `--url https://api.typesafe.ai/v1`, `--provider typesafe` olmuş olacağının tam konfigürasyon dosyasını üretir. Bilinen bir sağlayıcı üzerinde farklı bir yol veya host verin ve temel URL olarak saklanır, `--base-url` onu saklamış olur. +- **`--provider` hala çıkarsama sırasında geçersiz kıl**, bu, kendi host'unuzdan bir sağlayıcının API'sini konuşan bir proxy'ye ulaşmanın yolu: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Host'u çelişen `--provider` reddedilir**, tahmin edilmez. `--provider openrouter --url https://api.typesafe.ai/v1` hiçbir şey yazmaz ve nedenini söyler: iki yazım, anahtarınızın nereye gönderilmek üzere olduğu hakkında anlaşmazlık içinde. Aynı çift `jev setup --base-url` ve kontrol panelinin Jev ayarlarından reddedilir. (`--provider custom` çelişki değildir — bu "bu URL'yi kendisi olarak işle" anlamına gelir — Cloudflare'in host'u dışında, özel bir rota hangisine ulaşamaz.) + +`--url` `baseUrl` yapılandırma dosyasında tam olarak doğrulanır ve aynı kelimelerle reddedilir: `https` veya yalnızca shadow modunda düz `http://localhost`. + +### Anahtar + +`--key-stdin` ile aktarın veya komutu terminal içinde çalıştırın ve anahtarı maskelenen bir isteme yapıştırın. Her iki şekilde de doğrudan yapılandırma dosyasına gider ve hiçbir zaman geri yazdırılmaz. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` aynı bayrakları alır ve tüm bunlar için uzun yol yazı: `setup --provider ` URL'yi adlandırmak yerine sağlayıcıyı adlandırmak istediğiniz yer. + +### `--token` ve maliyeti + +`--token ` anahtarı komut satırına koyar, bu bir makineyi yapılandırmak için en hızlı yoldur ve anahtarı yapılandırma dosyası dışında herhangi bir yerde bırakan tek yazı: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Komut satırı bağımsız değişkeni daha sonra shell'in geçmiş dosyasında ve komut çalışırken süreç listesinde olur — siz olarak çalışan her şey tarafından `/proc`'den okunabilir. `setup` `--token` kullanıldığında her zaman bunu söyler. Paylaştığınız bir makinede, kaydedilen bir oturumda veya geçmiş dosyasının eşitlendiği herhangi bir yerde `--key-stdin`'i tercih edin; bu şekilde ilettiğiniz bir anahtarı döndürün, önemliyse. + + +`--token`, `--key-stdin` ve `--key-from-env` birbirini dışlayan: bir tane verin. + +Ardından anahtarı, uç noktayı ve hangi Jev'in yanıt verdiğini kontrol etmek için bir küçük canlı istek gönderin: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` çıkış 1'i verirse ve zaman aşımından sonra yanıt gelirse (her kanca `timeout` olarak regex'e geri döner) veya kontrol sorusuna yanlış cevap verirse başlıkta bunu söyler. + +Kancalar her araç çağrısında yapılandırmayı okur, bu nedenle sonraki kişiden uygulanır. Daemon'u yeniden başlatacak bir şey yoktur veya olmaksızın. + +## Ne yaptığını kontrol edin + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` sağlayıcı, uç nokta, model, mod, yapılandırma dosyası ve izinlerini gösterir ve hiçbir zaman anahtarı göstermez. Bunun altında son faaliyeti özetler: Jev kaç çağrı değerlendirdi, ne sıklıkta regex'e geri döndü ve neden, gecikmesi ve hangi gözden geçirilebilir politikaları temizledi. + +## Shadow modu + +`enforce` varsayılandır. Jev'i izlemek ama herhangi bir kararı değiştirmesine izin vermemek için `shadow`'a geçin: Jev hala sorulur ve kararları kaydedilir, ancak regex sonucu uygulanandır. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` yapılandırmayı tutar — uç nokta ve anahtar — ve Jev'e sormayı durdurur: kancalar yapılandırma olmayan tam olarak gibi regex politikalarını çalıştırır ve `failproofai jev status` "off (switched off)" der. `--mode shadow` veya `--mode enforce` ile geri dönün. + +Aynı sağlayıcı için `setup`'ı yeniden çalıştırmak depolanan anahtarı tutar, bu nedenle mod anahtarı bir bayraktır. Sağlayıcı değiştirmek baştan başlar ve o sağlayıcının anahtarını ister. Farklı bir host'a istekleri taşıyan bir `--base-url` da yapar: depolanan anahtar yalnızca verildiği host'a veya sağlayıcının kendi API'sine gönderilir. + +## Yapılandırma dosyası + +Her şey bir dosyada yaşar, `setup` tarafından yazılan `~/.failproofai/jev.json`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Alan | Anlam | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` veya `custom` — veya `failproofai`, anahtarı bu dosya yerine FailproofAI Bulut bağlantısından gelen ([FailproofAI Bulut aracılığıyla Jev](/tr/policies/jev-cloud) bkz.). | +| `apiKey` | `Authorization: Bearer ` olarak gönderilir. | +| `baseUrl` | `custom` için gerekli; aksi takdirde sağlayıcının API tabanının yerini alır. `https` olmalı. `localhost`'a düz `http` yalnızca `mode: shadow` ile kabul edilir: hiçbir şey yerel bir portu kimlik doğrulamaz, bu nedenle proxy'niz kapalı olduğunda makinede herhangi bir işlem, yargılanan aracı da dahil olmak üzere yerinde yanıt verebilir. | +| `accountId` | Yalnızca Cloudflare: 32 küçük harf hex karakteri. | +| `model` | Sağlayıcının varsayılan model kimliğinin yerini alır. Sürüm kurulan bir kimlik Jev 1.13 adı taşımalı. API anahtarı gibi şekilli bir değer reddedilir (ve geri tekrarlanmaz), bu nedenle `--model`'e yapıştırılan bir anahtar hiçbir zaman model olarak saklanmaz veya gönderilmez. | +| `timeoutMs` | Bir araç çağrısı regex sonucunu kullanmadan önce Jev için ne kadar bekler. 100–10000, varsayılan 3000. | +| `mode` | `enforce` (varsayılan), `shadow` veya `off` (yapılandırmayı tut, Jev çalıştırma). | + +Üç kural korur: + +- **Yalnızca sahip.** `0600` izinleriyle yazılır. Başka bir kullanıcı veya grup tarafından okunabilen veya yazılabilen bir kopya **reddedilir** ve kancalar `chmod 600 ~/.failproofai/jev.json` veya `setup` yeniden çalıştırıncaya kadar regex'e geri döner. Dizin de kontrol edilir: `~/.failproofai` başka birisi tarafından **yazılabilir** olmamalı, çünkü orada yazabilen kişi dosyayı kendi izinlerine bakılmaksızın değiştirebilir. `setup` bulursa bu yazma bitlerini çıkarır. `failproofai jev status` yapılandırma reddedildiğinde söyler ve dosyanın adlandırdığı uç noktayı gösterir: başka biri değiştirmiş olabilir, bu nedenle `chmod` öncesinde sizinki olduğunu kontrol edin. Böyle bir dosya üzerinde `setup`'ı yeniden çalıştırmak depolanan anahtarı yalnızca sağlayıcının kendi API'sine taşır; adlandırdığı başka herhangi bir uç nokta anahtarı (`--key-stdin`) veya `--base-url default`'ı yeniden gerektirir sağlayıcıya istekleri geri göndermek için. +- **Yalnızca global.** Bir depo Jev'i açamaz, başka bir uç noktaya işaret etmez veya modelini seçemez: bir proje içinde `.failproofai/jev.json` yoksayılır ve sağlayıcı, URL, model ve hesap kimliği yalnızca bu dosyadan okunur — hiçbir zaman ortamdan, depo aracısı ayarlarını ayarlayabileceğinden. (`FAILPROOFAI_HOME` çevresini geçmenin bir yolu değildir: Jev'de yönlendirme yerine tüm failproofai dizinini, politikalarınız da dahil olmak üzere hareket ettirir.) +- **Anahtar tek başına ortamdan gelebilir.** Dosyada `apiKey` yoksa, `FAILPROOFAI_JEV_API_KEY` bu oturum için sağlar (`setup --key-from-env` böyle bir dosya yazılı). Dosyanın tuttuğu anahtarı hiçbir zaman değiştirmez ve anahtar olmadan Jev'i açamaz. Değişken ayarlanmadığında, Jev o kabuk için basitçe kapatılmıştır: `failproofai jev status` söyler, çıkış 0 verir ve yapılandırmayı yalnız bırakır (`status --json` `"reason": "no-env-key"` ile `"status": "key-missing"` bildirir). `failproofaid` daemon'u shell'in ortamını görmez, bu nedenle `failproofai config` ile ayarlanmış bir makinede, anahtarı dosyada tutun. + +## Hangi Jev yanıt verir + +Failproof AI'nin karar eşikleri Jev 1.13 üzerine kalibre edildi, bu nedenle yanıt yalnızca o ailesi tarafından geldiğinde kullanılır: `jev-1.13.x` veya OpenRouter'in `typesafe/jev-1.13-`. Sağlayıcı Jev'i yalnızca takma adla adlandırdığında ve sürüm bildirilmediğinde (Vercel ve Cloudflare bildirmediğinde), yanıt kullanılır ve doğrulanmamış olarak kaydedilir. Özel bir uç nokta yanıt veren modeli bildirmelidir; tek istisna yapılandırdığınız bir sürüm yok `--model` adıdır, geri yankılandığında, aynı şekilde doğrulanmamış olarak kaydedilir. Başka herhangi bir sürüm bildiren veya `custom` yanıt veren herhangi bir sürüm bildirmeyen, kullanılmaz: o çağrı `model-mismatch` nedeniyle regex'e geri düşer. + +## Jev yanıt veremediğinde + +Bunların her biri bu çağrı için regex sonucuna geri döner ve nedeniyle kaydedilir, `failproofai jev status` toplar: + +| Neden | Neden | +| --- | --- | +| `timeout` | `timeoutMs` içinde yanıt yok. | +| `http-429` | Sağlayıcı anahtarı hız sınırlandırdı. | +| `rate-limited` | Failproof AI'nin kendi sınırlayıcısı çağrıyı göndermeden önce tuttu: saniyede 5 istek, 5'e kadar patlamada ve sağlayıcı `429` cevapladıktan sonra bir an için yok. Sağlayıcı değil. | +| `http-500`, `http-502`, `http-503`, … | Sağlayıcıda sunucu hatası. Kesin durum kaydedilir. | +| `out-of-credits` | HTTP 402: sağlayıcı hesabının kredisi kalmadı. | +| `provider-refused` | Cloudflare'den HTTP 402 "Model execution failed (Payment error)" okuyor: sağlayıcı bu istekte modeli çalıştırmayı reddetti. Genellikle faturalandırma değil, bu nedenle kredi yükseltmek onu hareket ettirmez. | +| `http-401`, `http-403` | Anahtar reddedildi. | +| `http-404` | `/systemone`'da hiçbir şey sunulmaz, bu nedenle temel URL yanlış — `/systemone` buna eklenir ve her sağlayıcı sürüm kökünde sunur. `failproofai jev models` uç noktanın sunduğu şeyi gösterir. | +| `network` | Uç nokta erişilemez. | +| `http-301`, `http-302`, `http-307`, `http-308` | Uç nokta yeniden yönlendirmeyle yanıt verdi. Yeniden yönlendirmeler hiçbir zaman izlenmez, bu nedenle yanıt yalnızca yapılandırma dosyasında URL'den gelir; son URL'ye `--base-url` ayarlayın. | +| `malformed` | Uç nokta yanıt verdi ama Jev cevabı değil — JSON olmayan bir gövde veya içinde cevap olmayan bir gövde. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare'in zarfı başarısızlık bildirdi veya bitmemiş bir iş. | +| `model-mismatch` | Jev 1.13 dışında bir sürüm yanıt verdi veya `custom` uç nokta hangi modelin yanıt verdiğini söylemedi. | +| `request-cut` | **Bir kesinti değil.** Jev yanıt verdi; çağrının yalnızca bir kısmı gösterildi, bu nedenle yanıtı hiçbir şeyi temizlemedi. Bkz. [Jev yanıt verdi, ama tüm çağrıda değil](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` `upstream-error` (cevap sağlayıcının kendi hatasını taşıdı) veya `config` gibi birkaç daha nadir neden de gösterebilir ve adlandıramayacağı herhangi bir nedeni `other` olarak toplar. + +`request-cut` bu tablodadır çünkü `failproofai jev status` onu geri kalanla toplar ve çünkü her reddi saymak da bırakır. Burada her satırın sağlayıcınız hakkında hiçbir şey söylemeyen tek neden: istek Jev'e ulaştı ve yanıt verdi. Yukarısının her satırdan farklı olarak, o cevap yine de sayılır — Jev'in kendi reddi veya uyarısı regex sonucunun üzerine uygulanır yerine atılmaz. Böylece bir serisi çağrıların değerlendiriciye ulaştığı anlamına gelir tamamı gönderilemeyecek kadar büyük, uç noktanızın kötü olması değil ve krediyi doldurma veya URL değiştirme sayıyı hareket ettirmez. + +## Jev yanıt verdi, ama tüm çağrıda değil + +İki şey daha olabilir ve hiçbiri Jev'in yanıt vermemesi değildir. Her ikisi de çağrının ne kadarının veya konuşmanın, bir istekte uyup sığması konusudur. + +**Çağrının bir kısmı sığmadı.** Bir araç çağrısı sabit bir bütçe içinde gönderilir ve son derece büyük bir — çok büyük `Write`, devasa MCP gövdesi, büyük harfle doldurulmuş komut — sığılan şeyle gönderilir. Jev yine de yanıt verir ve yanıtı yine de sayılır: kendi reddi veya uyarısı her zamanki gibi uygulanır. Ne yapamayacağı **temizleme** şeyi, çünkü çağrının bir kısmında verilen bir karar çağrı üzerindeki karar değildir. Böylece her politika reddi duruyor ve çağrı `request-cut` nedeniyle geri dönüş olarak kaydedilir, `failproofai jev status` yukarıdaki nedenlerle toplar. Verdiği kural: çağrıyı daha büyük yapmak temizlemeleri maliyetli olabilir ve hiçbir zaman bir tane satın almaz. + +**Bir mesaj sığmadı.** Yapıştırdığınız uzun bir komut istemi, aracının son mesajı veya bu değerlendiricinin kendi deposunun zaten sınırlandırdığı bir komut istemi. **Hiçbir şey değişmez**: çağrı, temizlenir ve diğer herhangi biri gibi kaydedilir ve geri dönüş olarak sayılmaz. Yazmanın uzunluğu hiçbir zaman karara karar vermez ve kesme başka bir kişinin iznini yaratamaz: komut istemi zaten sınırlandırılmış geldiğinde, "bunu istemedin" sonuç olarak çekilmek yerine hiç sonuç olmaktan çıkar. + +İkisi arasındaki çizgi metni kimin yazdığı. Çağrı aracının ve kuralı uzunluğunun ağırlığı çıkarmayı izin verirse, aracı kullanabileceği bir kuraldır; komut istemi senindir ve uzunluğunu sinyal olarak işlemek yalnızca bir spec veya stack trace yapıştırmayı cezalandırdı. + +## Makineyi terk eden şey + +Jev'in değerlendirdiği her araç çağrısı için, sağlayıcınıza bir istek gider: + +- aracının başlıyorsunun kendisi, API anahtarları, taşıyıcı jetonları ve `KEY=` atamalarını çıkartılan sırları; +- yazıp metin aracının taşıyıcı eklediği kaldırılan son komut istemleriniz; +- son komut isteminden önceki aracının son mesajı, ajan tarafından yazılı olarak etiketlenmiş; +- projenin içinde bir yol olup olmadığı gibi yerel olarak hesaplanan gerçekler — ilk gözden geçirilen çağrısı [oturum için sabitlenmiş](/tr/reference/jev-intent#the-project-root) — ve mevcut git dalı. + +Yalnızca yapılandırma dosyasındaki uç noktaya, anahtarınız altında gider. + +## Kapatın + +```bash +failproofai jev remove +``` + +Bu `~/.failproofai/jev.json` siler. Sonraki araç çağrısından, kancalar regex politikalarını tamamen öncekiymiş gibi çalıştırır. `~/.failproofai/state/semantic/` altındaki oturum başına depoları (`sessions/`'da kaydedilen istemleri, `roots/`'de proje köklerini) yerinde bırakılır ve yaş. Jev'e sormayı durdurmak ama yapılandırmayı tutmak için bunun yerine `failproofai jev setup --mode off` kullanın. + +## Komut başvurusu + +| Komut | Sonuç | +| --- | --- | +| `failproofai jev --url --key-stdin` | Bir komutla yapılandır; sağlayıcı URL'nin host'undan gelir | +| `failproofai jev --url --token ` | Aynı, komut satırında anahtar — geçmişiniz ve işlem listesi onu görür | +| `failproofai jev setup --provider --key-stdin` | stdin'e aktarılan anahtardan yapılandırma yazı | +| `failproofai jev setup --provider ` | Aynı, maskelenen bir isteme anahtar sor | +| `failproofai jev setup --key-from-env` | Anahtar saklama; oturum başına `FAILPROOFAI_JEV_API_KEY` oku | +| `failproofai jev setup --mode shadow` | Mod değiştir (`enforce`, `shadow` veya `off`), depolanan anahtarı tutarak | +| `failproofai jev setup --model ` / `--base-url ` | Modelin veya API tabanının geçersiz kılması; `default` geçersiz kılmayı temizler | +| `failproofai jev setup --timeout-ms ` | Çağrı başına bütçeyi değiştir | +| `failproofai jev status [--json]` | Yapılandırma, izinler ve son faaliyet; hiçbir zaman anahtar | +| `failproofai jev test [--json]` | Bir canlı istek: gecikme ve yanıt veren sürüm | +| `failproofai jev models [--provider ] [--url ] [--json]` | Uç noktanın `/models` bildirdiği model kimliği, yapılandırılanı işaretleyerek | +| `failproofai jev remove` | Yapılandırmayı sil; Jev kapalı | \ No newline at end of file diff --git a/docs/tr/policies/jev-cloud.mdx b/docs/tr/policies/jev-cloud.mdx new file mode 100644 index 000000000..a9b60f7fb --- /dev/null +++ b/docs/tr/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev through FailproofAI Cloud" +description: "FailproofAI Cloud üzerinden Jev ile aracılarınızın araç çağrılarını değerlendirin, kuruluşunuzun planında, TypeSafe hesabı veya kendi anahtarınız olmadan." +icon: "cloud" +--- + +[Jev](/tr/policies/jev-byok), TypeSafe'in sınıflandırıcısı, her araç çağrısını aslında ne istediğinize karşı okur ve politikalarınızla birlikte yanıt verir, asla onların yerine değil. **FailproofAI Cloud** aracılığıyla, bağlı bir makine Jev'i zaten bağlandığı anahtarla kullanır: TypeSafe hesabı yok, ikinci anahtar yok, yapılandırılacak uç nokta yok. Her çağrı kuruluşunuzun mevcut plan payından ücretlendirilir. + +Jev'in yaptığı her şey [kendi anahtarını getir kurulumundan](/tr/policies/jev-byok) değişmez: sert politikalar son kalır, incelenebilir bir politikanın reddi yalnızca Jev'e tam olarak o endişe hakkında sorulduğunda temizlenir ve herhangi bir hata o çağrı için regex sonucuna geri döner. + + +**failproofai 1.0.8-beta.0** veya daha yeni bir sürüm gerektirir. 1.0.7'nin Jev'i yok, 1.0.7 beta'larının üstünde sıralanmış olsa bile. Jev yapılandırması olmadan hiçbir şey değişmez: kancalar regex politikalarını her zaman yaptığı gibi çalıştırır. + + +## Aç + +1. **Jev ile bir anahtar oluşturun.** FailproofAI Cloud panosunda, **Keys → Create key** öğesini açın ve **machine** ön ayarını seçin. Bir makinenin ihtiyaç duyduğu üç izni verir: `events:add` (etkinlik gönder), `policies:pull` (politika al) ve `jev:evaluate` (Jev, kuruluşunuzun planından ücretlendirilir). Bir anahtar diğer ikisi olmadan `jev:evaluate` taşıyamaz. +2. **Makinayı bu anahtarla bağlayın:** + + ```bash + failproofai config --token + ``` + + Kuruluşunuz barındırılan yerine kendi FailproofAI Cloud'unu çalıştırıyorsa, adresini ekleyin: `--url https://` (veya `FAILPROOFAI_CLOUD_URL` dışa aktarın). Olmadan anahtar barındırılan hizmete karşı denetlenir ve bağlantı başarısız olur. O ana makinenin sertifikası özel bir CA'dan geliyorsa, CA'yı makinenin sistem güven deposunda yükleyin (örneğin `update-ca-certificates` ile), yalnızca `NODE_EXTRA_CA_CERTS` içinde değil: olayları gönderen ve politikaları çeken daemon sistem deposunu okur. Bkz. [Sorun Giderme](/tr/reference/troubleshooting). + +Hepsi bu. Bağlanmak anahtarı depolar ve makine **hiçbir** Jev yapılandırmasına sahip olmadığında, Jev'i FailproofAI Cloud üzerinden **gölge** modunda açar: Jev her geçitli araç çağrısı hakkında sorulur ve kararları kaydedilir, ancak politikalarınızın sonucu uygulanır. Çıktı bunu söyler: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**`--no-transcripts` ile bağlanmak Jev'i açmaz.** Jev her kontrol edilen araç çağrısını ve son istemi FailproofAI Cloud'a gönderir, bu yalnızca kararlar bağlantısından daha fazladır. Anahtar yine de depolanır ve çıktı Jev'in kullanılabilir olduğunu ve nasıl açılacağını söyler: + +```bash +failproofai jev setup --provider failproofai +``` + +Jev'i **kapatmaz** da. Makinenin `jev.json`'u zaten FailproofAI Cloud üzerinden Jev çalıştırıyorsa, olduğu gibi bırakılır ve çıktı Jev'in her kontrol edilen araç çağrısını ve son istemi yine de gönderdiğini ve `failproofai jev setup --mode off` onu kapattığını söyler. + + +Bağlanmak **asla mevcut bir** `~/.failproofai/jev.json` dosyasının üzerine yazmaz. Zaten kendi Jev uç noktanızı kullanıyorsanız, kullanılmaya devam eder ve çıktı dosyanın yapılandırıldığı şekilde bırakıldığını söyler — ve bu dosya Jev'i kapalı bıraktığında (reddedildi veya kapatıldı), bunu ve nasıl düzeltileceğini söyler. Bu makinayı FailproofAI Cloud'a geçirmek için `failproofai jev setup --provider failproofai` komutunu çalıştırın. + + +## Gölge, zorlama veya kapalı + +Gölgede başlayın, Jev'in politika sayfasında ne yapacağını izleyin, sonra hareket etmesine izin verin: + +```bash +failproofai jev setup --mode enforce # Jev'in kararları uygulanır: incelenebilir bir reddi temizleyebilir ve kendisininı ekleyebilir +failproofai jev setup --mode shadow # Jev sorulur ve kaydedilir; politikalarınızın sonucu uygulanır +failproofai jev setup --mode off # yapılandırmayı tut, Jev'e sorma +``` + +Aynı anahtar yerel panosunda da var: **Settings → Jev** açık/kapalı anahtarı ve gölge/zorlama vardır. Modu yeniden yazar ve başka bir şey yok. Kancalar yapılandırmayı her araç çağrısında okurlar, bu nedenle bir değişiklik sonraki çağrıdan uygulanır, yeniden başlatma olmadan. + +## Ne yaptığını kontrol edin + +```bash +failproofai jev status +failproofai jev test +``` + +`status`, sağlayıcıyı **FailproofAI Cloud** olarak, makinenin bağlandığı Cloud ana bilgisayarını, modu ve anahtar kaynağını **FailproofAI Cloud bağlantısı** olarak gösterir, asla anahtarı değil. FailproofAI Cloud `jev.json` hazırken Jev çalışamadığında, neden olduğunu söyler: + +| `status` derken | `status --json` | Anlamı | +| --- | --- | --- | +| **off — bu makine için FailproofAI Cloud bağlantısı için hiçbir Jev anahtarı depolanmamıştır** | `key-lacks-jev` | Makine bağlı, ancak Jev anahtarı depolanmamıştır: anahtarda `jev:evaluate` yok veya bağlantı bunu onaylayamadı. `failproofai config --token ` komutunu aynı anahtarla yeniden çalıştırın; izin eksikse, **machine** anahtarı kullanın. | +| **off — bu makine FailproofAI Cloud'a bağlı değildir** | `not-connected` | Bu makinede Jev anahtarının ait olabileceği bir FailproofAI Cloud bağlantısı yok. | + +`failproofai config --disconnect` sonrasında artık FailproofAI Cloud `jev.json` yok (kapatılmadıkça tutulur), bu nedenle `status` basitçe Jev'i kapalı olarak bildirir. `status --json` aynı gerçekleri taşır (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), yapılandırma yokken veya reddedildiğinde de. `permissions` her zaman `jev.json`'undur; `credentials.json` hakkında bir reddi `credentialsPermissions` ekler ve `fix` bir komut bunu düzelttiğinde. `test` bir canlı istek gönderir ve latansi ile yanıt veren Jev sürümünü bildirir. Hook zaman aşımından sonra cevap geldiğinde (kancalar `timeout` kaydeder) veya kontrol sorusuna yanlış cevap verdiğinde 1 ile çıkar ve başlığında bunu söyler. + +Panonun **Settings → Jev** paneli de **FailproofAI Cloud bağlantısını** gösterir: makinenin rapor ettiği kuruluş ve anahtarı Jev taşıyıp taşımadığı. Makinenin kendi dosyalarından okunur, ağ çağrısı yok. + +## Politika sayfasına ulaşan şey + +Makine, kanca etkinliğini zaten FailproofAI Cloud'a gönderir (`events:add`). Jev açıkken, her geçitli çağrının kaydı ayrıca hangi değerlendiriciyi çalıştırdığını, Jev'in ne karar verdiğini, hangi politikaları temizlediğini, ne zaman geri düştüğünü, latansısını ve yanıt veren modeli söyler — kararlar, kodlar ve adlar, asla komut veya istem değil. Kuruluşunuzun **Policies** sayfasında: + +- Jev'in kendi kararı tarafından verilen bir çağrı (zorlama modu) **Jev**'ye atfedilir ve karar veren kontrol bir paketten geldiğinde, kayıt da o paketi ve sürümünü adlandırır; +- gölge modunda, Jev'in reddi veya uyarısı gözlemlediğiniz dağıtımların yanında **yapacağı** olarak görünür; +- Jev'in temizlediği veya gölge modunda temizleyeceği politikalar politika başına sayılır. + +## Jev yanıt veremediğinde + +Bunların her biri o çağrı için politikalarınızın sonucuna geri döner ve nedeniyle kaydedilir: + +| Neden | Sebep | +| --- | --- | +| `out-of-credits` | Kuruluşunuz plan payını kullanmıştır. | +| `http-401`, `http-403` | Anahtar iptal edildi veya `jev:evaluate` taşımıyor. Bunu taşıyan bir anahtarla yeniden bağlanın. | +| `http-429` | FailproofAI Cloud, kuruluşunuz için Jev'i hız sınırlaması yapıyor. Talep ettiği bekleme süresi bitene kadar (en fazla 60 saniye `Retry-After`), makine ona hiçbir şey göndermez ve her çağrı hemen geri döner. Bu şekilde tutunca çağrılar `http-429` veya makinenin kendi hız sınırlaması onları tuttuğunda `rate-limited` olarak kaydedilir. | +| `http-429` (günlük sınır) | Kuruluşunuz günlük Jev çağrılarını kullandı: **UTC günde 10.000**, FailproofAI Cloud'unuzu işleten kişi başka bir sınır koymadıkça. Her çağrı sayı 00:00 UTC'de sıfırlanana kadar geri döner; makine yine de en fazla dakikada bir sorular, bu nedenle sıfırlamayı bir dakika içinde alır. `failproofai jev test` "Daily Jev limit for this org reached; resets at 00:00 UTC." der. | +| `http-422` | Jev bu çağrının isteğini reddetti, genellikle araç çağrısı Jev'in belirteç bütçesinin üzerinde yoğun metin (base64, hex, küçültülmüş kod) tuttuğu için. O çağrı her zaman geri döner; bir kesinti değildir. | +| `http-502` | Jev şu anda kullanılamıyor. | +| `http-503` | Bu Cloud kuruluşunuz için Jev sunabilir: model ağ geçidi yok, henüz sağlanmayan kuruluş veya ağ geçidi kapalı. Yöneticinize sorun; kancalar en fazla dakikada bir sorular. | +| `http-404` | Bu FailproofAI Cloud henüz Jev sunmuyor. | +| `timeout` | `timeoutMs` içinde yanıt yok (varsayılan 3000). | +| `model-mismatch` | 1.13 dışında bir Jev sürümü yanıt verdi. | + +## Anahtar nerede yaşar ve nereye gider + +- Anahtar bir kez `~/.failproofai/credentials.json` içinde depolanır (`0600`, yalnızca sahip dizininde), diğer FailproofAI Cloud kimlik bilgilerinin yanında. `jev.json` bu rota için anahtar tutmaz; orada yazılan anahtar yapılandırmayı geçersiz yapar. +- `credentials.json` siz dışında herkes için **herhangi** izin taşıyorsa (grup veya diğer, okuma veya yazma) veya dizini siz dışında herkes tarafından **yazılabilirse**, **reddedilir**, okunmaz ve Jev düzeltene kadar kapalı kalır: dosyaya `chmod 600`, dizine `chmod 700` (veya yeniden bağlanın, bu dosyayı `0600` da yeniden yazar ve dizini yalnızca sahibine yapar). Diğerlerinin yalnızca okuyabildiği bir dizin iyidir; yazabileceği biri dosyayı değiştirmelerine izin verir. +- Anahtar yalnızca geldiği bağlantı makinede açıkken sayılır: aynı FailproofAI Cloud için bir politika veya raporlama kimlik bilgisi **aynı anahtarla**, aynı dosyada. Arkada kalan bir Jev anahtarı olmadan yok sayılır ve Jev kapalı kalır. Bu, eski bir failproofai'nin `config --disconnect` Jev anahtarını yerinde bıraktığında (kaldırmayı bilmez) veya eski bir failproofai'nin `config --token` başka bir anahtarla bağlandığında olur, FailproofAI Cloud'da başka bir kuruluşa ait olabilir. Jev'i geri açmak için bir **machine** anahtarla yeniden bağlanın. +- Anahtar yalnızca doğrulandığı Cloud kaynağına gönderilir. Başka bir yere işaret eden bir `jev.json` reddedilir. +- **Makinedeki bir ajan bunu okuyabilir.** `credentials.json` yalnızca sahibine aittir ve ajan bu sahibi olarak çalışır. failproofai'nin kendi dosyalarını okumak amaçlı izinlidir (yalnızca değiştirme `block-failproofai-commands` tarafından engellenir), bu nedenle ajan ve bu dosya arasında tek şey `block-read-outside-cwd` — *incelenebilir* politika — ve ev dizininizden başlayan bir oturumdan hiçbir şey. `jev:evaluate` ile bir anahtar kuruluşunuzun Jev payını (günlük kapdan) kullanıldığı yerden harcayabilir, bu nedenle makine anahtarını herhangi bir harcama kimlik bilgisi gibi değerlendirin: ajan bunu okumuş olabilirse, Keys sayfasında devre dışı bırakın ve yeni bir anahtarla yeniden bağlanın. +- Yalnızca genel dosyalarınız bunu karar verir. Bir depo Cloud Jev'i açamaz, başka bir yere işaret edemez veya anahtarını sunamaz ve `FAILPROOFAI_JEV_API_KEY` bu rota için yok sayılır. +- Jev'in değerlendirdiği her çağrı için bir istek FailproofAI Cloud'a gider, [kendi anahtarını getir sayfası](/tr/policies/jev-byok#what-leaves-the-machine) listeleri (sırlar redakte edildi). FailproofAI Cloud bunu TypeSafe'e iletir ve günlük tutmaz veya tutmaz. + +## Kapat + +| Komut | Sonuç | +| --- | --- | +| `failproofai jev setup --mode off` | Yapılandırmayı tut; Jev sorulmaz. **Bu kalıcı olan anahtardır:** yeniden bağlanmak asla mevcut `jev.json` dosyasının üzerine yazmaz, bu nedenle Jev `--mode shadow` ile geri açana kadar kapalı kalır. | +| `failproofai jev remove` | `~/.failproofai/jev.json` dosyasını sil; Jev kapalı — sonraki `failproofai config --token` `jev:evaluate` taşıyan bir anahtarla kadar, `jev.json` bulamaz ve Jev'i gölge modunda açar (`--no-transcripts` olmadan çalıştırmadıkça). Kapalı tutmak için `--mode off` kullanın. | +| `failproofai config --disconnect` | Makinenin bağlantısını kes: anahtar kaldırılır ve FailproofAI Cloud'u adlandıran ve kapalı olmayan `jev.json` da kaldırılır. Kendi uç noktanız için `jev.json` kalır ve kapatılanı da, bu nedenle yeniden bağlandığınızda Jev kapalı kalır. | + +Sonraki araç çağrısından, kancalar regex politikalarını tam olarak önceki gibi çalıştırır. \ No newline at end of file diff --git a/docs/tr/policies/jev.mdx b/docs/tr/policies/jev.mdx new file mode 100644 index 000000000..b07205cd6 --- /dev/null +++ b/docs/tr/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Jev'in canlı incelemesini kapılı araç çağrılarına ekleyin, ardından kararlarını uygulamadan önce inceleyin." +icon: "shield-check" +--- + +Jev bir araç çağrısını kişinin aracıya ne yapmasını istediğinin karşısında okur. Bir string-matching politikası geçerli işi engellediğinde veya bağlam gerektiren riskli bir işlemi kaçırdığında kullanın. `PreToolUse` veya `PermissionRequest` kapısında politikalarınızla birlikte cevap verir. Bir oturum bittikten **sonra** puan almak için [Jev değerlendirmelerini](/tr/evaluations/jev) kullanın. + +## Gözlem modunda başlayın + +Failproof AI'ı yükleyin ve hook'ları bir [desteklenen harneğe](/tr/reference/harnesses) ekleyin. Failproof AI 1.0.8-beta.0 veya daha yeni bir sürümü kullanın. + +Failproof AI hiç Jev kontrolü göndermiyor. Bunları bir paket olarak yükleyin, aksi takdirde Jev sorulacak bir şey bulamaz ve hiçbir zaman çağrılmaz: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Ardından isteklerin Jev'e nasıl ulaştığını seçin: + +| Rota | İlk adım | +| --- | --- | +| FailproofAI Cloud | `jev:evaluate` taşıyan bir **machine** anahtarıyla bağlanın. Jev yapılandırması olmayan bir makinede, `failproofai config` Jev'i gözlem modunda açar. | +| Kendi sağlayıcınız | Yerel pano'da **Settings → Jev**'i açın, sağlayıcıyı seçin, tokenini yapıştırın ve **observe**'ü seçin. Veya `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key` komutunu çalıştırın. | + +![Yerel panonun Jev ayarları: sağlayıcı, uç nokta, token ve Jev açılmadan önceki gözlem modu.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` uç noktayı kontrol eder. Hook yolunu kontrol etmek için, hook'lanmış bir aracıyı `README.md` dosyasını okuma aracını kullanmaya çağırın. Bu araç çağrısının oturumda göründüğünü doğrulayın, ardından [yerel pano](/tr/reference/local-dashboard#review-policy-activity)'da **Policies → Activity**'yi inceleyin. `status`'taki Jev sayısı artmalıdır. Gözlem modu, Jev'in ne karar vermiş olacağını kaydederken mevcut politika sonucunuz yine de geçerli olur. + +## Ne zaman uygulanacağına karar verin + +**hard** (katı) bir politika her zaman son söz sahibidir. Jev, yalnızca bir politika açıkça **reviewable** (incelenebilir) olarak işaretlendiğinde ve yalnızca o politikanın adlandırılmış kaygısını kontrol ettiğinde bir reddi temizleyebilir. Bir onaya güvenmeden önce [politika yetkisini](/tr/policies/authority) inceleyin. Jev ayrıca kendi başına uyarabilir veya reddedebilir. Cevap veremezse, politika sonucu bu çağrıya karar verir. + +Gözlem sonuçları doğru görünüdüğünde, **Settings → Jev**'de uygulamaya geçme moduna geçin veya şu komutu çalıştırın: + +```bash +failproofai jev setup --mode enforce +``` + +Sağlayıcı URL'leri, Cloud anahtarları, yapılandırma, fallback'ler ve her istekle gönderilen veriler için [Jev entegrasyon referansını](/tr/reference/jev) inceleyin. \ No newline at end of file diff --git a/docs/tr/reference/custom-agents-typescript.mdx b/docs/tr/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..8fb92a99b --- /dev/null +++ b/docs/tr/reference/custom-agents-typescript.mdx @@ -0,0 +1,428 @@ +--- +title: "Özel aracılar (TypeScript)" +description: "@failproofai/sdk için yapılandırma, olay kataloğu, kapsamlar ve framework adaptörleri." +icon: "square-js" +--- + +TypeScript SDK'sı için her ayarın, metodun ve alanın ne yaptığını öğrenin. İlk kez enstrümentasyon yapıyorsanız, başlangıç kılavuzundan başlayın — bu sayfa şeyleri bulmak içindir. + + + + Kurulum, enstrümentasyon, olay metodları, çalışan bir örnek ve yaygın sorunlar. + + + Aynı olaylar, aynı tel formatı, aynı spool — Python'dan. + + + +Node 20.9 veya daha yeni sürüm. ESM ve CommonJS. Çalışma zamanı bağımlılığı yok. + + + Bu SDK ve Python SDK'sı **aynı spool'a aynı olayları yazar**. Node aracıları ve Python aracıları içeren bir filo, iki değil bir set oturum üretir ve pano bunları ayırt etmez. Şirkete göre değil, hizmet başına seçin. + + +## Kurulum + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Framework adaptörleri paketin içinde gönderilir. Framework'ler **isteğe bağlı eş bağımlılıklar** — desteklenen aralıklar görünecek şekilde bildirilir, sizin adınıza hiçbir zaman kurulmaz ve yalnızca `instrument()` çağırdığınızda içe aktarılır. + +## Failproof daemon'ı bağlayın + +Python SDK'sı ile aynı: **Admin → Keys** altında bir `events:add` anahtarı oluşturun, ardından [daemon'ı aracı makinesinde bağlayın](/tr/start/setup#connect-a-machine-to-cloud). SDK diske yazar; daemon gönderir. + +## Yapılandırma + +### OpenTelemetry span'ları (devre dışı seçeneği) + +OpenTelemetry'i `npm install @opentelemetry/api @opentelemetry/sdk-trace-base` ile ayrı olarak kurun. +Ardından FailproofAI'ı sağlayıcınızın işlemcilerine ekleyin: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Mevcut bir sağlayıcı için, diğer işlemcilerini aynı listede tutun. `addSpanProcessor` sunan sağlayıcılar bunun yerine `{ provider }` olarak geçirilebilir. Seçeneksiz, kurulum yalnızca başka bir sağlayıcı zaten kayıtlı değilse yeni bir sağlayıcı kaydeder. +`OtelSpanExporter` ayrıca kendi işlemcinizle doğrudan kullanılabilir. + +İhracat bağlı FailproofAI daemon'ı üzerinden gider; SDK ağ istekleri göndermez ve anahtara veya yerel dinleyiciye ihtiyaç duymaz. Bir yöneticiden [OpenTelemetry alımını](/tr/agenteye/opentelemetry) etkinleştirmesini isteyin. Boş bir `instrument()` bu dışa aktarıcıyı etkinleştirmez. `uninstrument("otel")` yalnızca kendi işlemcisini devre dışı bırakır. +Span öznitelikleriniz içerik yakalamasını kontrol eder; çıkıştan önce sağlayıcınızı temizleyin. +OpenTelemetry isteğe bağlı bir uygulama bağımlılığı olarak kalır, SDK'nın sabit bağımlılığı değil. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Seçenek | Ne yaptığı | +| --- | --- | +| `environment` | Her olayda etiket — `production`, `staging`, `prod-eu`. Varsayılan olarak `dev`. | +| `flushInterval` | Zamanlayıcının diske yazma sıklığı, saniye cinsinden. Varsayılan olarak `0.5`. | +| `baseDir` | Nereye yazılacağı. Varsayılan olarak daemon'ın spool'u, aksi takdirde bilmiyorsanız istediğiniz şey. | + +Tümü doğrulanmadığı sürece hiçbir şey uygulanmaz, bu nedenle reddedilen bir çağrı SDK'yı yeni `baseDir` ve eski aralıkla bırakmak yerine tam olarak olduğu gibi bırakır. + +Bunun yerine ortam değişkeniyle ayarlayın: + +| Değişken | Ne yaptığı | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | `environment`'ı kod değişikliği olmadan ayarlar. `configure()` seçeneği bunu geçersiz kılar. | +| `FAILPROOFAI_HOME` | Spool'u tutan Failproof AI kökünü taşır. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (varsayılan), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` enstrümentasyon hatalarının günlüğe kaydedilmek yerine throw etmesini sağlar. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` bir framework uyumluluğu sorununun uyarı vermek ve devam etmek yerine throw etmesini sağlar. | + + + **`environment` içinde virgül yok.** İçe alma bu alanı virgülde bölerek filtrelerini oluşturur ve virgül içeren bir etiketi olan herhangi bir olayı atlar — böylece tüm bir çalıştırma sessizce kaybolur. `prod,eu` değil `prod-eu` yazın. + + `configure({ environment: "prod,eu" })` hemen fark etmeniz için throw eder. `AGENTEYE_ENVIRONMENT` throw edemez — hiç kimse sizi çağırmıyor — bu nedenle bir kez uyarır ve `dev` öğesine geri döner. + + +SDK'nın kendi günlük satırlarını `failproofai.setLogger({ debug, info, warn, error })` ile günlükçüğe yönlendirin. + +## Kapatma + +Arabelleğe alınan olaylar `process.on("exit")` üzerinde temizlenir. + +Bir sinyal tarafından öldürülen işlem asla buna ulaşmaz ve `SIGTERM` için Node'un varsayılanı çıkış işleyicileri çalıştırmadan sonlandırmaktır — bu nedenle kapsayıcılı bir aracı son aralığın yazılmadığını kaybeder. + + + **Bu SDK sizin için bir sinyal işleyicisi kurmayacak.** Birini kaydetmek işleminizin davranışını değiştirir: bir dinleyici Node'un varsayılan sonlandırmasını bastırır, bu nedenle bir tane ekleyen bir kütüphane sessizce Ctrl-C'nin çalışmasını durdururdu. Kendi yapınızı ekleyin: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Kısa süreli bir komut dosyası veya sunucusuz bir işleyici, döndürmeden önce `await failproofai.flush()` yapmalıdır — aralık tek başına teslimatı garanti etmez. + +## Kimlik + +Her olay bir oturum ve bir aracıya aittir. **Kapsamlar her ikisini de doldurur**, bu nedenle nadiren onları geçersiniz: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +`sessionId` veya `agentId` açıkça geçmek hala çalışır ve kazanır. Ne bağlı ne de geçildiği halde, çağrı Cloud'un sessizce atmış olacağı bir olayı yayınlamak yerine throw eder. + + + Kimlik `AsyncLocalStorage` üzerinde yer alır. `await`, `.then()`, zamanlayıcılar ve kapsam içinde oluşturulan herhangi bir geri çağırma izler. Bir çalıştırma sırasında depolanan ve başka bir sırada çağrılan bir geri çağırma veya bir `worker_threads` sınırında elle alınan iş izlemez — bunları `failproofai.propagate()` içinde saralım veya olayları bağlantısız iniş yapın. + + +### Kapsamlar + +| Kapsam | Yayınlar | Döndürür | +| --- | --- | --- | +| `session(body)` | hiçbir şey — yalnızca kimlik | `body`'nin ne döndürdüğü | +| `agent(id, options?, body)` | `agent_start`, sonra `agent_end` | `body`'nin ne döndürdüğü | +| `toolCall(name, options?, body)` | `tool_use`, sonra `tool_result` | `body`'nin ne döndürdüğü | + +Senkron bir gövde senkron kalır: `agent("x", () => 1)` bir promise değil `1` döndürür. + +`toolCall` gövdenin çözülmüş değerini aracın `output` olarak kaydeder, siz `call.output` atamadığınız sürece. + + + +| Ne oldu | Olaylar | `outcome` | +| --- | --- | --- | +| blok döndü | `agent_end` | `"success"` veya sizin `outcome` | +| blok throw etti | `error`, sonra `agent_end` | `"failed"` | +| bir `AbortError` | yalnızca `agent_end` | `"cancelled"` | + +Hata her zaman yeniden throw edilir. + +Bir aracı başarısızlığı yaprağa kaydedilir — `tool_result` bir `error` dizesiyle — ve **hiç** çalıştırma düzeyinde `error` olayı yayınlamaz. Aracı döngüsünün yakaladığı çalıştırma başarısızlığı değildir ve yayılan bir kez, çevresel `agent()` tarafından bildirilir. + + + + + +İş tek bir fonksiyon olmadığında — bir yapıcıda açılan ve bir yıkımda kapatılan bir kapsam, veya mevcut kontrol akışını kapsayan: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +Her iki form bayt için aynı olaylar yayınlar. Geri çağırma formunu tercih edin: `AsyncLocalStorage.run()` içinde çalışır, bu nedenle geri sarılacak hiçbir şey yoktur ve "burada açılmış, orada kapatılmış" hataların tüm sınıfı ulaşılamaz. + +Kendi başarısızlığını yakalayan bir `using` bloğu `span.fail(error)` ile bildirir — dispozerin kendi istisna kanalı yoktur. + + + +## Olay kataloğu + +Python SDK'sı ile aynı on beş yöntem, camelCase'te. Çoğu **çiftler** halinde gelir — açıcıyı çağırır, sonra kapıcıyı, ve SDK boşluğu zamanlar. + +| | Açar | Kapatır | +| --- | --- | --- | +| **Aracılar** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Modeller** | `modelRequest` | `modelResponse` | +| **Araçlar** | `toolUse` | `toolResult` | +| **Kancalar** | `hookTriggered` | `hookCompleted` | +| **İnsanlar** | `humanWait` | `humanInput` | + +Üç bağımsız: `error`, `humanPause`, `humanInterrupt`. + + + +Her yöntem ayrıca `sessionId` ve `agentId` alır, kapsamlar sizin için doldurur. Atlanmış hiçbir şey JSON `null` olarak gönderilmek yerine bırakılır. + +| Yöntem | Gerekli | İsteğe Bağlı | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Eklediğiniz diğer herhangi bir anahtar özel bir yük alanı olur. Framework'e özel herhangi bir şeyi `fw_*` ile adlandırın; bildirilmiş bir alanla çakışan bir ad sessizce tanıtılan bir sütunu üzerine yazmak yerine reddedilir. + + + + + **`duration_ms` hesaplanır, kabul edilmez.** Dört kapatma yöntemi açıcıdan boşluğu zamanlar ve arayan tarafından sağlanan `duration_ms` reddeder — bildirilen süre sahteci yapılamaz. + + Çiftler oturuma ve kimliğe göre eşleştirilir, hiçbir zaman aracıya değil. `planner` altında açılan ve `worker` altında kapatılan bir araç hala eşleşir, bu iç içe çok aracılı çalıştırmaların gerçekten yaptığı şeydir. + + +## Framework adaptörleri + +```ts +await failproofai.instrument(); // bulabildiği her şey +await failproofai.instrument("langchain"); // tam olarak bir tane +failproofai.uninstrument(); // her şeyi geri koy +``` + +| Framework | Desteklenen | Nasıl bağlanır | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, yani her `invoke`/`stream`/`batch` hiçbir yerde `callbacks:` geçirmeden kapsanır — veya `langchainHandler()` kendini geçin ve hiçbir şeyi yama yapmayın. | +| **Vercel AI SDK** | `ai` 4 – 7 | Çağrı sitesinde `telemetry()` veya tüm işlem için `instrument("ai")` — `ai` 7'de (4–6'da bu devre dışı seçenek — aşağıya bakın). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, aracının model ve araç çözümü ve iş akışı çalıştırma/adım motoru. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (abone) artı `AgentWorkflow.runStream`, iş akışı çalıştırmaları ve adımları için. | + +Her aralık, her CI çalıştırmasında, her iki uçta da, ES modülü ve CommonJS olarak gerçek framework sürümlerine karşı test edilir. + +Eşleme Python SDK'sının eşlemesidir, bu nedenle aynı program her iki dilde aynı ağacı çizer. Bir yapı, bir LLM karar döngüsüne sahipse **aracı** — bir grafik veya zincir çalıştırması, bir AI SDK `generateText`/`streamText` çağrısı, Mastra aracısı, LlamaIndex aracısı çalıştırması. Bir LangGraph düğümü veya iş akışı adımı **kanca** (`hook_triggered`/`hook_completed`), asla iç içe aracı değil. Model çağrıları, belirteç sayılarıyla birlikte `model_request`/`model_response` çiftleridir; araç çağrıları modelin kendi araç çağrısı kimliğini taşır. Bir başarısızlık meydana geldiği olayda bir kez kaydedilir. + +Kurulması başarısız olan bir adaptör günlüğe kaydedilir ve atlanır; diğerleri yine de kurulur, çünkü kırılmış bir LlamaIndex size LangGraph'ı mal etmemeli. + + + Bağımsız değişken olmadan `instrument()` bir framework'ü zaten içe aktarılıp aktarılmadığına göre değil, **çözülüp çözülmediğine** göre algılar — Node ES modülleri için Python'ın `sys.modules` eşdeğeri sunar. Yüklü ama kullanmayan bir framework içe aktarılır ve yama yapılır. İstediğinizi adlandırın, eğer bu önemliyse. + + + + Bu framework'lerin çoğu bir ES modül yapısı ve Node'un iki ilişkisiz kopya olarak yüklediği bir CommonJS yapısı gönderir. Adaptörler uygulamanızın yüklediği kopyaya yama yapar (ve bir şey zaten `require` ettiyse CommonJS kopyasına da), böylece her iki modül sistemi çalışır. Bir framework **esbuild veya webpack'e göre kendi çıktınıza paketlenir** ulaşılamaz — orada çağrı sitesi yardımcılarını kullanın: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### Yamalamadan LangChain + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +İşleyici `instrument()` ile veya olmadan çalışır ve asla çift kaydını yapmaz. `instrument("langchain")` `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` ve `captureLimit` alır, Python adaptörü yaptığı gibi; bir çağrıda `metadata: { failproofai_sdk_session_id }` o çağırma için oturumu seçer. + +### Vercel AI SDK + +AI SDK, bir ES modülünden düz işlevleri dışa aktarır ve bir ES modülü ad alanı belirtim tarafından değişmez — yamanacak hiçbir yer yoktur. SDK'nın kendisinin belgelediği uzantı noktalarını kullanır: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // ai 7'de, `telemetry: telemetry({ … })` — aynı nesne, yeni ad +}); +``` + +Bu tüm entegrasyon: bir aracı aralığı, adım başına belirteç sayılarıyla bir model istek/yanıt çifti ve her araç çağrısı. Bir çağrı sitesi her majöre çalışır — `ai` 4–6 taşıdığı iz okur, `ai` 7 telemetri tümleştirmesi. + +`instrument("ai")` **`ai` 7'de** aynı işlemi tüm işlem için yapar: AI SDK'nın global telemetri tümleştirme listesi, katkı yönlü ve kimse başkasından hiçbir şey almayan her çağrı. + +**`ai` 4–6'da, `instrument("ai")` kendisi tarafından hiçbir şey kaydetmez ve bunun söyleyen bir uyarı günlüğe kaydeder.** Bu majörlerin sahip olduğu tek işlem çapında kanca, küresel OpenTelemetry iz sağlayıcısı — bir kez alındıktan sonra OpenTelemetry'nin teslim etmeyi reddettiği tek yuva. Bizim kaydetmek daha sonra başlangıçta sizin kendi `NodeSDK.start()` öğenizi sessizce reddedecek ve http/database aralıklarınızı hiçbir şey dışa aktarmayan bir izleyiciye gönderecektir. Çağrı sitesinde `telemetry()` kullanın veya orada `wrapModel`. İşlem kendi OpenTelemetry'sini çalıştırmıyorsa, `instrument("ai", { registerGlobalTracer: true })` ile devre dışı seçeneği açın: ardından `experimental_telemetry: { isEnabled: true }` geçen her çağrıyı kaydeder ve yalnızca hala boşsa yuvasını alır. `registerGlobalTracer: false` varsayılanı korur ve uyarıyı kaldırır. + +Modeli bir kez sarmalamayı tercih ederseniz, `wrapModel` yalnızca model çağrılarını görür, çünkü araç çağrıları model katmanının üzerinde olur. Etrafında hiçbir şey ile sarmalanan bir model kendi çalıştırması olarak kaydedilir. Akışlı bir çağrı akışın nasıl durduğuna bağlı olarak kapanır — tüketici iptal ettiğinde `stop_reason: "cancelled"`, yarı yolda başarısız olduğunda `"error"` hatasıyla: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Her ikisini kullanmak iyidir: ara yazılım çağrının zaten kaydedildiğini fark eder ve erteler, bu nedenle her çağrı bir kez kaydedilir. + +`functionId` aracı aralığını adlandırır. Düşük kardinalite tutun — birincil pano faset olan `agent_id` olarak iniş yapar. + +### Next.js + +`next build` sunucunuzun bağımlılıklarını varsayılan olarak paketler ve yapının içine paketlenen bir framework, `instrument()` ulaşamadığı bir kopyasıdır. Yapılandırmayı bir kez sarmalayın ve Next'in başlangıç kancasından `instrument()` çağırın: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` LangChain, Mastra, LlamaIndex ve SDK'nın kendisini `serverExternalPackages` öğesine ekler, sizin listesini korur. Bunu yapmazsanız, `instrument()` sessizce başarısız olmak yerine ulaşamadığı framework başına bir kez uyarır; paketleri kendiniz listelerseniz `FAILPROOFAI_NEXT_EXTERNALS=1` ayarlayın. Vercel AI SDK ve çağrı sitesi yardımcıları her iki şekilde de çalışır. Bir Edge rotası no-op yapısı alır: SDK'yı içe aktarmak güvenlidir ve hiçbir şey kaydetmez. + +### Akışlı çağrılar üzerinde belirteç sayıları + +OpenAI uyumlu API'ler, istemci sorduğunda bir akışta kullanımı yalnızca bildirir. LangChain ve Vercel AI SDK sordu; LlamaIndex için `additionalChatOptions: { stream_options: { include_usage: true } }` öğesini kendi `OpenAI` LLM'sine geçirin ve Mastra için modeli kullanım etkin olarak oluşturun (örneğin `createOpenAICompatible({ includeUsage: true })`). Aksi takdirde akışlı model çağrıları belirteç sayısı taşımaz. + +### Çalışma zamanları + +Node ≥ 20.9, Bun ve Deno — her framework, bir ES modülü ve CommonJS olarak her bireyde Node'un izine karşı test edilir. SDK, yazanları gönderen `failproofaid` daemon'ı yanında çalışır. + +## Kendi aracınız — framework yok + +Kendiniz yazdığınız bir aracı döngüsü veya adaptörü olmayan bir framework için. Olayları adaptörlerin altında kullandığı aynı API ile yayımlarsınız, bu nedenle iz aynı şekil ve kaliteye sahip. + +Aracının nasıl organize edildiğini bilmeniz gerekmez. Fonksiyonları ne denirse densin, elde derlenen her aracının zaten üç yeri vardır ve bu üçü tüm entegrasyondur: + +| Nerede | Ne eklenecek | Yayınlar | +| --- | --- | --- | +| Burada **bir çalıştırma** başlar ve biter | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| Modeli çağıran **tek işlev** | `event.modelRequest` önce, `event.modelResponse` sonra — başarısızlıkta da her iki yarı | model dönüşü başına bir çift | +| Araçları çalıştıran **tek işlev** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +Kimlik ortam ortamı: `agent()` içindeki her şey bir kimlik almadan o çalıştırmanın oturumuna iniş yapar ve programdaki başka hiçbir şey değişmez — aracının zaten kendi veritabanına yazdığı da dahil. + +- **Bir hizmet veya işçi:** kendi istek veya iş kimliğini `sessionId` olarak geçin, böylece panodaki bir oturum ve kendi günlüklerinizde veya veritabanınızda kayıt aynı dizedir. +- **Alt aracılar:** `agent()` çağrılarını iç içe yerleştirin. İç, dış oturuma `parent_id` olarak katılır. +- **Çiftleri yayınlayın.** Modelresponse `olmayan bir `modelRequest`, panonun sonsuza kadar çalışıyor olarak gösterdiği bir aralık — dolayısıyla `catch`. + +Deponun [`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts), tam, çalıştırılabilir sürümüdür: gerçek OpenAI aracı döngüsü tam olarak bu şekilde enstrümente edilmiş, her değişiklikte CI'da ES modülü ve CommonJS olarak çalıştırılır. + +## Değerlendirmeler + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Protokol, işçi ayarları ve sonuç türleri için [Değerlendirici SDK başvurusuna](/tr/reference/evaluator-sdk) bakın. + + + **Bir değerlendirme vermelidir.** Hiçbir zaman döndürmeyen senkron bir işlev Node'un sahip olduğu tek iş parçacığını engeller ve hiçbir zaman timeout ateşleyemez. `async` değerlendirmeler yazın. + + +## İşleminize ne yapmayacağı + +| | | +| --- | --- | +| **Aracı döngünüzü engelle** | Olaylar hafızadaki kuyruğa gider; bir zamanlayıcı onları yazar. Zamanlayıcı `unref`'lenmiştir, bu nedenle bu paketi içe aktarmak hiçbir zaman komut dosyasını çıkıştan durdurur. | +| **Sınırlar olmaksızın büyü** | Kuyruk sayıya **ve** ölçülen baytlara göre kapatılır. Her biri geçtikten sonra, en eski olaylar atılır ve bir uyarı bunu söyler — telemetri kesintisi OOM öldürmesi olmamalı. | +| **İşlemi aşağı al** | Kodlanmayan bir olay yalnız bırakılır, etrafındaki toplu değil. Atma getter, döngüsel referans, `BigInt`, yalnız vekil: her birine ele alınır, yayılmaz. | +| **Yarı yazılı toplu bırak** | İçerik `fsync`'lenmiştir; atomik yeniden adlandırmadan ve dizin `fsync`'lenmiştir sonra ve başarısız yazma geçici dosyasını temizler. | +| **Transkriptleri okunabilir bırak** | Toplu işler `0600` içindedir bir `0700` dizin. Hedefler, istemler, araç argümanları ve araç çıktısı taşırlar. | +| **Kimlik bilgilerine gemi** | API anahtarları, belirteçler, JWT'ler, taşıyıcı başlıkları ve gizli şekilli atamalar, baytlar diske ulaşmadan önce redakte edilir. Daemon, yükleme yapılmadan önce tekrar redakte eder. | \ No newline at end of file diff --git a/docs/tr/reference/custom-agents.mdx b/docs/tr/reference/custom-agents.mdx index 3dd999854..68e78c2a3 100644 --- a/docs/tr/reference/custom-agents.mdx +++ b/docs/tr/reference/custom-agents.mdx @@ -15,7 +15,7 @@ Her ayarın, metodun ve alanın ne işe yaradığı. İlk kez enstrümantasyon y -Python 3.10 veya daha yeni. Runtime bağımlılığı yok. +Python 3.11 veya daha yeni. Runtime bağımlılığı yok. ## Kurulum diff --git a/docs/tr/reference/jev-cloud.mdx b/docs/tr/reference/jev-cloud.mdx new file mode 100644 index 000000000..b1f43bfa1 --- /dev/null +++ b/docs/tr/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "FailproofAI Cloud üzerinden Jev" +description: "Bulut makine anahtarları, bağlantı durumu, limitler ve canlı Jev ilke incelemesi için başarısızlık davranışı." +icon: "cloud" +--- + +Bu, [Jev ilkeleri](/tr/policies/jev) için Bulut rotası referansıdır. TypeSafe'in sınıflandırıcısı olan Jev, her araç çağrısını sizin gerçekte istediğiniz şeyle karşılaştırır ve ilkelerinizin yanında cevap verir, asla onların yerine değil. **FailproofAI Cloud** aracılığıyla, bağlı bir makine Jev'i zaten bağlandığı aynı anahtarla kullanır: TypeSafe hesabı yok, ikinci anahtar yok, yapılandırılacak uç nokta yok. Her çağrı, kuruluşunuzun mevcut plan tahsisine yüklenir. + +Jev'in yaptığı her şey, [kendi anahtarını getir kurulumundan](/tr/reference/jev-providers) değişmez: sert ilkeler nihai kalır, inceleme yapılabilir ilkenin inkarı yalnızca Jev'e tam olarak bu sorun hakkında sorulduğunda temizlenir ve herhangi bir başarısızlık o çağrı için regex sonucuna geri döner. + + +**failproofai 1.0.8-beta.0** veya daha yeni bir sürüm gerekir. 1.0.7'de Jev yoktur, hatta 1.0.7 beta'larının üzerine sıralanmasına rağmen. Jev yapılandırması olmadan hiçbir şey değişmez: kancalar regex ilkelerini her zaman olduğu gibi çalıştırır. + + +## Başlamadan önce + +FailproofAI'ı aracınızın çalıştığı makinede kurun ve kancalarını [desteklenen bir sisteme](/tr/reference/harnesses) bağlayın. Sıfırdan başlıyorsanız, kanca kurulumuna kadar [hızlı başlangıcı](/tr/start/quickstart) izleyin. Yüklü CLI'yi `failproofai --version` ile kontrol edin; Jev'den önceki bir sürümü varsa güncelleyin. Ayrıca makine anahtarı oluşturmak için kuruluşunuzun **Administration → Keys** sayfasına erişime ihtiyacınız vardır. + +Jev, `PreToolUse` veya `PermissionRequest` kapısında adlandırılmış araç çağrılarını inceler. Oturumdaki her olayı incelemez. Jev'in ilke inkarını temizlemesini görmek için, [inceleme yapılabilir](/tr/policies/authority) olarak işaretlenmiş yüklü bir ilkeye ihtiyacınız vardır; diğer tüm ilke inkarları nihai kalır. + +## Açın + +1. **Jev ile bir anahtar oluşturun.** FailproofAI Cloud panosunda **Administration → Keys → Create key** açın ve **machine** ön ayarını seçin. Bir makinenin ihtiyaç duyduğu üç izni verir: `events:add` (etkinlik gönder), `policies:pull` (ilkeleri al) ve `jev:evaluate` (Jev, kuruluşunuzun plana yüklenir). Anahtar diğer ikisi olmadan `jev:evaluate` taşıyamaz. +2. **Makineyi** o anahtarla bağlayın. Komut isteminde tek seferlik sırrını okuyun, ardından tam kurulum komutunu çalıştırın: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config`, daemon'u yükler, bulduğu ajan CLI'lerine kancalar bağlar ve makineyi bağlar. Ortam değişkeni anahtarı komutun bağımsız değişkenlerinin dışında tutar ve kabuk geçmişinizden uzaklaştırır. Sisteminiz daha sonra kurulduysa, [onu açıkça bağlayın](/tr/start/quickstart). + + Kuruluşunuz barındırılanmış yerine kendi FailproofAI Cloud'unu çalıştırıyorsa, adresini ekleyin: `--url https://` (veya `FAILPROOFAI_CLOUD_URL` dışa aktarın). Olmadan anahtar barındırılan hizmet karşısında kontrol edilir ve bağlantı başarısız olur. Bu ana bilgisayarın sertifikası özel bir CA'dan geliyorsa, CA'yı makinenin sistem güven deposuna kurun (örneğin `update-ca-certificates` ile), yalnızca `NODE_EXTRA_CA_CERTS` içinde değil: olayları gönderen ve ilkeleri çeken daemon sistem deposunu okur. Bkz. [Sorun Giderme](/tr/reference/troubleshooting). + +Bu kadar. Bağlanmak anahtarı depolar ve makine henüz Jev yapılandırmasına **sahip değil** olduğunda, FailproofAI Cloud için bir tane yazar. Makinenin ilk dağıtımından (yaklaşık 30 s içinde) FailproofAI Cloud modu ayarlar: bir Jev ilkesi ona dağıtılmışken `enforce`, hiçbiri olmadığında `off` (bkz. [Modu kim ayarlar](#who-sets-the-mode)). Çıktı şunu söyler: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +FailproofAI Cloud dağıtımlarını Bulut'ta çalıştırdığı kontrolleri. Makinede kendi kontrolleri eklemek için bir paket kurun: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**`--no-transcripts` ile, bağlanmak Jev'i açmaz.** Jev her kontrol edilen araç çağrısını ve son istemi FailproofAI Cloud'a gönderir, bu sadece karar bağlantısı göndermesi istenenden daha fazladır. Anahtar yine de depolanır ve çıktı Jev'in kullanılabilir olduğunu ve nasıl açılacağını söyler: + +```bash +failproofai jev setup --provider failproofai +``` + +Ayrıca FailproofAI Cloud üzerinden Jev'i **kapatır**. FailproofAI Cloud üzerinden Jev'i çalıştıran bir `jev.json` (transkriptler açıkken önceki bir bağlantıdan kalan) aynı kural tarafından kaldırılır (`config --disconnect` kullanır) ve çıktı Jev via FailproofAI Cloud'un bu makinede kapalı kaldığını söyler. Kendi Jev uç noktanız için bir `jev.json` bırakılır ve kapalı (kapatılan) bir FailproofAI Cloud'u da öyle. + + +Bağlanmak **hiçbir zaman** mevcut bir `~/.failproofai/jev.json` dosyasını üzerine yazmaz. Zaten kendi Jev uç noktanızı kullanıyorsanız, kullanılmaya devam eder ve çıktı dosyanın yapılandırıldığı gibi bırakıldığını söyler — ve bu dosya Jev'i kapalı bıraktığında (reddedildi veya kapatıldı), bunu ve nasıl düzelteceğini söyler. Bu makineyi FailproofAI Cloud'a geçirmek için `failproofai jev setup --provider failproofai` çalıştırın. + + +## Modu kim ayarlar + +FailproofAI Cloud'a bağlı bir makinede, **FailproofAI Cloud Jev modunu ayarlar**; makinede hiçbir şey yapmaz: + +- makineye herhangi bir Jev (veya regex + Jev) ilkesi dağıtılmışken `enforce`: bu ilkelerden biri hedefleyen bir ajan tarafından gelen her kontrol edilen araç çağrısı, kontrolleri orada yüklü paketlerin kontrolleriyle birlikte soracak FailproofAI Cloud'a gider. Cloud Jev ilkesinin hedeflediği bir ajandan gelen çağrı, kendi paket kontrolü olmadığında hiç gönderilmez. `enforce` modunda, Jev'in kendi inkar kontrolleri çağrıları engeller ve ayrıca inceledikleri regex kararlarını temizler. +- hiçbiri olmadığında `off`: `jev.json` ne derse desin Jev yok. + +Jev ilkesini hareket etmeden önce denemek için, onu **observe** etkisiyle dağıtın: kontroller yine de sorulur ve ne yapacakları ilke sayfasında **would-have** olarak kaydedilir, ancak çağrıyı hiçbir zaman engeller ve asla temizlemez. `failproofai jev setup --mode` ve panonun **Settings → Jev** modu FailproofAI Cloud tarafından yönetildiğini söyler ve hiçbir şeyi değiştirmez. `jev.json` başka bir sağlayıcı adlandırsa bile Cloud'un kontrolleri için kullanılmaz. `failproofai config --disconnect` Jev'i makinenin kendi `jev.json` dosyasına geri verir. + +`failproofai jev status` daha sonra `Jev checks run on FailproofAI Cloud (mode: enforce)` der. Ayrıca her `both` ilkesini inceleyen kontrolleri adlandırır. Filo sayfası bir mod yükleme yapamayan makinenin nedenini gösterir: + +- `transcripts_disabled`: makine `--no-transcripts` ile bağlandı, bu asla Jev'i açmaz. +- `jev_unconfigured`: makinenin anahtarı `jev:evaluate` taşımaz. +- `jev_rate_limited`: FailproofAI Cloud, kuruluşunuzun Jev hız limitine yönelik makinenin bazı çağrılarını reddetti ve bu çağrılar yalnızca regex ilkeleri tarafından kararlaştırıldı. +- `jev_unavailable`: arka arkaya birkaç çağrı başarısız oldu, bu nedenle makine bir seferde bir dakika boyunca FailproofAI Cloud'un Jev'ini atlar. Kendi başına yeniden dener. + +FailproofAI Cloud 5 saniye içinde yanıt vermezse, regex ilkeleri yalnız karar verir, herhangi bir Jev kesintisi gibi. Arka arkaya 3 başarısızlıktan sonra makine bir seferde bir dakika boyunca sormayı durdurur, bu nedenle Cloud kesintisi her araç çağrısını yavaşlatmaz. + +Oturum duraklaması (`failproofai config --pause`) FailproofAI Cloud'un Jev kontrollerini durdurmamasına rağmen, Cloud tarafından yönetilen ilkeleri de durdurmamasına rağmen durdurmaz. Makinede yüklü paketlerin Jev kontrollerini duraklatır. + +## Ne yaptığını kontrol edin + +```bash +failproofai jev status +failproofai jev test +``` + +`status` sağlayıcıyı **FailproofAI Cloud**, makinenin bağlandığı Cloud ana bilgisayarı, modu ve anahtar kaynağını **FailproofAI Cloud connection** olarak gösterir, hiçbir zaman anahtarı değil. Bir FailproofAI Cloud `jev.json` vardır ancak Jev çalışamıyorsa nedenini söyler: + +| `status` der | `status --json` | Anlamı | +| --- | --- | --- | +| **off — bu makinenin FailproofAI Cloud bağlantısı için hiçbir Jev anahtarı depolanmaz** | `key-lacks-jev` | Makine bağlıdır, ancak onun için hiçbir Jev anahtarı depolanmaz: anahtar `jev:evaluate` eksiktir veya bağlantı bunu doğrulayamaz. `FAILPROOFAI_CLOUD_TOKEN` içindeki anahtar ile `failproofai config` komutunu tekrar çalıştırın; izin eksikse **machine** anahtarı kullanın. | +| **off — bu makine FailproofAI Cloud'a bağlı değil** | `not-connected` | Bu makinede Jev anahtarının ait olacağı FailproofAI Cloud bağlantısı yok. | + +`failproofai config --disconnect` sonrasında artık FailproofAI Cloud `jev.json` yok (kapalı bırakılmadıkça, bu saklanır), bu nedenle `status` yalnızca Jev'i kapalı olarak raportar. `status --json` aynı gerçekleri taşır (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), yapılandırma yokken veya reddedildiğinde de. `permissions` her zaman `jev.json`'dir; `credentials.json` hakkında bir red `credentialsPermissions` ekler ve bir komut bunu düzelttiğinde `fix`. `test` bir canlı istek gönderir ve gecikmesini ve cevap veren Jev sürümünü raportar. Cevap kanca zaman aşımından sonra geldiğinde (kancalar `timeout` kaydeder) veya kontrol sorusuna yanlış cevap verdiğinde 1'le çıkar ve başlığında bunu söyler. + +Panonun **Settings → Jev** paneli de **FailproofAI Cloud bağlantısını** gösterir: makine raporladığı kuruluş ve anahtarı Jev taşıyıp taşımadığı. Makinenin kendi dosyalarından okunur, ağ çağrısı olmadan. + +## Gerçek bir çağrıyı doğrulayın + +Hooked agent'da yeni bir oturum başlatın. Dosya okuma aracını `README.md` üzerinde kullanmasını ve başlığı raporlamasını isteyin. Oturumun bu araç çağrısını içerdiğini doğrulayın, ardından `failproofai jev status` komutunu yeniden çalıştırın: son değerlendirilen çağrı sayısı artmalıdır. [Yerel panonun](/tr/reference/local-dashboard#review-policy-activity) **Policies → Activity** bölümünü açarak bu çağrının Jev kararını ve modunu inceleyin. Bulut'ta, kuruluşunuzun **Policies** sayfası teslim edilen etkinlik için Jev sonuçlarını gösterir. Gözlem modunda, karar **would-have** olarak kaydedilir ve ilke sonucu yine de çağrıyı kararlaştırır. Temizleme yalnızca inceleme yapılabilir ilke eşleştiğinde ve Jev adlandırılmış kontrolleri temizlediğinde görünür. + +## İlke sayfasına ne ulaşır + +Makine zaten kanca etkinliğini FailproofAI Cloud'a gönderir (`events:add`). Jev açıkken, her kapılı çağrının kaydı ayrıca hangi değerlendiricinin çalıştığını, Jev'in ne kararlaştırdığını, hangi ilkeleri temizlediğini, geri döndüğü zamanı, gecikmesini ve cevap veren modeli söyler — kararlar, kodlar ve adlar, hiçbir zaman komut veya isteminiz değil. Kuruluşunuzun **Policies** sayfasında: + +- Jev'in kendi kararının kararlaştırdığı çağrı (`enforce` modu) **Jev** ile ilişkişlendirilir ve karar veren kontrol bir paketten geldiğinde, kayıt da o paketi ve sürümünü adlandırır; +- gözlem modunda, Jev'in inkarı veya uyarısı gözlediğiniz dağıtımların yanında **would-have** olarak görünür; +- Jev'in temizlediği ilkeler veya gözlem modunda temizleyeceği ilkeler ilke başına sayılır. +- Jev'in katıldığı karar (bir blok, uyarı, temizleme veya gözlem modunda would-have) sorduğu her kontrol ve o kontrolün ne sonuçlandığını listeler: karar, neden (`not-detected`, `exempt`, `fired`, `op-requested`, …), kanıtı `p`, `exempt` cevabı ve her sond'un cevabı. Gözleyecek şekilde dağıtılan ilkenin kontrolü da listelenir, izlenen olarak işaretlenir; hiçbir zaman engeller. Jev olasılıklar ile cevap verir, metinsel değil, bu nedenle hiçbir ücretsiz metin nedeni yoktur. Düz izinler sayılara yuvarlanır ve bu listeyi taşımaz. + +## Jev yanıt veremediğinde + +Bunların her biri o çağrı için ilkelerinizin sonucuna geri döner ve sebebiyle kaydedilir: + +| Neden | Sebep | +| --- | --- | +| `out-of-credits` | Kuruluşunuz plan tahsisini kullanmıştır. | +| `http-401`, `http-403` | Anahtar iptal edildi veya `jev:evaluate` taşımaz. `jev:evaluate` taşıyan bir anahtarla yeniden bağlanın. | +| `http-429` | FailproofAI Cloud, kuruluşunuz için Jev'i hız sınırlandırıyor. Sorduğu bekleme bitene kadar (onun `Retry-After`, en fazla 60 saniye), makine ona hiçbir şey göndermez ve her çağrı hemen geri döner. O şekilde tutulmuş çağrılar `http-429` olarak kaydedilir veya makinenin kendi hız sınırı önce tuttuğunda `rate-limited` olarak. | +| `http-429` (günlük limit) | Kuruluşunuz günlük Jev çağrılarını kullanmıştır: **UTC gün başına 10.000**, FailproofAI Cloud'u işleten kişi başka bir limit belirlemediği sürece. Her çağrı sayaç 00:00 UTC'de sıfırlanana kadar geri döner; makine hala en fazla dakikada bir sorabilir, bu nedenle sıfırlamayı dakika içinde alır. `failproofai jev test` "Daily Jev limit for this org reached; resets at 00:00 UTC." der. | +| `http-422` | Jev bu çağrının isteğini reddetti, genellikle araç çağrısı Jev'in token bütçesinin üzerinde yoğun metin (base64, hex, minifiye kod) içerdiği için. Bu çağrı her defasında geri döner; kesinti değildir. | +| `http-502` | Jev şu anda kullanılamıyor. | +| `http-503` | Bu Bulut kuruluşunuz için Jev'i sunamaz: model ağ geçidi yok, henüz sağlanmamış kuruluş veya ağ geçidi kapalı. Admin'e sorun; kancalar en fazla dakikada bir sorabilir. | +| `http-404` | Bu FailproofAI Cloud henüz Jev'i sunmaz. | +| `timeout` | `timeoutMs` içinde cevap yok (varsayılan 3000). FailproofAI Cloud makinenin Jev modunu ayarlarken, bekleme 5000 ms'dir ve `jev.json`'nin `timeoutMs` kullanılmaz. | +| `model-mismatch` | 1.13 dışında bir Jev sürümü cevap verdi. | + +## Anahtar nerede yaşar ve nereye gider + +- Anahtar bir kez `~/.failproofai/credentials.json` dosyasında saklanır (`0600`, yalnız sahip dizinin içinde), diğer FailproofAI Cloud kimlik bilgilerinin yanında. `jev.json` bu rota için anahtar tutmaz; oraya yazılan anahtar yapılandırmayı geçersiz kılar. +- `credentials.json` siz dışında herhangi biri için **herhangi** izin taşıyorsa (grup veya diğer, okuma veya yazma) veya dizini siz dışında herhangi biri tarafından **yazılabilir**, **reddedilir**, okunmaz ve Jev düzeltene kadar kapalı kalır: dosyada `chmod 600`, dizinde `chmod 700` (veya yeniden bağlanın, dosyayı `0600` ve dizini yalnız sahibine yeniden yazar). Diğerlerinin yalnızca okuyabileceği bir dizin iyidir; yazabileceği bir dizin dosyayı değiştirmelerine izin verir. +- Anahtar yalnızca onunla geldiği bağlantı makinede olduğu sürece sayılır: aynı FailproofAI Cloud için ilke veya raporlama kimlik bilgisi, aynı anahtarla, aynı dosyada. Bağlı olmadan bırakılan Jev anahtarı yoksayılır ve Jev kapalı kalır. Bu, eski failproofai'nin `config --disconnect` komutu Jev anahtarını yerinde bıraktığında (kaldırması gerektiğini bilmiyor) veya eski failproofai'nin `config --token` başka bir anahtarla bağlandığında olur, bu FailproofAI Cloud'da başka bir kuruluşa ait olabilir. Jev'i geri açmak için **machine** anahtarıyla yeniden bağlanın. +- Anahtar yalnızca doğrulandığı Cloud kaynağına gönderilir. Başka yere işaret eden `jev.json` reddedilir. +- **Makinedeki ajan bunu okuyabilir.** `credentials.json` yalnız sahibine aittir ve ajan bu sahip olarak çalışır. failproofai'nin kendi dosyalarını okumak amaçlı olarak izin verilir (yalnızca değiştirmek `block-failproofai-commands` tarafından engellenir), bu nedenle ajan ve bu dosya arasında tek şey `block-read-outside-cwd` — **inceleme yapılabilir** ilke — ve home dizininizde başlatılan oturumdan hiçbir şey. `jev:evaluate` ile anahtar, kullanıldığı yerden kuruluşunuzun Jev tahsisini (günlük kapaktan) harcar, bu nedenle makine anahtarını başka bir harcama kimlik bilgisi gibi davranın: ajan bunu okumuş olabilirse, Keys sayfasında kapatın ve yeni birisiyle yeniden bağlanın. +- Yalnızca genel dosyalarınız bunu belirler. Depo Cloud Jev'i açamaz, başka yere işaret edemez veya anahtarını sunamaz ve `FAILPROOFAI_JEV_API_KEY` bu rota için yoksayılır. +- Jev değerlendirdiği her çağrı için, FailproofAI Cloud'a bir istek gider, [kendi anahtar sayfasının](/tr/reference/jev-providers#what-leaves-the-machine) listelediği şeyi taşır (sırlar düzenlenmiş). FailproofAI Cloud bunu TypeSafe'e iletir ve günlüğe kaydetmez veya saklamaz. + +## Kapatın + +Bağlı bir makinede, Jev kapalıdır; FailproofAI Cloud ona hiçbir Jev ilkesi dağıtmaz: orada Jev ilkelerini kaldırın veya arşivleyin. + +| Komut | Sonuç | +| --- | --- | +| Makinenin Jev ilkelerini FailproofAI Cloud'da kaldırın | Cloud'un modu sonraki anket sırasında (yaklaşık 30 s) `off` olur: `jev.json` ne derse desin Jev yok. | +| `failproofai config --disconnect` | Makineyi bağlantısını kes: anahtar kaldırılır ve FailproofAI Cloud'u ve kapalı bırakılmayan `jev.json` adlandırıldığında da. Kendi uç noktanız için `jev.json` kalır. | + +Sonraki araç çağrısından itibaren, kancalar regex ilkelerini tam olarak önceki gibi çalıştırır. \ No newline at end of file diff --git a/docs/tr/reference/jev-evaluations.mdx b/docs/tr/reference/jev-evaluations.mdx new file mode 100644 index 000000000..0e3ef7552 --- /dev/null +++ b/docs/tr/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev evaluation referansı" +description: "Jev oturumu değerlendirmeleri için soru türleri, kalibre edilmiş puanlar, limitler ve geriye dönük doldurma." +icon: "list-checks" +--- + +Bu sayfa, [Jev değerlendirmelerinin](/tr/evaluations/jev) arkasındaki soru şekillerini ve puanlama kurallarını açıklamaktadır. Bazı sorular bir modelin konuşmayı *okumasını* gerektirse de, onun hakkında *yazmasını* değil. "Müşteri aciliyet ifade etti mi?" sorusunun iki cevabı vardır. "Ne kadar sinirli görünüyorlardı?" sorusunun birkaç cevabı vardır ve bunlar sıralı olur. Sormadan önce tüm cevapları bilirsiniz. + +Bir **sınıflandırıcı değerlendirme** tam olarak bunlar içindir. Soruyu ve alabileceği cevapları yazarsınız, sınıflandırma için inşa edilmiş küçük bir model kalibre edilmiş bir sayı döndürür — asla serbest metin değil. + + +Bir hakim gibi, sınıflandırıcı değerlendirme oturum başına bir model çağrısına mal olur. Hakim olmasının aksine, genel bir model yerine küçük, tek amaçlı bir model olduğu için daha hızlı ve daha ucuzdur — ancak kendini asla açıklamaz. Akıl yürütmeye ihtiyacınız varsa, bir [hakim](/tr/evaluations/judge) kullanın. + + +## Hangisini istiyorum? + +| Soru | Kullanım | +| --- | --- | +| Kaç tane araç çağrısı vardı? | kod | +| Oturum 30 saniyenin altında mıydı? | kod | +| Müşteri aciliyet ifade etti mi? | **sınıflandırıcı** | +| Hangi takım bunu halletmeli: faturalandırma, teknik veya satış? | **sınıflandırıcı** | +| Müşteri ne kadar sinirli idi? | **sınıflandırıcı** | +| Cevap gerçekten doğru muydu? | **hakim** | +| Eskalasyon politikamızı takip etti mi ve bunu neden düşündüğümüzü açıklayabilir misiniz? | **hakim** | + +Temel kural: **sayılabilir → kod, cevapları listeleyebileceğiniz → sınıflandırıcı, açıklama gerekiyor → hakim.** + +Önceden karar vermek zorunluluğunuz yoktur. Ölçülmesini istediğinizi açıklayın ve asistan seçer, hangisini seçtiğini ve neden olduğunu söyler ve bunu değiştirebilirsiniz. + +## İki soru türü + +### `noul` — bu doğru mu? + +İki cevap ve her ikisini de siz açıklarsınız. Sonuç, "doğru" açıklamanın uyma olasılığıdır: + +```json +{ + "instructions": "Asistan ilk olarak geri ödeme politikasını kontrol etmeden geri ödeme sözü verdi mi?", + "criteria": { + "true": "Hiçbir önceki politika kontrolü veya onayı olmadan bir geri ödeme vaat edildi veya verildi", + "false": "Hiçbir geri ödeme vaat edilmedi veya her geri ödeme politika kontrolünü takip etti" + } +} +``` + +Her iki tarafı da açıklayın. "Aciliyet ifade edilmedi" gerçek bir cevapdır ve bunu söylemek diğerini daha belirgin hale getirir. + +### `score` — bunun ne kadarı? + +Sıralı bir rubrik, **en kötüsü ilk**. Sonuç, oturumun 0–1 arasında nerede olduğudur: + +```json +{ + "instructions": "Müşteri ne kadar sinirli?", + "criteria": ["Sakin", "Sinirli", "Çok kızgın"] +} +``` + +**Bir rubrik üç ila beş seviye alır ve hepsi farklı olmalıdır.** Her iki limit de ölçülür, stilistik değil: + +- **İki seviye** `noul`in zaten daha iyi yaptığı şeye çöker ve **beşten fazla** model ortaya doğru gitmek yerine taahhüt etmeye yönlendirir. Aynı soru aynı oturum üzerinde iki seviye ile 0.00, üç seviye ile 0.01 ve on seviye ile 0.55 puanlandı. +- **Tekrarlanan seviyeler** cevabı onlar arasında keyfi olarak böler. Açıkça sinirli bir oturum `["Sakin", "Sinirli", "Çok kızgın"]` ile 1.00 ve `["Kızgın", "Kızgın", "Kızgın"]` ile 0.66 puanlandı — hiçbir şey ifade etmeyen iyi biçimlenmiş bir sayı. + +Sipariş içermeyen kategoriler — "faturalandırma, teknik veya satış" — rubrik değildir. Bunları kategori başına `noul` olarak sorun veya bir hakim kullanın. + +## Sonuçları okuma + +Bir sınıflandırıcı, 0 ile 1 arasında bir **puan** üretir, tam olarak bir hakim gibi, bu nedenle aynı şekilde grafik oluşturur, filtreler ve uyarıları tetikler. Bilmekte faydalı olacak iki fark vardır: + +- **Açıklama yok.** Alan kasıtlı olarak boştur. Bu model kendini açıklamaz ve bir açıklama icat etmek bir özellik değil, bir sahte olurdu. +- **Belirsizlik etiketlenmiş.** Bir `score` sorusu kendi güvenini bildirir ve modelin emin olmadığı bir sonuç `low_confidence` ile etiketlenir — bu nedenle "bir insanın hangi değerini incelemesi gerekiyor" bir tahmin yerine bir filtredir. Bir `noul` sorusu güven bildirmez, bu nedenle asla etiketlenmez. + +Çok uzun oturumlar alıntılar halinde okunur ve birleştirilir. Bir oturum okumak için çok uzunsa, sonuç kaç döneminin dışarıda bırakıldığını söyler — hiçbir zaman bir oturumun tamamı üzerinde yapılmış gibi sunulan kısmı üzerinde yapılmış bir karar görmezsiniz. + +## Limitler + +- **Üç ila beş rubrik seviyesi, hepsi farklı.** Yukarıya bakın; her iki sınır da yazarlık zamanında uygulanır. +- **Değerlendirme başına bir soru.** İki şey sorun ve iki değerlendirme alırsınız, bu da grafikte istediğiniz şeydir. +- **Soruyu düzenlemek yeni bir sürümü yayınlar.** Eski ve yeni puanlar karşılaştırılamaz, bu nedenle bunlar bir trend çizgisine karışmak yerine ayrı tutulur. +- **Bir sınıflandırıcı her zaman bir puan üretir**, asla metrik veya iddia değil. +- **Açıklama yok**, yukarıdaki gibi. Bir sayı birinin "neden?" sorusunu sormasına neden olacaksa, bunun yerine bir hakim yazın. + +## Test ve geriye dönük doldurma + +Bir hakim olmasının aksine, bir sınıflandırıcı değerlendirme dağıtmadan **test edilebilir** — gerçek oturumlar üzerinde bir kod değerlendirmesi gibi [test edin](/tr/evaluations/test) ve hiçbir şey canlı gitmeden puanları okuyun. + +Ayrıca zaten sahip olduğunuz oturumlar üzerinde [geriye dönük doldurulabilir](/tr/evaluations/deploy#score-sessions-you-already-have). Oturum başına bir model çağrısına mal olur, bu nedenle pencereyi her şeyi yeniden oynatmak yerine kasıtlı olarak kapsam belirleyin. \ No newline at end of file diff --git a/docs/tr/reference/jev-intent.mdx b/docs/tr/reference/jev-intent.mdx new file mode 100644 index 000000000..f99abcb91 --- /dev/null +++ b/docs/tr/reference/jev-intent.mdx @@ -0,0 +1,112 @@ +--- +title: "Jev intent capture" +description: "Which harness events tell the Jev evaluator what the human asked for, which field carries the text, what is never counted, and the risk that comes with trusting a harness-delivered prompt." +icon: "message-square-quote" +--- + +[Jev policy review](/tr/policies/jev) konfigüre ettiğinizde, evaluator her gated tool çağrısını **insanın ne istediğine** karşı değerlendirir — harness'in agent'in önüne koyduğu her neyse onu değil. "Evet, force-push yap" gibi bir cevap **reviewable** bir policy'yi temizleyebilir — bu da evaluator'ün tüm amacı zaten, çünkü isteği okuyamayan bir regex gerçek işin üçte birini engeller. + +Bu metin bir yerden gelir: **harness'in kendisinin hook'a prompt-submit event'inde sunduğu prompt**. Failproof AI, insanın yazdığı kısmı — harness sarması çıkarılmış, sırlar redakte edilmiş, sınırlandırılmış — kendi state dizini altında bir `0600` dosyasına kaydeder. Disk'ten hiçbir şey sorgulanmaz: session transkrip, agent'in bir komutla yeniden yazabileceği bir dosya olduğu için kimsenin prompt'u yazdığı sorulmaz. + +## Bu kararın açıkça taşıdığı risk + +Zaten komut çalıştırabilen bir agent, harness'i prompt göndermeye zorlayabilir. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` ve `pi -p` hepsi aynı prompt-submit event'ini, aynı payload'ı, bir kişi yazdığında olduğu gibi tetikler — agent'in kontrol ettiği bir child session'da. Failproof AI'ın kendi hook binary'sini de çalıştırabilir ve kendisinin yazdığı bir payload'ı besleyebilir. Failproof AI içinde hiçbir şey ikisini ayırt edemez — her ikisi de aynı program, aynı stdin'i okuyor. + +**Yani shell'e sahip bir agent kendi rızasını sahte yapabilir.** Bu kasıtlı bir takas, 2026-09-23 tarihinde alınmış ve işte her iki tarafı: + +- **Ne satın alır.** Alternatif yapılıp ölçülmüştü: harness'in insanı prompt'un yazarı olarak adlandırdığı bir alan gerekli kıl, aksi takdirde hiçbir şey kaydetme. Hiçbir shipping harness böyle bir alan göndermediği için o versiyon **her harness'te hiçbir şey kaydı etmedi** — Jev her çağrısı belirtilen intent olmaksızın değerlendirdi ve asla tek bir policy'yi temizleyemedi. Asla tetiklenmeyen bir capture, daha güvenli bir ürün değildir, ürün değildir. +- **Ne yapamaz.** Kaydedilen bir prompt, sadece zaten **reviewable** olarak işaretlenmiş bir policy'yi temizleyebilir. **hard** policy asla Jev söylediklerinden temizlenmez, bu yüzden sahte bir prompt hard deny'ı allow'a dönüştüremez — ve hook'u atlamak agent'e hiçbir şey kazandırmaz: harness, tool çağrısı için Failproof AI'ı bağımsız olarak çağırır. +- **Full ölçekte ne yapabilir.** Yapabilecek en kötü şey on beş reviewable built-in policy'den birini temizlemektir — ve **bunların on ikisi engeller**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` ve altı altyapı-CLI bloğu (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) deny'dir, bu yüzden sahte rıza real deny'ı, ortam sırlarını yazdırma, `.env` dosyasını okuma, proje dışını okuma, `rm -rf`, force-push, secrets dosyasına yazma veya live altyapı değiştirme konusunda allow'a dönüştürebilir. Sadece `warn-git-amend`, `warn-destructive-sql` ve `warn-global-package-install` nudges'dir. Varsayılan kurulum on ikinin ikisini açar, `protect-env-vars` ve `block-env-files`; diğer on sadece birisi etkinleştirmişse bir makinede ulaşılır. Hiçbir prompt'un ulaşamadığı şey hard'ın tamamı — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, agent'i Failproof AI'ı devre dışı bırakmaktan koruyan guard ve reviewable olarak işaretlenmemiş her diğer built-in. [Policy authority](/tr/policies/authority) on beşini ve her birinin tarafından ne zaman incelendiğini listeler. + +Hala reddedilen her şey ucuz kontrol etmek ve agent'in sadece soru sorarak elde edemeyeceği: harness'in kendi payload'ı machine-submitted olarak işaretleyen bir turn, sub-agent adlandıran payload, düz isim olmayan session id, prompt-submit olmayan event ve harness sarması ile sınırlandırılan metin — Failproof AI'ın kendi stop-gate sözcükleri dahil, birkaç harness bunları sonraki user turn'ü olarak geri besler. + +## Harness başına tablo + +"Text field" Failproof AI'ın harness başına normalizasyonundan sonra stdin payload alanıdır. "Recorded" prompt'un insanın isteği olarak tutulup tutulmadığını söyler. + +| Harness | `--cli` | Prompt event → canonical | Text field | Recorded | Agent'in son mesajı okunacak yer | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Evet, payload'ın `source`'u kimsenin göndermedği bir turn adlandırmadığı sürece (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, bilinmeyen değer ve kaynak göndermemeyen build hepsi kaydedilir | session transkrip (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Evet | rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Evet | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Evet, tüm prompt olduğunda `` wrapper sıyrılarak | agent transkrip JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | Evet — ama mevcut OpenCode bu event'de metin taşımadığı için uygulamada hiçbir şey kaydedilmez; aynı mesaj bir kere kaydedilir | yok (sessions SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Evet, `input_source` `extension` olmadığı sürece — başka extension'ın `sendUserMessage()`, metni model-yazılı veya repo-türetilmiş olabilir | Pi session JSONL | +| Hermes | `hermes` | yok | — | Hayır — Hermes'in prompt-submit event'i yok | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Evet, run metadata run'ı machine'in olarak işaretlemediği sürece: `user` dışında `trigger`, `external_user` dışında `inputProvenance.kind`, veya `senderIsOwner: false` | yok (`before_agent_run` transkrip yolu taşımaz) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Evet | droid session JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Evet | yok (sessions SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | yok | Hayır — `PreInvocation` bir turn'deki her model çağrısından önce tetiklenir ve prompt metin taşımaz | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Evet | yok (sessions SQLite) | + +İki harness hiçbir şey kaydı etmez ve her iki durumda da aynı nedenle: event'leri insan metni sunmaz. Hermes'in prompt-submit event'i yok — kendi native plugin'i `pre_llm_call`'ı kendisi ele alır ve sadece tool, session ve subagent event'lerini iletir. Antigravity'nin `PreInvocation` bir human turn'de ve sonrasındaki beşinde her model çağrısından önce tetiklenir ve prompt alanı taşımaz; hook'lar aynı conversation'a `userMessage` adımları da enjekte edebilir. Her iki event'te de kaydedecek hiçbir şey yok. + +## Bir prompt'u insanın yapan nedir + +1. **Event.** Failproof AI harness'in prompt-submit event'i için çağrıldı, handler bunu `UserPromptSubmit`'e kanonikleştirir. +2. **Payload.** Harness bunu hook'ın stdin'ine yazar ve yukarıda adlandırılan alanda metni taşır. Payload olmadan Failproof AI'a ulaşan çağrı hiçbir şey kaydetmez. +3. **Payload'daki hiçbir şey turn'ü dışarı atmaz.** Sub-agent adlandıran payload (`agent_id`) agent'in kendisini prompt'uyor. `source`, `input_source` veya OpenClaw run marker'ı machine-submitted turn adlandıran bir şey reddedilir. **Absent** bir marker hiçbir şeyi dışarı atmaz — bu hiçbir şey kaydetmeyen versiyon'dan fark, her marker burada her shipping build'de absent'tir. +4. **Sarma sıyrıldıktan sonra bir şey kalır** (aşağıya bakın). + +**Session transkrip prompt'u kimin yazdığının kanıtı değildir.** Bu sayfanın eski versiyonları transkript cross-check'ini açıklamıştı: eğer transkript model'ın onu programladığını gösterirse prompt reddedilir ve transkript önceki prompt'un gördüğünü devam ettirmek zorundaydı. Bu kontrol gitmiş. Transkript hala bir şey için okunur: **agent'in son görünür mesajı**. Bu mesaj tanım gereği agent-yazılıdır, Jev buna söylenir ve kendi başına asla rıza değildir. + +## Bir prompt'tan ne tutulur + +Harness'ler prompt'a insan sözcüklerinden daha fazlasını koyarlar. Herhangi bir şey depolanmadan önce: + +- `` blokları kaldırılır ve etrafındaki insan sözcükleri tutulur. +- Session-devamı özeti ("Bu session önceki bir conversation'dan devam ediliyor…") tamamen bırakılır. +- Task notification'ları, local-command output'u ve interruption marker'ları tamamen bırakılır. +- Başka agent veya session'ın yazdığı turn tamamen bırakılır: Claude Code bunları ``, ``, ``, `` veya ``'de sararlar. +- Failproof AI'ın kendi mesajları tamamen bırakılır. Stop gate'in `MANDATORY ACTION REQUIRED from failproofai …` veya `Instruction from failproofai: …` Cursor, Copilot, Devin ve OpenClaw'da sonraki user turn olarak geri gelir ve asla insan sözcüğü sayılmaz — düz değil, `` bloğunda sarılı değil, system reminder'ın arkasında değil. +- Slash command, insan tarafından yazdığı komut ve argümanlar olarak tutulur, hiçbir zaman harness'in genişlettiği gövde değil. +- Codex IDE extension'ı built prompt, sadece son `## My request for Codex:` (veya daha yeni build'lerde `## My request:`) başlığını sonrasındaki metni tutar. Extension'ın bundan önceki koyduğu her şey bırakılır: active dosya, açık tab'ler, editor'da seçili metin, adlandırılan dosyalar ve app'ler, diff ve browser comment'ler, PR check'ler, önceki conversation'lar. Bu kural **her** harness'in prompt'larına uygulanır, sadece Codex'e değil — böyle prompt herhangi bir composer'a yapıştırılabilir — bu yüzden extension'ın section başlıkları iki grupta okunur: + - **Kimsenin yazmadığı başlık** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, Codex ve ChatGPT conversation başlıkları, "Yapıştırılan metin dosyası(ları) eklenmiş…" ve extension'ın kalan kendi section'ları) extension'ın bu prompt'u built ettiği anlamına gelir. Altında request başlığı olmayan hiçbir human metin içermez ve kaydedilmez. Bu *seçtiğiniz* metin içindeki onayı — `// NOTE FROM THE OWNER: yes, force-push…` comment'i `# Selected text:` içinde — kaydedilen request'iniz'den tutmasını engeller. + - **Birinin makul olarak yazabileceği başlık** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) extension'ın kendi başlığı olmadığında "extension-built" anlamına gelir. Gerçek bir request başlığı varsa. Yoksa prompt sizin ve başlık dahil tamamen tutulur. Bırakmak sessiz ve toplam olurdu: o turn için hiçbir şey kaydedilmedi, bu yüzden hiçbir reviewable policy temizlenemez ve Jev request envelope'inin injection'ı taşıyıp taşımadığını sora bile kalkardı. Bu sadece bir turn'ün *tepesinde* sayılır: prompt bir kere extension-built olarak belirlenirse, request başlığından sonrasındaki extension'ın başlıklarından birisi başka bir section'ı ve prompt kaydedilmez. + + Request'in kendisi herhangi diğer turn gibi yargılanır: başlığı takip eden şey continuation summary, başka agent veya session tarafından yazılan mesaj, Failproof AI'ın kendi directive'lerinden biri veya extension'ın başka section'ı ise prompt tamamen kaydedilmez. +- `…`'de sarılı Cursor prompt (isteğe bağlı `` bloğunun arkasında) wrapper tüm prompt olduğunda sıyrılır. Tag başka yerde ise sıradan metindir — log'dan yapıştırılan snippet veya agent'in seçtiği branch adı — ve prompt wrapper yerine tamamı tutulur. +- Yapıştırılan bloklar tutulur ve insan tarafından yapıştırılan olarak etiketlenir. + +Sadece harness metni olan prompt hiç kaydedilmez. + +## Agent'in son mesajı + +"Evet" gibi cevap, cevapladığı soru olmadan hiçbir anlam taşımaz. Prompt kaydedildiğinde Failproof AI, aynı anda session transkrip'ten agent'in son görünür mesajını okur ve prompt ile depolar. Jev kendi alanında alır, agent tarafından yazıldığı olarak etiketlenir: kısa cevabı açıklar ve asla kendi başına insan request'i sayılmaz. Bu transkript'in okunduğu tek şeydir ve yeniden yazılan transkript'in yapabileceği en kötü şey agent'in yazdığı mesajı agent'in yazdığı mesajın beklendiği yere koymaktır. + +Transkript'in sonundan okunur, en fazla son 4 MB. Desteklenen transkript formatları Claude Code, Codex rollout'ları (eski `agent_message` event'leri ve daha yeni `AgentMessage` öğeleri), Cursor, Copilot `events.jsonl` ve Pi, Factory ve OpenClaw session JSONL'dir. Claude Code'ın kendi sentetik ve API-error mesajları ve subagent (sidechain) mesajları atlanır. Goose ve OpenCode için SQLite'da session'ları, Devin için tek JSON dokuman transkript'i veya OpenClaw için `before_agent_run` event'i transkript yolu taşımaması snapshot yok. + +## Depolama + +| Özellik | Değer | +| --- | --- | +| Konum | `~/.failproofai/state/semantic/sessions//.json`, burada `` prompt'un yazıldığı agent profil'idir: FailproofAI'ın bildiği agent için `.` (Cloud policy'lerin hedeflediği kimlik) veya aksi takdirde sadece `` | +| İzinler | file `0600`, directory `0700`. Onun üstündeki her dizin, `~/.failproofai`'ye kadar `jev.json`'ın dizini tuttuğu kurala tutulur: başkası **write** yapabileceği bir taraf adlandırılıp değiştirilebilir ve değiştirilebilir, bu yüzden read path yazma bitleri alabileceği yerlerde çıkarır ve çıkaramadığı yerde **hiçbir şey** okumaz. Kaydedilen prompt bu durumda sahte yerine absent'tır ve hiçbir şey temizlenmez | +| Session başına tutulur | son 5 prompt; öncekisiyle aynı prompt yerine yeni slot almaktansa yer alır | +| Window | 6 saatten eski prompt'lar görmezden gelinir | +| Boyut | her prompt ve agent mesaj başı ve kuyruğu tutarak 6,000 karaktere sınırlıdır | +| Sırlar | herhangi yazılmadan önce `sanitize-*` policy'leriyle aynı pattern'lerle redakte edilir. 48,000 karakterden daha uzun metin ilk 28,800 ve son 19,200 karakteri olarak redakte edilir ve bu kesiklerin yanındaki metin, bir sır bölünmüş olabilir, asla tutulmaz | + +Harfler, digits, `.`, `_` ve `-` dışında herhangi şey içeren veya 128 karakterden uzun session ID, dosya adı olarak hiçbir zaman kullanılmaz, bu yüzden hiçbir şey kaydedilmez. + +Session dosyası sadece bir prompt kaydedildikten sonra var olur. Prompt'lar ve başka bir şey tutar — origin state yok, transkript mark yok — ve 6 saatlik window'dan daha uzun sessiz kaldıktan sonra silinir, sonraki sefer yeni session'un ilk prompt'unu yazınca. + +Prompt sadece kaydedildiği aynı agent profil ve session ID'si için geri okunur. Session ID'leri agent'den gelir, bu yüzden iki profil aynı kullanabilir; profile'a göre key, bir profile'ın sözcüklerinin başka bir profile'ın request'i sayılmasını engeller. Eski layout'tan dosyalar (`sessions/.json`) hangi profile'ın yazdığını söyleyemez, bu yüzden hiçbir zaman okunmazlar ve 6 saatlik window'la expire olurlar. + +Jev endpoint'i konfigüre edilmediği sürece hiçbir şey kaydedilmez. FailproofAI Cloud Jev mode'unda, hiçbir Cloud Jev check'i atanmamış ve installed pack'in check'i review'lamayan agent profil için hiçbir şey kaydedilmez. + +### Project kökü + +"Proje içi" — `read-outside-workspace` ve diğer path kontrol'ler tarafından değerlendirilen — session'un ilk reviewed çağrısında olduğu proje içi anlamına gelir. Kök o zaman fix'lenir ve daha sonraki `cd` asla hareket ettirmez; `cd` hala relative path'in nasıl çözüldüğünü değiştirir. Bunu `cd`'yi takip ettirilerse bir çağrıda `cd ~/.ssh` sonrakini `~/.ssh` project'ı yapabilir. + +Pin `~/.failproofai/state/semantic/roots/.json` dir, `{root, at}` tutar: file `0600`, directory `0700` ve yukarıdaki aynı session-ID kuralı. Yeni session kökünü pin'lediyse 7 günden eski dosyalar silinir. Diğer users tarafından write yapılabileceğini `roots` dizin ignore edilir ve live dizin root'u kullanılır. Session'u tekrar pin'lemek için dosyasını silin. + +## Bilinen limitler + +- **Prompt'un güvenilirliği hook çağrısı kadar güvenilir.** Buradaki her şey harness'in hook'ın stdin'ine yazdığı payload'ı okur. Komut çalıştırabilen agent headless harness'i çalıştırabilir (`claude -p` ve yukarıda listelenen yedi tane) veya Failproof AI'ın kendi hook binary'sini yazdığı payload ile çalıştırabilir ve kimsenin yazmadığı prompt kaydedebilir. Bu başında açıklanan kabul edilen takas: sadece reviewable policy'leri temizler, asla hard bir tane değil — ama on beş reviewable built-in'den on ikisi deny'dir, bu yüzden sahte prompt real bloğu bu on ikisinde allow'a dönüştürebilir. +- **Sub-agent detection Claude-şekilli.** `agent_id` taşıyan payload, herhangi harness'te asla kaydedilmez. Bu Claude Code, Factory Droid ve Devin'in kullanacağı alandır. Codex sub-agent thread'lerinde prompt event'ini tetikler, Copilot process-içi sidekick'leri çalıştırır, Goose bir `delegate` tool'ü vardır ve OpenClaw personas çalıştırır — hiçbiri payload'ı bunu tanıdığı bir şekilde işaretlemez, bu yüzden bu harness'lerde sub-agent prompt session'un kendi olarak kaydedilir. OpenClaw'ın `openclaw.agentId` **bu değil**: shipped plugin her run'da bunu ayarlar, owner'ın dahil. +- **Marker taşımayan Scheduler'lar.** Claude Code'ın `schedule_wakeup` ve `loop_wakeup` ve OpenClaw'ın `cron` ve `heartbeat` trigger'ları reddedilir çünkü bu harness'ler payload'da bunu söyler. Goose'un kendi scheduler'ı (`goose schedule add`) ve Codex'in `codex exec` hiçbir şey söylemez, bu yüzden başlattıkları run diğeri gibi kaydedilir. +- **Agent'in son mesajı agent'in seçtiği mesaj olabilir.** Transkript authenticate edilmez, bu yüzden kendi transkript'ini yazan agent "son mesaj"ının ne söylediğine karar verebilir. Agent-yazılı etiketlenmiş ve kendi başına hiçbir şeyi temizlemez — ama `decide.ts`'nin v1 path'i belirleyici "user bu target'ı adlandırdı mı" kontrol'ünü tatmin etmesine izin verdiğini not edin, bu yüzden transkript'ini kontrol eden agent override'ın gereksinim duyduğu target adını besleyebilir. +- **Extension'ın machine başlığıyla açılan prompt tamamen bırakılır.** Prompt'u `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` veya yukarıdan ilk gruptan başka section başlığıyla başlat ve `## My request:` başlığı asla yazma ve o turn için hiçbir şey kaydedilmez — bu yüzden onun için hiçbir şey temizlenmez. Bu kasıtlı: bu section'lar başka birisi kontrol ettiği metni taşır (seçtiğiniz kod, reviewer'ın diff comment'i, page başlığı) ve bunu sözcükleriniz olarak kaydetmek daha kötü başarısızdır. Developer'ın makul olarak yazdığı başlıklar ikinci grupta ve kendi kendine asla prompt'u bırakmaz. +- **OpenCode uygulamada hiçbir şey kaydetmez.** `message.updated` event'i mevcut OpenCode'da metin taşımaz ve aynı zamanda task tool'ünün yarattığı child session'lar için tetiklenir, kimin yazıyla "user" mesajı parent agent yazmıştır. +- **`CODEX_HOME` honoured değildir** `lib/codex-sessions.ts`'deki rollout discovery tarafından. Bu sadece agent-message snapshot'u aradığı yeri etkiler, asla prompt kaydedilip kaydedilmediğini değil. \ No newline at end of file diff --git a/docs/tr/reference/jev-providers.mdx b/docs/tr/reference/jev-providers.mdx new file mode 100644 index 000000000..1847a312b --- /dev/null +++ b/docs/tr/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev sağlayıcılar ve kendi anahtar kurulumu" +description: "Sağlayıcı uç noktaları, model kimlikleri, yapılandırma ve kendi anahtarınızla canlı Jev politika incelemesi için başarısızlık davranışı." +icon: "key-round" +--- + +Bu, kendi anahtarınızla [Jev politikaları](/tr/policies/jev) için sağlayıcı ve yapılandırma referansıdır. Regex politikaları dizeleri eşleştirir. `rm -rf build/` komutunun sizin istediğiniz versiyon ile `rm -rf ~` komutunun bir plana sızması arasındaki farkı anlayamazlar, bu nedenle bir yerde çok fazla bloklarlar, başka bir yerde çok az. **Jev**, TypeSafe'in sınıflandırıcısı, çağrıyı gerçekten istediğiniz şeye karşı okur ve bir hızlı istekte bununla ilgili bir dizi evet/hayır sorusuna cevap verir. + +Kendi Jev uç noktanız ve anahtarınız yapılandırılmışsa, Failproof AI, regex politikalarının **yerine değil** yanında her araç çağrısı hakkında Jev'e sorar: + +- Bir **sert** politikanın reddi kesindir. Jev bunu iptal edemez. Her politika, açıkça gözden geçirilebilir olarak işaretlenmediği ve Jev kontrollerini adlandırmadığı sürece serttir; bu nedenle hiçbir şey söylemeyen özel, paket veya Bulut politikası serttir ve her zaman açık olan kendi kendini koruma gardı her zaman serttir. +- Bir **gözden geçirilebilir** politikanın reddi iptal edilebilir, ancak yalnızca Jev'e politikanın kapsadığı tam sorun hakkında sorulduğunda ve "burada bir şey yok" veya "kullanıcı bunu istedi" cevabını verdiğinde. Sorunu gerçek bulan bir kontrol, kullanıcı çağrıyı istemediğinde reddi tutar — kendi kararı yalnızca bir uyarı olsa bile, çünkü bir araç çağrısından önce bir uyarı acenteyi durdurmaz. Ve bu kontrol, reddedebilen bir tane ise (gizli dışa açılma, kimlik bilgisi dışa aktarma, yıkıcı silme, …), o çağrıda hiçbir şey iptal edilmez. +- Bir blok, çağrı verdiğiniz görevin bir adımı olduğunda ve daha ileri gitmediğinde yine de bir **uyarıya** dönüşebilir: Jev kendi reddini uyarıya yumuşatır ve bu uyarı — çağrıda gerçekte neyin yanlış olduğunu adlandırır — politikanın bloğunun yerini alır. +- Jev ayrıca regex'in tanımladığı zarar için kendi başına uyarabileceği veya reddedebileceği. +- Jev cevap veremezse (zaman aşımı, oran sınırı, sunucu hatası, kredi yok, beklenmedik bir model versiyonu), o çağrı regex sonucunu alır, tam olarak Jev olmaksızın. +- Jev, politikalarınız tarafından yalnız bir çağrıyı daha izin verici hale getirmez; bütün çağrıyı okumuş ve tam sorunu sormuş olmalıdır. Bundan daha az — çok büyük bir çağrı, şüpheli bir enjeksiyon — onayları geri çeker ve her reddi tutar. + + +Jev yapılandırması olmadan hiçbir şey değişmez: kancaları tam olarak her zaman olduğu gibi regex politikalarını çalıştırır. Yapılandırma tamamiyle katılım (opt-in). + + + +FailproofAI Cloud'ta mısınız? Kendi anahtarınıza gerek yok: `jev:evaluate` taşıyan bir anahtarla bağlanan makine, kuruluşunuzun planında Jev kullanabilir. Bkz. [FailproofAI Cloud aracılığıyla Jev](/tr/reference/jev-cloud). + + +## Başlamadan önce + +**failproofai 1.0.8-beta.0 veya daha yeni sürümü** kurun ve kancalarını aracınızın çalıştığı makinedeki bir [desteklenen koşuma takısı](/tr/reference/harnesses) öğesine takın. Bu yeni bir makineyse [hızlı başlangıcı](/tr/start/quickstart) izleyin veya Cloud kullanmıyorsanız [yerel uygulama ayarı](/tr/start/setup#enforce-locally) yapın. Yüklü CLI'yi `failproofai --version` ile kontrol edin. + +Aşağıdaki bir sağlayıcıdan API anahtarı alın veya uyumlu bir uç noktası ve anahtarı hazır bulundurun. Jev, `PreToolUse` veya `PermissionRequest` kapısında adlandırılmış araç çağrılarını gözden geçirir. Kendi kararı verebilir, ancak mevcut politika reddini iptal etmek de [gözden geçirilebilir](/tr/policies/authority) olarak işaretlenen bir politikanın kurulu olmasını gerektirir. Sert politika reddetmeleri kesindir. + +## Bir sağlayıcı seçin + +Jev beş rota aracılığıyla erişilebilir. Bunlardan herhangi biri için bir anahtar getirin. + +| Sağlayıcı | `--provider` | Uç Nokta | Varsayılan Model | Notlar | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Tam sürüm sabitleme. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | İstekler yalnızca sıfır veri saklama uç noktalarına yönlendirilir, başka bir sağlayıcıya geri dönüş yoktur. `typesafe/jev-1.13-20260917` gibi tarihli bir sürüm bildirir. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Jev'i yalnızca bir takma ad ile adlandırır, bu nedenle cevaplayan sürüm doğrulanmamış olarak kaydedilir. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | `--account-id` gerektirir. HTTP 429'den önce saniyede altı çağrı ölçüldü. | +| Kendi uç noktanız | `custom` | `/systemone` | `jev-1.13.0` | TypeSafe'in istek gövdesini kabul eden ve hangi modelin cevap verdiğini bildiren herhangi bir uç nokta. Yalnızca `https`; yerel test için bir loopback ana bilgisayarına (`localhost`, `127.0.0.1`, `::1`) düz `http` kabul edilir. | + + +Vercel'in kendi getir-kendi-anahtarı özelliğinde, başarısız bir istek Vercel'in kimlik bilgileriyle sessizce yeniden denenir. Her çağrının yalnızca kendi TypeSafe hesabınıza faturalandırılmasını ve görülmesini istiyorsanız, TypeSafe'i doğrudan kullanın. + + +## Kurulumu yapın + +Bir komut, uç nokta ve anahtar. Mevcut politikalar çağrıları kararlaştırırken Jev'in kararlarını inceleyebilmeniz için `observe` modunda başlayın: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### URL sağlayıcıyı seçer + +Sağlayıcıyı adlandırmanız gerekmez: URL'nin **ana bilgisayarı** hangisi olduğudur. + +| URL Ana Bilgisayarı | Sağlayıcı | Ayrıca Gerekir | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| herhangi bir başka ana bilgisayar | `custom` | — verdiğiniz URL temel URL'dir | + +Bundan üç şey sonuç çıkar: + +- **Sağlayıcının kendi API'sine işaret eden bir URL geçersiz kılma yazmaz.** `--url https://api.typesafe.ai/v1` tam olarak `--provider typesafe` yapacağı yapılandırmayı üretir. Bilinen bir sağlayıcıda farklı bir yol veya ana bilgisayar verin ve temel URL olarak saklanır, `--base-url` olarak saklanır. +- **`--provider` yine de çıkarımı geçersiz kılar**, bu da kendi ana bilgisayarınızdan bir sağlayıcının API'sini konuşan bir proxy'ye ulaşmak için kullanılan şekilde: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Konak ile çelişen bir `--provider` reddedilir**, tahmin edilmez. `--provider openrouter --url https://api.typesafe.ai/v1` hiçbir şey yazmaz ve nedenini söyler: iki yazım, anahtarınızın nereye gönderileceği konusunda anlaşmıyorlar. Aynı çift `jev setup --base-url` ve panodan Jev ayarlarından reddedilir. (`--provider custom` bir çelişki değildir — "bu URL'yi kendisi olarak davran" anlamına gelir — Cloudflare'in ana bilgisayarı hariç, bunun hesap başına uç noktasına özel bir rota ulaşamaz.) + +`--url` tam olarak yapılandırma dosyasındaki `baseUrl` gibi doğrulanır ve aynı sözcüklerle reddedilir: `https` veya yerel test modunda bir loopback ana bilgisayarına (`localhost`, `127.0.0.1`, `::1`) düz `http`. Risk: loopback sunucusunu hiçbir şey doğrulamaz, bu nedenle inişi sırasında makinedeki başka bir yerel işlem bağlantı noktasını alabilir ve cevap verebilir; yerel test dışında `https` kullanın. + +### Anahtar + +`--key-stdin` ile aktarın veya komutu bir terminalinde olmaksızın çalıştırın ve anahtarı maskelenen bir istemde yapıştırın. Her iki şekilde de doğrudan yapılandırma dosyasına girer ve hiçbir zaman geri yazdırılmaz. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup`, aynı bayrakları alır ve hepsinin uzun yazımıdır: `setup --provider ` sağlayıcıyı URL'den ziyade adlandırmayı tercih ettiğinizde. + +### `--token` ve maliyet nedir + +`--token ` anahtarı komut satırına koymak, bir makineyi yapılandırmanın en hızlı yoludur ve anahtarın yapılandırma dosyası dışında herhangi bir yerde kalmasını bırakan tek yazımıdır: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Komut satırı bağımsız değişkeni daha sonra kabuğunuzun geçmiş dosyasında bulunur ve komut çalışırken işlem listesinde bulunur — sizin çalıştırdığınız her şey tarafından `/proc` öğesinden okunabilir. `setup` her zaman `--token` kullanıldığında bunu söyler. Paylaştığınız bir makinede, kaydedilen bir oturumda veya geçmiş dosyası senkronize olan herhangi bir yerde `--key-stdin` tercih edin; bu şekilde geçen bir anahtarı önemliyse döndürün. + + +`--token`, `--key-stdin` ve `--key-from-env` birbirini dışlar: biriyle verin. + +Ardından anahtarı, uç noktayı ve hangi Jev'in cevap verdiğini kontrol etmek için küçük bir canlı istek gönderin: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test`, cevap zaman aşımından sonra geldiğinde (her kanca regex'e `timeout` olarak dönerdi) veya kontrol sorusuna yanlış cevap verdiğinde çıkış 1'i kullanır ve başlığında bunu söyler. + +Kancaları her araç çağrısında yapılandırmayı okur, bu nedenle sonraki çağrıdan uygulanır. Daemon ile veya daemon olmaksızın yeniden başlatılacak hiçbir şey yoktur. + +## Ne yaptığını kontrol edin + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status`, sağlayıcı, uç nokta, model, mod, yapılandırma dosyası ve izinlerini gösterir, hiçbir zaman anahtarı göstermez. Bunu takiben yakın zamanda yapılan etkinliği özetler: Jev kaç çağrı değerlendirdi, kaç kez regex'e döndü ve neden, gecikme süresi ve gözden geçirilebilir politikaları iptal etti. + +## Gerçek bir çağrıyı doğrulayın + +Kancalı acentede yeni bir oturum başlatın. Dosya okuma aracını `README.md` üzerinde kullanması ve başlığı bildirmesi isteyebileceksiniz. Oturumun o araç çağrısını içerdiğini doğrulayın, ardından `failproofai jev status` öğesini tekrar çalıştırın: yakın zamanda değerlendirilen çağrı sayısı artmalıdır. [Yerel panoda](/tr/reference/local-dashboard#review-policy-activity) **Politikalar → Etkinlik** açın ve çağrının Jev kararını ve modunu inceleyin. Gözlemci modunda, politika sonucu yine de çağrıya karar verir. Gözden geçirilebilir politika eşleştiği ve Jev adlı her kontrolü iptal ettiğinde yalnızca bir onay görülür; sıradan okuma, iptal etmek için bir politikası olmayabilir. + +## Gözlemci modu + +`enforce` varsayılandır. Jev'i hiçbir kararı değiştirmesine izin vermeden izlemek için `observe`'e geçin: Jev yine de sorulur ve kararları kaydedilir, ancak regex sonucu uygulanan şeydir. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off`, yapılandırmayı tutar — uç noktayı ve anahtarı — ve Jev'i sorgulamayı durdurur: kancaları bir yapılandırma olmaksızın exact regex politikalarını çalıştırır ve `failproofai jev status` "off (switched off)" sayılır. `--mode observe` veya `--mode enforce` ile geri dönün. + +Aynı sağlayıcı için `setup` öğesini yeniden çalıştırmak depolanan anahtarı tutar, bu nedenle bir mod anahtarı tek bir bayraktır. Sağlayıcıyı değiştirmek baştan başlar ve bu sağlayıcının anahtarını ister. Farklı bir ana bilgisayarına istekleri taşıyan bir `--base-url` da yapabilir: depolanan anahtar yalnızca verdiği ana bilgisayara veya sağlayıcının kendi API'sine gönderilir. + +## Yapılandırma dosyası + +Her şey `~/.failproofai/jev.json` bir dosyada yaşar, `setup` tarafından yazılır: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Alan | Anlam | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` veya `custom` — veya `failproofai`, bunun anahtarı bu dosya yerine FailproofAI Cloud bağlantısından gelir (bkz. [FailproofAI Cloud aracılığıyla Jev](/tr/reference/jev-cloud)). | +| `apiKey` | `Authorization: Bearer ` olarak gönderilir. | +| `baseUrl` | `custom` için gerekli; aksi takdirde sağlayıcının API tabanı yerine. `https` olmalıdır. `localhost`'a düz `http` yalnızca `mode: observe` ile kabul edilir: loopback sunucusunu hiçbir şey doğrulamaz, bu nedenle proxy'niz inişte başka bir yerel işlem, ajanı da dahil olmak üzere, yerine cevap verebilir. | +| `accountId` | Yalnızca Cloudflare: 32 küçük heksadesimal karakter. | +| `model` | Sağlayıcının varsayılan model kimliğinin yerini alır. Sürümlü kimlik, Jev 1.13'i adlandırmalıdır. API anahtarı gibi görünen bir değer reddedilir (ve geri tekrarlanmaz), bu nedenle `--model` içine yapıştırılan bir anahtar hiçbir zaman model olarak depolanmaz veya gönderilmez. | +| `timeoutMs` | Bir araç çağrısının Jev'i beklemesi ve regex sonucunu kullanması ne kadar süre. 100–10000, varsayılan 3000. | +| `mode` | `enforce` (varsayılan), `observe` veya `off` (yapılandırmayı tutun, Jev çalıştırmayın). | + +Üç kural onu korur: + +- **Yalnızca sahip.** `0600` izinleriyle yazılır. Başka bir kullanıcı veya grup tarafından okunabilecek veya yazılabilecek bir kopya **reddedilir** ve kancaları `chmod 600 ~/.failproofai/jev.json` veya `setup` öğesini yeniden çalıştırana kadar regex'e dönerler. Dizin de denetlenir: `~/.failproofai`, başka kimse tarafından **yazılabilir** olmamalıdır, çünkü oraya yazabilen kişi, dosyanın kendi izinleri ne olursa olsun, dosyayı değiştirebilir. `setup`, bulduğu yazma bitlerini kapatır. `failproofai jev status`, yapılandırma reddedildiğinde söyler ve dosyanın adlandırdığı uç noktayı gösterir: başka biri bunu değiştirebilir, bu nedenle `chmod` yapmadan önce sizin olduğunu kontrol edin. Böyle bir dosya üzerinde `setup` öğesini yeniden çalıştırmak depolanan anahtarı yalnızca sağlayıcının kendi API'sine taşır; adlandırdığı başka herhangi bir uç nokta anahtarı (`--key-stdin`) veya temel URL'yi sağlayıcıya geri göndermek için `--base-url default` gerektirir. +- **Yalnızca küresel.** Bir depo Jev'i açamaz, başka bir uç noktaya işaret edemez veya modelini seçemez: proje içindeki `.failproofai/jev.json` yoksayılır ve sağlayıcı, URL, model ve hesap kimliği yalnızca o dosyadan okunur — hiçbir zaman ortamdan, hangi depo ajanı ayarları ayarlayabilir. (`FAILPROOFAI_HOME` bunu çevirmek için yol değildir: failproofai'nin bütün dizinini, politikalarınız dahil olmak üzere taşır, Jev'i tek başına yönlendirmek yerine.) +- **Yalnızca anahtar ortamdan gelebilir.** Dosyada `apiKey` yoksa, `FAILPROOFAI_JEV_API_KEY` o oturum için bunu sağlar (`setup --key-from-env` böyle bir dosya yazar). Dosya tarafından tutulan anahtarı hiçbir zaman değiştiremez ve anahtarsız Jev'i açamaz. Değişken ayarlanmadığında, Jev o kabuk için basitçe kapalıdır: `failproofai jev status` bunu söyler, 0 çıkış verir ve yapılandırmayı bırakır (`status --json`, `"key-missing"` nedeniyle `"status": "key-missing"` rapor eder). `failproofaid` daemon, kabuğunuzun ortamını görmez, bu nedenle `failproofai config` ile ayarlanmış bir makinede, anahtarı dosyada tutun. + +## Hangi Jev cevap verir + +Failproof AI'nin karar eşikleri Jev 1.13'te kalibre edildi, bu nedenle cevap yalnızca bu aileden geldiğinde kullanılır: `jev-1.13.x` veya OpenRouter'ın `typesafe/jev-1.13-`. Bir sağlayıcı Jev'i yalnızca takma ad ile adlandırdığında ve sürüm bildiremediğinde (Vercel ve Cloudflare'de olmadığında), cevap kullanılır ve doğrulanmamış olarak kaydedilir. Özel `--model` adı tarafından yapılandırılan `custom` uç noktası model raporu vermelidir, cevap aynı şekilde doğrulanmamış olarak kaydedilir. 1.13 dışında bir sürüm raporlayan veya hiç raporlamayan bir `custom` cevap kullanılmaz: o çağrı `model-mismatch` nedeniyle regex'e geri döner. + +## Jev cevap veremediğinde + +Bunlardan her biri o çağrı için regex sonucuna geri döner ve neden ile kaydedilir, `failproofai jev status` toplamlar: + +| Neden | Sebep | +| --- | --- | +| `timeout` | `timeoutMs` içinde cevap yok. | +| `http-429` | Sağlayıcı anahtarı oran sınırlandırdı. | +| `rate-limited` | Failproof AI'nin kendi sınırlayıcısı çağrıyı göndermeden önce tuttu: 5 istek saniye, 5'e kadar patlamalar ve sağlayıcı `429` cevap verdikten sonra bir anlık hiçbir şey. Sağlayıcı değil. | +| `http-500`, `http-502`, `http-503`, … | Sağlayıcıda sunucu hatası. Tam durum kaydedilir. | +| `out-of-credits` | HTTP 402: sağlayıcı hesabının kredisi kalmadı. | +| `provider-refused` | Cloudflare'den HTTP 402 "Model execution failed (Payment error)" okuması: sağlayıcı bu istek üzerinde modeli çalıştırmayı reddetti. Genellikle faturalandırma değil, bu nedenle doldurma bunu hareket ettirmez. | +| `http-401`, `http-403` | Anahtar reddedildi. | +| `http-404` | `/systemone` adresinde hiçbir şey sunulmaz, bu nedenle temel URL yanlış — `/systemone` öğesine eklenir ve her sağlayıcı bunu sürüm kökünde sunar. `failproofai jev models`, uç noktanın sunduğunu gösterir. | +| `network` | Uç noktaya ulaşılamadı. | +| `http-301`, `http-302`, `http-307`, `http-308` | Uç nokta yeniden yönlendir ile cevap verdi. Yönlendirmeler hiçbir zaman takip edilmez, bu nedenle cevap yalnızca yapılandırmanızdaki URL'den gelir; son URL'ye `--base-url` ayarlayın. | +| `malformed` | Uç nokta cevap verdi, ancak Jev cevabıyla değil — JSON olmayan bir gövde veya içinde cevap olmayan bir gövde. | +| `cloudflare-error`, `cloudflare-incomplete` | Cloudflare'nin zarfı başarısızlığı bildirdi veya tamamlanmayan bir iş. | +| `model-mismatch` | 1.13 dışında bir Jev sürümü cevap verdi veya `custom` uç noktası hangi modelin cevap verdiğini söylemedi. | +| `request-cut` | **Kesinti değil.** Jev cevap verdi; ona sadece çağrının bir kısmı gösterildi, bu nedenle cevabı hiçbir şey iptal etmedi. Bkz. [Jev cevap verdi, ancak tüm çağrıda değil](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` birkaç daha nadir neden de gösterebilir, örneğin `upstream-error` (cevap sağlayıcının kendi hatasını taşıdı) veya `config` ve adlandıramayacağı herhangi bir nedeni `other` olarak toplar. + +`request-cut`, `failproofai jev status` bunu geri kalanıyla topladığı için ve her reddi tutuğu için bu tablodadır. Burada sağlayıcınız hakkında hiçbir şey söylemeyen tek nedendir: istek ulaştı ve Jev cevap verdi. Yukarıdaki her satırın aksine, bu cevap yine de sayılır — Jev'in kendi reddi veya uyarısı, regex sonucunun yerine atılmak yerine bunun üstüne uygulanır. Bu yüzden bir koşu, çağrıların tüm kadar uç noktanız iyi olmayan değil, değerlendiriciye çok büyük çağrıya ulaştığı anlamına gelir ve kredileri doldurma veya URL'yi değiştirme sayıyı hareket ettirmez. + +## Jev cevap verdi, ancak tüm çağrıda değil + +İki şey daha olabilir ve ikisi de Jev'in cevap verememesi hakkında değildir. Her ikisi de ne kadar çağrı veya konuşmanın bir istekte sığdığıyla ilgilidir. + +**Çağrının kendisinin bir kısmı sığmadı.** Araç çağrısı sabit bütçe içinde gönderilir ve aşırı boyutlu bir — çok büyük bir `Write`, devasa MCP gövdesi, başlık kadar doldurulan komut — sığan şey ile gönderilir. Jev yine de cevap verir ve cevabı yine de sayılır: kendi reddi veya uyarısı zamanki gibi uygulanır. Yapamadığı şey **temizlemektir**, çünkü bir çağrının bir kısmında verilen karar o çağrıda bir karardır. Bu nedenle her politika reddi tutar ve çağrı `request-cut` nedeniyle geri dönüş olarak kaydedilir, `failproofai jev status` yukarıdaki nedenlerle birlikte toplar. Bu size verdiği kural: bir çağrıyı daha büyük yapmak temizliğini maliyetlendirebilir ve hiçbir zaman bir satın alamaz. + +**Bir mesaj sığmadı.** Yapıştırdığınız uzun istem, acentenin son mesajı veya bu değerlendiricinin kendi deposunun zaten kapladığı istem. **Hiçbir şey değişmez**: çağrı başka herhangi biri gibi yargılanır, temizlenir ve kaydedilir ve geri dönüş olarak sayılmaz. Yazdığınız metni yazma uzunluğu asla kararı belirlemez ve kesme rıza yaratamaz: istem zaten başlıkta geldiği yerlerde, "bunu istemedin" daha fazla onayının çekilmesinden ziyade hiç sonuç olmayan bir sonuç olmaktan çıkar. + +İkisi arasındaki çizgi metni kimin yazdığıdır. Çağrı acentenindir ve uzunluğunun şiddeti çıkarmasını yapan kural, acentenin kullanabileceği kuraldır; isteminiz sizin olup isteminizin uzunluğunu sinyal olarak ele almak hiçbir zaman ceza almış değildir ve spek veya yığın izi yapıştırmak. + +## Makineyi terk edenler + +Her Jev değerlendiren araç çağrısı için, bir istek sağlayıcınıza gider: + +- araç çağrısı kendisi, API anahtarları, taşıyıcı jetonları ve `KEY=` atamaları gibi sırlarla gizli edilir; +- yazdığınız yakın istemler, metni acentenin koşuma takısının kaldırıldığıyla; +- en son isteminizden önceki acentenin son mesajı, ajan tarafından yazılmış olarak etiketlenir; +- proje kökü (oturum ilk gözden geçirilen çağrısındakı, [oturum için sabitlenmiş](/tr/reference/jev-intent#the-project-root)) ve güncel git dalı gibi yerel olarak hesaplanan gerçekler. + +Yalnızca yapılandırmanızdaki uç noktaya, anahtarınızın altında gider. + +## Kapat + +```bash +failproofai jev remove +``` + +Bu, `~/.failproofai/jev.json` öğesini siler. Sonraki araç çağrısından itibaren, kancaları tam olarak önceki gibi regex politikalarını çalıştırır. `~/.failproofai/state/semantic/` altındaki oturum başına depolar (kaydedilen istemler `sessions/`, proje kökleri `roots/`) yerinde bırakılır ve süresi dolar. Jev'i sorgulamayı durdurmak ancak yapılandırmayı tutmak için bunun yerine `failproofai jev setup --mode off` kullanın. + +## Komut Referansı + +| Komut | Sonuç | +| --- | --- | +| `failproofai jev --url --key-stdin` | Bir komutla yapılandırın; sağlayıcı URL'nin ana bilgisayarından gelir | +| `failproofai jev --url --token ` | Aynı, komut satırında anahtar — geçmiş ve işlem listesi bunu görür | +| `failproofai jev setup --provider --key-stdin` | Stdin'e aktarılan anahtardan yapılandırmayı yazın | +| `failproofai jev setup --provider ` | Aynı, maskelenen isteme anahtarı isteyerek | +| `failproofai jev setup --key-from-env` | Anahtar depolamayın; `FAILPROOFAI_JEV_API_KEY` oturum başına okuyun | +| `failproofai jev setup --mode observe` | Modu (`enforce`, `observe` veya `off`) değiştirin, depolanan anahtarı tutarak | +| `failproofai jev setup --model ` / `--base-url ` | Modeli veya API tabanını geçersiz kılın; `default` geçersiz kılmayı temizler | +| `failproofai jev setup --timeout-ms ` | Çağrı başına bütçeyi değiştirin | +| `failproofai jev status [--json]` | Yapılandırma, izinler ve yakın zamanda yapılan etkinlik; hiçbir zaman anahtar | +| `failproofai jev test [--json]` | Bir canlı istek: gecikme ve cevap veren sürüm | +| `failproofai jev models [--provider ] [--url ] [--json]` | Uç noktanın `/models` bildirdiği model kimlikleri, yapılandırılmış olanı işaretler | +| `failproofai jev remove` | Yapılandırmayı sil; Jev kapalı | \ No newline at end of file diff --git a/docs/tr/reference/jev.mdx b/docs/tr/reference/jev.mdx new file mode 100644 index 000000000..febbb3356 --- /dev/null +++ b/docs/tr/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev entegrasyon referansı" +description: "Jev için konfigürasyon, sağlayıcılar, anahtarlar, istek verileri ve hata davranışı." +icon: "braces" +--- + +Jev, Failproof AI'de iki kullanım alanına sahiptir: + +| Kullanım | Çalışma zamanı | Dönen değer | Buradan başlayın | +| --- | --- | --- | --- | +| Oturum değerlendirmesi | Oturum tamamlandıktan sonra | Sabit cevaplı bir soru için puan | [Jev değerlendirmeleri](/tr/evaluations/jev) | +| Araç çağrısı politikası incelemesi | Korumalı bir araç çağrısı çalışmadan önce | Kurulu politikalarla birlikte sonuç | [Jev politikaları](/tr/policies/jev) | + +## Referans sayfaları + +| Konu | Ayrıntılar | +| --- | --- | +| [Değerlendirme soruları](/tr/reference/jev-evaluations) | Boolean ve sıralanmış-puan kriterleri, sonuçlar, limitler ve geriye dönük doldurma. | +| [Sağlayıcı karşılaştırması ve kendi anahtarını ayarlama](/tr/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare ve özel uç noktalar; URL çıkarımı, model kimlikleri, `jev.json`, modlar ve geri dönüş kodları. | +| [FailproofAI Cloud rotası](/tr/reference/jev-cloud) | Makine anahtarı izinleri, otomatik gözlem kurulumu, kullanım limitleri, bağlantı durumu ve veri işleme. | + +Yerel CLI komutları [Failproof AI CLI referansında](/tr/reference/failproof-cli) listelenmiştir. [Yerel pano referansı](/tr/reference/local-dashboard#set-up-jev), Jev ayarlarını ve aktivite görünümünü açıklamaktadır. \ No newline at end of file diff --git a/docs/tr/reference/mcp.mdx b/docs/tr/reference/mcp.mdx new file mode 100644 index 000000000..e1fa4f7ea --- /dev/null +++ b/docs/tr/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP sunucusu" +description: "Claude, Cursor, Codex veya başka bir MCP istemcisini Failproof AI Cloud'a bağlayın ve kendi izinlerinizi kullanın." +icon: "plug" +--- + +Bir AI aracını Failproof AI Cloud'a bağlayın ve aracılarınızın verilerine ondan erişin. Aracınız oturumları ve olayları sorgulayabilir, salt okunur SQL çalıştırabilir, panoları, uyarıları, sorunları, denetimleri ve ilkeleri okuyabilir ve izniniz varsa uyarı oluşturma veya ilke dağıtma gibi değişiklikler yapabilir. + +Her çağrı **kendi** izinlerinizle ve bağlanırken seçtiğiniz **tek bir** kuruluşta çalışır. + +Herkes için bir adres vardır, barındırılan veya kendi kendine barındırılan: + +```text +https://gateway.befailproof.ai/mcp +``` + +## İstemci bağlantısı + +Adresi istemcinize ekleyin. Bir araç ilk kez kullanıldığında, tarayıcınız açılır. Failproof AI Cloud'unuzun nerede olduğunu seçin, oturum açın, bir kuruluş seçin ve **Allow** (İzin Ver) düğmesini tıklayın. **Cancel** (İptal) hiçbir şeyi bağlamaz. + +Sayfa uygulamanın adını ve döndüğü yeri gösterir. Kendi web adresi tarafından tanımlanmayan bir uygulama **unverified app** (doğrulanmamış uygulama) olarak işaretlenir, bu nedenle bu işlemi kendi istemcinizden başlattıysanız devam edin. + + + + claude.ai veya Claude Desktop'ta **Settings → Connectors → Add custom connector** (Ayarlar → Bağlayıcılar → Özel bağlayıcı ekle) seçeneğine gidin. Adı `Failproof AI` olarak ayarlayın, adresi girin, **Add** (Ekle) ve ardından **Connect** (Bağlan) düğmesini tıklayın. + + Team ve Enterprise planlarında, bir sahip önce kuruluş için bağlayıcıyı ekler. Daha sonra her kişi kendi hesabını bağlar. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Ardından Claude Code içinde `/mcp` komutunu çalıştırın, `failproofai` seçeneğini seçin ve **Authenticate** (Kimlik doğrula) düğmesini tıklayın. + + + Bunu `~/.cursor/mcp.json` veya projenizin `.cursor/mcp.json` dosyasına ekleyin: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor sunucunun yanında **Needs login** (Oturum açması gerekiyor) yazısını gösterir. Oturum açmak için seçin. + + + Bunu `~/.codex/config.toml` dosyasına ekleyin: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Ardından `codex mcp login failproofai` komutunu çalıştırın. + + + OAuth ile Streamable HTTP üzerinden uzak MCP sunucularını destekleyen herhangi bir istemci çalışır. Yukarıdaki adresi verin. Yapılandırılacak istemci kimliği veya gizli anahtarı yoktur. + + + +## Bağlantı başına bir kuruluş + +Bir bağlantı yalnızca seçtiğiniz kuruluşta çalışır. İki kuruluş kullanmak için sunucuyu `failproofai-acme` ve `failproofai-sandbox` gibi farklı adlar altında iki kez ekleyin ve her birini kendi kuruluşuna bağlayın. + +Demo kuruluşları bağlantıları kabul etmez. Bunun yerine kendi kuruluşunuzu seçin. + +## İzinler + +Bir bağlantı, kuruluşta yapabileceklerinizi aşağıdaki küme içinde yapabilir. Mevcut izinlerinizi takip eder: yönetici size daha fazlasını verirse, araç bunu kazanır; alınırsa, araç bir sonraki çağrısında kaybeder. + +| İzin | Aracı şuna izin verir | +| --- | --- | +| `events:read` | Olayları listeleme, bir oturumun genel bakışını okuma, aracıları ve ortamları listeleme | +| `evaluations:read` | Oturumları listeleme, değerlendirme sonuçlarını ve işlerini okuma ve özetleme | +| `evaluations:trigger` | Değerlendirmeler oluşturma, yeni sürümleri yayımlama, açma/kapatma, geriye doldurma ve oturumu yeniden değerlendirme | +| `dashboards:read`, `dashboards:write` | Panoları okuma veya oluşturma, yeniden adlandırma ve sorgu ekleme | +| `queries:read`, `queries:write` | Kaydedilen sorguları okuma veya kaydetme ve düzenleme | +| `queries:run` | Bir salt okunur SQL sorgusu çalıştırma ve sorgu şemasını okuma | +| `alerts:read`, `alerts:write` | Uyarıları okuma veya oluşturma, düzenleme, duraklatma, silme ve test etme | +| `issues:read` | Sorunları okuma, onaylama ve yorum yapma | +| `issues:create` | Bir uyarıda sorun açma | +| `issues:close` | Sorunları çözme ve kapatma | +| `audits:read`, `audits:write` | Denetimleri, çalıştırmaları ve bulguları okuma veya denetimler oluşturma, düzenleme ve çalıştırma başlatma | +| `code_fixes:read` | Bir sorunu nasıl düzeltileceğini görme ve kendi aracının düzeltmesi için bağlamını alma | +| `code_fixes:write` | Failproof AI Cloud'da bir düzeltme başlatma; bu, GitHub'da bir pull request açar | +| `policies:read`, `policies:write` | İlkeleri, makineleri ve dağıtımları okuma veya ilkeleri yayımlama, dağıtma ve geri alma | + +Birkaç araç, kuruluş verilerine erişmediğinden hiçbir izin gerektirmez: oturum ve olay bağlantıları oluşturma ve bu belgeleri arama. + +Bir AI aracı asla API anahtarlarına, kullanıcılara, ayarlara veya kuruluş yönetimine dokunamamaz ve olayları gönderemez. + +## Değişiklikleri onaylama + +Yazma işlemleri, istemciniz istemi gösterebilirse önce sizi sorar. Ne değişeceğini görsünüz ve devam etmek için **Approve this change** (Bu değişikliği onayla) düğmesini seçersiniz. Reddederseniz veya yaklaşık 4 dakika içinde yanıt vermezseniz hiçbir şey değişmez. Bazı istemciler bir dakika sonra beklemeyi durdurur, bu yüzden hızlı yanıt verin. + + + İstemler desteklenmeyen bir istemci sorulmaz ve yazma işlemi istemci çağrıyı yapıp yapmadığında hemen çalışır. Burada, istemcinizin kendi onayı tek olandır, bu nedenle yazma araçları için onu açık tutun. + + +## Bağlı uygulamalar ve erişimi iptal etme + +**Settings → Integrations → MCP** (Ayarlar → Entegrasyonlar → MCP) mevcut kuruluştaki bağlı uygulamaları, izinlerini ve son kullanımını listeler. **Revoke** (İptal Et) bir uygulamayı anında keser. Sunucuyu istemcinizde kaldırmak da bağlantıyı iptal eder. + +Kuruluş başına 5'e kadar bağlı uygulama olabilir. Aynı uygulamayı yeniden bağlamak önceki bağlantısının yerini alır. + +## Kendi kendine barındırılan dağıtımlar + +Bağlanırken **Self-hosted Failproof AI Cloud** (Kendi kendine barındırılan Failproof AI Cloud) seçeneğini seçin ve oturum açtığınız adresi girin. Dağıtımınıza genel HTTPS üzerinden erişilebilir olmalıdır. + +Araç çağrıları ve sonuçları, AI aracınız ile dağıtımınız arasında ileri geri giderken barındırılan Failproof AI ağ geçidinden geçer. Ağ geçidi bunları depolamaz. + +## Verilerinize ne olur + +Sonuçlar bağladığınız AI aracına gider ve bu aracın sağlayıcısı bunları kendi şartları altında yönetir. Her araç çağrısı için Failproof AI, aracın adını, sonucunu, ne kadar sürdüğünü ve kuruluşu günlüğe kaydeder, hiçbir zaman argümanları veya sonuçları kaydeder. [Gizlilik politikasına](https://befailproof.ai/privacy/) bakın. + +## Sorun giderme + +| Gördüğünüz | Ne yapmalısınız | +| --- | --- | +| "Started in another browser" (Başka bir tarayıcıda başlatıldı) | İstemcinin açtığı tarayıcıda oturum açmayı tamamlayın, çerezlere izin verin ve istemciden tekrar başlayın | +| **Allow** (İzin Ver) sonrası hata | Bağlantı bir kez çalışır ve 10 dakika sonra süresi dolar, bu yüzden istemciden tekrar başlayın | +| Beklediğiniz bir araç eksik | Bu kuruluşta kendi izniniz yoktur. Bir yöneticiye sorun. Sahibi olduktan sonra yeniden bağlanmanıza gerek yok | +| İstemci size oturum açmanızı istemeye devam ediyor | Bağlantı iptal edildi, kuruluştan ayrıldınız veya 90 gün boyunca kullanılmadı. Tekrar bağlayın | +| "You have 5 connected apps" (5 bağlı uygulamanız var) | **Settings → Integrations → MCP** (Ayarlar → Entegrasyonlar → MCP) altında birini iptal edin, ardından tekrar bağlayın | + +Hala takılı kaldınız mı? [support@befailproof.ai](mailto:support@befailproof.ai) adresine e-posta gönderin. \ No newline at end of file diff --git a/docs/tr/reference/otel.mdx b/docs/tr/reference/otel.mdx new file mode 100644 index 000000000..e8ece77ba --- /dev/null +++ b/docs/tr/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "FailproofAI Cloud'a OTEL'i etkinleştirin, teslimatı inceleyin ve önceki ayarlarınızı geri yükleyin." +icon: "radio" +--- + +`failproofai otel` FailproofAI Cloud'a isteğe bağlı OpenTelemetry raporlamasını yapılandırır. Önce makinenizi `failproofai config` ile bağlayın ve bir kuruluş yöneticisinden **Settings → OpenTelemetry** özelliğini etkinleştirmesini isteyin. + +Etkileşimli kurulum, Cloud anahtar alanı ve ajan seçicisinden sonra OpenTelemetry hakkında sorar. İsteğe bağlı adım varsayılan olarak Hayır'dır. OTEL ajanlarını seçmek için Evet'i seçin; aynı etkinleştirme kodu bağlantı yazıldıktan sonra çalışır. Kurulumdan önce Esc tuşuna basılırsa herhangi bir değişiklik uygulanmaz. Etkileşimsiz kurulum, sağlanan bir anahtar, açık kaynak modu ve kaydedilmiş bir bağlantıyı tutmak sizi katılmaya göre dahil etmez. + +## Bir ajanı etkinleştirin + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Desteklenen ajanlar `claude`, `codex` ve `copilot` (VS Code) olabilir. Copilot kurulumu bir VS Code yürütülebilir dosyası veya yüklü bir Copilot uzantısı gerektirir. Geriye kalan bir ayarlar dizini tek başına yeterli değildir; kurulum ikisi de bulunamadığında Copilot'u atlar. + +`--local` doğrudan Cloud yerine yerel röleleye gönderir. Copilot röleleyi otomatik olarak kullanır çünkü ayarları kimlik doğrulama başlığını saklayamaz. + +Röle yalnızca makinenizde dinler. Yapılandırılmış FailproofAI daemon değişikliği birkaç saniye içinde alır; yeniden başlatmanız gerekmez. Başka bir uygulama röle bağlantı noktasına sahipse, durum raporu onu kapalı olarak gösterir ve daemon çalışmaya devam eder. + + +Metin yakalaması varsayılan olarak açıktır. İstemler ve araç ayrıntılarını atlamak için `--no-content` ekleyin. Ajan sürümleri farklı içerik denetimleri gösterebilir; hassas verilerle kullanmadan önce ajanınızın dışa aktardığı şeyi gözden geçirin. + + +Codex yalnızca konuşma günlüklerini dışa aktarır, iç çalışma zamanı izlemeleri veya metrikleri değil. Codex yapılandırmanızda açık `log_user_prompt = false` kapalı kalır; etkinleştirme bu seçimi koruduğunda bir not yazdırır. + +### Bir raporlama yolu seçin + +Bir ajan için transkript raporlaması açıksa, kurulum sorar: + +> failproofai zaten Claude Code oturumlarını Cloud'a gönderiyor. Bunları OTEL ile göndermek ister misiniz? Claude Code'un transkript yüklemesi durur. + +Varsayılan değer Hayır'dır. `--yes` bir istem olmadan anahtarı kabul eder. Diğer ajanlar ve ilke yaptırımı etkilenmez. + +Codex kurulumu, daemon'u eksporter ayarlarını yazmadan önce toplayıcı değişikliğini onaylamasını bekler. Onaylama zaman aşımına uğrarsa, kurulum sizi Codex başlatmadan önce beklemeyi uyarır. + +Config v2 hatırlanan izleme listesini `agents.selected` konumunda tutmaktadır (ve algılama geçmişini `agents.seen` konumunda). Ajan başına transkript tercihi `collector.agents..sessions` konumunda, OTEL sahipliği `otel.agents` konumunda ve röle ayarları `collector.otlp.enabled` / `collector.otlp.port` konumunda kalır. Bu ayrı anahtarlar eski OTEL yapılandırmalarını okunabilir tutar: kurulum izleme listesini taşıma tercihini veya ajan ayarlarınızı geri yüklemek için gereken durumu kaybetmeden değiştirebilir. + +## Kurulumu inceleyin + +```bash +failproofai otel status +``` + +Durum her ajanı, ayarlarının FailproofAI tarafından yönetilip yönetilmediğini, hedefini, kuruluşun içe aktarma anahtarını, röle durumunu ve son röle yükleme sonucunu gösterir. + +Kuruluş anahtarı için `unknown` sunucunun bunu sağlamadığı veya ulaşılamadığı anlamına gelir. Bu bir hata değildir ve eski bir Cloud sürümünde yapılandırmayı engellemiyor. + +Cloud henüz OTEL'i desteklemiyorsa, röle reddedilen dışa aktarmaları atmak yerine saklar. Kuruluş alımı kapalıysa, `enable` hiçbir şey yazmaz ve bir hatayla çıkar; bir yöneticiden önce bunu açmasını isteyin. + +## Bir uygulama için yapılandırmayı yazdırın + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +Çıktı bir OTLP/HTTP dışa aktarıcı için bir kabuk ortamı bloğudur. Cloud çıktısı `OTEL_EXPORTER_OTLP_ENDPOINT` öğesini Cloud'un OTLP tabanı olan `https:///otel` öğesine ayarlar ve dışa aktarıcı `/v1/` öğesini ekler; `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` gibi sinyal başına değişken tam `https:///otel/v1/logs` gerektirir. Yerel çıktı röleye işaret eder, `http://127.0.0.1:`. Cloud çıktısı yapılandırılmış API anahtarını içerir; bunu bir sır olarak işlem görün. Yerel çıktı anahtarı atlar. Yerel çıktıyı kullanmak için önce yerel bir ajanı etkinleştirin ve röle çalışmaya başlasın. + +## Önceki ayarları geri yükleyin + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable yalnızca FailproofAI tarafından yazılan ayarları geri yükler, ilgisiz değişiklikleri tutar ve her ajanın önceki transkript raporlaması seçimini geri yükler. Son yönetilen yerel ajan devre dışı bırakıldığında, röle dışa aktarmaları kabul etmeyi durdurur. + +Codex için disable ayrıca `collector.agents.codex.sessions_resume_after` öğesini (epoch milisaniye) kaydeder. Mevcut dağıtım baytları teslim edildi olarak kabul edilir, bu nedenle OTEL ile yakalanan oturumlar tekrar yüklenmez; daha sonraki ekler yine de transkript raporlaması yoluyla akar. + +Her komut `--help` destekler. Uygulama ve kodlama ajanı örnekleri için [Cloud'da OpenTelemetry](/tr/agenteye/opentelemetry) bölümünü görün. \ No newline at end of file diff --git a/docs/tr/reference/slack.mdx b/docs/tr/reference/slack.mdx new file mode 100644 index 000000000..35710b64b --- /dev/null +++ b/docs/tr/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack uygulaması" +description: "Failproof Asistanını Slack'ten sorun, grafikleri konuda alın ve bir düğmeyle değişiklikleri onaylayın." +icon: "slack" +--- + +[Failproof Asistanını](/tr/sessions/assistant) Slack'ten sorun. Uygulamayı bir kanalda etiketle, doğrudan mesaj gönder veya `/failproof ` komutunu kullan. Yanıtlar **kendi** Failproof AI izinlerini kullanır, grafikler konuda görünür ve bir şeyi değiştirmesi gereken her şey önce onayını ister. + +Bir resmi uygulama vardır. Failproof AI Cloud'unuz barındırılmış olsun veya kendi kendine barındırılmış olsun aynı şekilde çalışır. + + + Yanıtlar AI modelleri tarafından oluşturulur ve yanlış olabilir. Önemli herhangi bir şeyi bağlantılı kaynak verilere karşı kontrol edin. + + +## Bir çalışma alanını bağlayın + +Failproof AI'da `settings:write` iznine ve Slack'te çalışma alanı yöneticisi veya sahibi olmanız ya da uygulamayı ekleyen kişi olmanız gerekir. + + + + 1. **Ayarlar → Entegrasyonlar**'a gidin ve **Slack'e Ekle**'yi seçin. + 2. Uygulamayı Slack'te onaylayın. + 3. Failproof AI'ya geri dönün ve çalışma alanını kuruluşunuza bağlamayı onaylayın. + + + 1. Uygulamayı ekleyin, ardından **Home** sekmesini açın. + 2. **FailproofAI Cloud ile Devam Et**'i seçin veya **Kendi URL'mi Kullan**'ı seçip oturum açtığınız adresi girin. + 3. Devam düğmesini seçin, oturum açın, kuruluşu seçin ve onaylayın. Bağlantı bir kez çalışır ve 10 dakika sonra sona erer. + + + +Bir çalışma alanı bir kuruluşa bağlanır ve bir kuruluş bir çalışma alanına bağlanır. + +Hesabınız yok mu? Önce [bir tane oluşturun](https://app.befailproof.ai/login), ardından bağlayın. + +## Slack'te kim olduğunuz + +İlk kez sorduğunuzda, uygulama hangi üye olduğunuzu belirler: + +- **Otomatik olarak, e-posta ile**, bağlı çalışma alanının tam üyesi olduğunuzda, Slack e-postanız doğrulandığında ve kuruluşun tam olarak bir üyesi bu e-postayı kullanırken. +- **Aksi takdirde**, özel bir **Hesabınızı Bağlayın** düğmesi alırsınız ve bu, Failproof AI'ı açar ve Slack kullanıcınızı hesabınıza bağlar. + +## Bir soru sorun + +| Yer | Nasıl | +| --- | --- | +| Bir kanal | Uygulamayı etiketle. Konuda devam etmek için yanıt ver, etiket gerekli değil | +| Doğrudan mesaj | Uygulamaya mesaj gönder | +| Uygulamanın içinde olduğu grup doğrudan mesaj | Etiketle, ardından konuda devam etmek için yanıt ver | +| Slack Connect kanalı | Uygulamayı etiketle | +| Uygulamanın içinde olduğu herhangi bir konuşma | `/failproof ` yanıtıyla bir konu başlatır | +| `/failproof help` | Uygulamanın neler yapabileceğini görmek için | +| `/failproof status` | Hangi kuruluşun bağlı olduğunu ve kim olarak bağlandığınızı görmek için | +| `/failproof link` | Hangi Failproof AI hesabına bağlandığınızı görmek için | + +Bir konu bir konuşmadır. Meslektaşlar uygulamayı aynı konuda etiketleyebilir ve kendi izinleriyle her birine yanıt verir. Konuyu başlatan kişi etiket olmadan devam ettirebilir. + +Yanıt veri olduğunda, uygulama Failproof AI'da açmak için bir bağlantı içeren bir grafik veya tablo yayımlar. + +## Değişiklikleri onaylayın + +Asistanın yaptığı her değişiklik ilk olarak **Onayla** ve **İptal** düğmelerini gösterir ve Slack **Onayla**'dan önce bir kez daha sorar. Sadece soruyu soran kişi bunlara yanıt verebilir, düğmeler 5 dakika sonra sona erer ve değişiklik o kişinin izinleriyle yapılır. + +Slack'ten, asistan kaydedilmiş sorguları ve panoları, değerlendirmeleri, uyarıları, denetimleri, sorunları ve ilkeleri değiştirebilir ve kod düzeltmeleri önerebilir; bunu yalnızca izniniz varsa yapabilir. API anahtarlarını, kullanıcıları veya ayarları değiştiremez. + +## Bağlantı önizlemeleri + +Slack'e yapıştırılan Failproof AI sorunu, oturumu ve değerlendirme bağlantıları barındırılan Failproof AI Cloud'da kartlara açılır. Bir kart yalnızca onu tetikleyen kişinin görebileceği şeyi gösterir. Kendi kendine barındırılan bir adrese bağlantılar açılmaz; ancak asistanın kendi yanıtlarındaki kartlar yine de görünür. + +## Slack Connect kanalları + +Başka bir çalışma alanından gelen kişiler, kuruluşun üyesi olmaları ve hesaplarını bağlamaları durumunda uygulamayı kullanabilir. Yanıtlar, kuruluşunuzun üyesi olmayan kişiler de dahil olmak üzere konuşmadaki herkesin görebileceğine, bu nedenle herkesin yanıtı görebileceği yerde sormalısınız. + +Uygulama, yalnızca kanalda olan diğer çalışma alanının her birinin kuruluşa bağlı biri olması halinde yanıt verir. Buna kadar, soran kişiye neden olduğunu söyler. + +## Uygulamanın istediği izinler + +| Slack izni | Neden | +| --- | --- | +| `app_mentions:read` | Birinin uygulamayı etiketlediğini bilmek | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Doğrudan mesajları ve uygulamanın konularındaki yanıtları almak. Uygulama diğer mesajları yoksayar ve konuşmanın geçmiş mesajlarını hiçbir zaman okumaz | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Ne tür konuşma olduğunu kontrol etmek, böylece kim yanıtı görebileceğini bilmek | +| `chat:write` | Yanıtları ve onay düğmelerini göndermek | +| `commands` | `/failproof` sağlamak | +| `files:write` | Grafikleri göndermek | +| `links:read`, `links:write` | Yapıştırılan Failproof AI bağlantılarının önizlemelerini göstermek | +| `users:read`, `users:read.email` | Sizi Failproof AI hesabınıza eşleştirmek ve adları göstermek | + +## Bağlantıyı kesin + +**Ayarlar → Entegrasyonlar**'a gidin ve **Bağlantıyı Kes**'i seçin, uygulamanın **Home** sekmesinde **Bağlantıyı Kes**'i kullanın veya Slack'ten uygulamayı kaldırın. + +Bunlardan herhangi biri çalışma alanının bağlantısını, bot jetonunu, bağlı hesapları ve konu kayıtlarını siler. Geçmiş Slack konuşmaları panoda okunabilir kalır. Kuruluş daha sonra herhangi bir çalışma alanını hemen bağlayabilir. + +## Veri ve gizlilik + +Sorular ve yanıtlar konuyu başlatan kişi altında kuruluşunuzun panosunda konuşmalar olarak kaydedilir. Slack verileri hiçbir zaman AI modellerini eğitmek için kullanılmaz. Uygulamanın ne aldığını ve ne kadar süre tutulduğunu görmek için [gizlilik politikasına](https://befailproof.ai/privacy/) bakın. + +## Sorun giderme + +| Gördüğünüz şey | Ne yapmalısınız | +| --- | --- | +| "Bu çalışma alanı henüz bir FailproofAI Cloud'a bağlı değil." | Bir çalışma alanı yöneticisi uygulamanın **Home** sekmesini açar ve birini seçer | +| "Bu bağlantının süresi dolmuş veya zaten kullanılmış." | **Home** sekmesinde yeni bir bağlantı için Cloud'unuzu tekrar seçin | +| "Bu kuruluş zaten bir Slack çalışma alanına bağlı." | Önce ayarlarında bağlantıyı kesin | +| "Bu Slack çalışma alanı başka bir kuruluşa bağlı." | Önce onu bu kuruluştan kesin | +| "Asistanı kullanmak için hesabınızı bağlayın." | Düğmeyi seçin ve Failproof AI'da onaylayın | +| Uygulama grup doğrudan mesajda yanıt vermez | Grup izinlerini vermek için Slack'te uygulamayı tekrar ekleyin. Bağlantınız korunur | +| "Kuruluşunuzdan yanıtları buraya göndermeyeceğim" | Bu çalışma alanında kuruluşun üyesi olan biri uygulamayı etiketler ve hesaplarını bağlar | + +Hala takılı mı? [support@befailproof.ai](mailto:support@befailproof.ai) adresine e-posta gönderin. \ No newline at end of file diff --git a/docs/tr/sessions/sentiment.mdx b/docs/tr/sessions/sentiment.mdx new file mode 100644 index 000000000..e13c07b99 --- /dev/null +++ b/docs/tr/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Duygu analizi" +description: "Jev duygu puanları ile sinirli, kafası karışık ve düzeltici mesajları bulun." +icon: "smile" +--- + +Jev, bir kişinin ajanlarınıza gönderdiği her mesajı dört duygu için 0 ile 100 arasında puanlandırır — **öfkeli**, **sinirli**, **mutlu** ve **kafası karışık** — ve ajanın performansı hakkında üç sinyal: + +- **Düzeltici**: kişi ajanın bir şey yanlış yaptığını söyler. +- **Çözüldü**: kişi ajanın sorunu çözdüğünü doğrular. +- **Şüpheli**: kişi ajanın cevabının doğru olup olmadığını veya gerçekten işe yarayıp yaramadığını sorgulamaktadır. + +Duygu analizi, insanların sabırlarını kaybettiği sohbetleri, devamlı düzeltilen ajanları ve iyi sonuç veren yanıtları bulmak için kullanın. Bu, yerleşik Jev puanlandırması; bir değerlendirme yazmanıza gerek yoktur. Kendi sabit cevap sorunuz için, [bir Jev değerlendirmesi oluşturun](/tr/evaluations/jev). + + + Duygu analizi, bir yönetici bunu kuruluş için etkinleştirene kadar kapalıdır. Jev her mesaj için bir puanlama isteği yapar ve bu mesajı ajan yanıtından önce alır. Puanlama, kuruluşunuzun model bütçesini kullanır. + + +## Etkinleştirin + +1. **Yönetim → Ayarlar** sayfasına gidin. +2. **İnsan girdisi duygusu** altında, açık konuma getirin ve kaydedin. + +Son günün mesajları önce puanlandırılır. Bundan sonra, yeni mesajlar gelişinden bir iki dakika içinde puanlandırılır. + +## İncelemek için bir sohbet bulun + +**Gözlemle → Duygu analizi** sayfasını açın. Zaman, ortam, ajan veya oturum kimliğine göre filtreleyin. Başlık, mesaj ve oturum sayılarını sayar, kaç mesajın **işaretlendiğini** gösterir ve en çok kullanılan sinali adlandırır. Öfkeli, sinirli, düzeltici, kafası karışık veya şüpheli puanı 100 üzerinden 35'e ulaştığında bir mesaj işaretlenir. + +![Duygu analizi kontrol paneli, mesaj ve oturum sayılarını, işaretlenen mesajları ve zaman içindeki Jev puanlarını gösteren görüntü.](/images/dashboard/sentiment-overview.png) + +Sinyalleri karşılaştırmak için **Zaman içinde skor** kullanın. Gösterilecek puanları seçin, ardından o zaman diliminin mesajlarını görmek için bir noktayı seçin. **Ajan başına** tablosu, bir sinyalin nerede yoğunlaştığını gösterir. **Mesajlar** bölümünde, en güçlü negatif puana göre sıralayın veya tek bir puanı seçin. Neyin başarısız olduğuna karar vermeden önce çevredeki sohbeti okumak için bir mesajı kendi oturumunda açın. + +![Duygu analizi mesaj listesi, en güçlü negatif puana göre sıralanmış ve her kaynak oturumuna bağlantı gösteren görüntü.](/images/dashboard/sentiment-messages.png) + +## Hangi mesajlar puanlandırılır + +Yalnızca bir kişinin yazdığı mesajlar: + +- Özel ajanlarınızın SDK ile insan girdisi olarak kaydettiği mesajlar. +- Claude Code, Codex, OpenCode, pi, Hermes ve OpenClaw'a yazılan istemler (oturum transkriptleri gönderildiğinde — varsayılan). Planlanan işler, enjekte edilen talimatlar, alt-ajan devir işlemleri ve ajanın kendi çalışma zamanının yazdığı diğer metinler puanlandırılmaz. `claude -p`, `codex exec` ve `hermes -z` gibi etkileşimli olmayan çalıştırmalar da değildir: bir komut dosyası bu istemler yazıyordu, bir kişi değil. + +Puanlama, kişinin kendi kelimelerini yargılar. "Düzeltimi" gibi kısa, keskin bir talimat öfke olarak sayılmaz ve soru sormak kafa karışıklığı olarak sayılmaz. Yeni bir istek bir düzeltme değildir ve kendi başlarına teşekkürler çözüldü olarak sayılmaz. \ No newline at end of file diff --git a/docs/tr/start/use-jev.mdx b/docs/tr/start/use-jev.mdx new file mode 100644 index 000000000..7f909b05e --- /dev/null +++ b/docs/tr/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Jev'i Kullan" +description: "Tamamlanan oturumlar için Jev değerlendirmelerini ayarlayın veya canlı araç çağrısı incelemesi için Jev ilkelerini ayarlayın." +icon: "sparkles" +--- + +Jev, bir aracı çalıştırmasında iki noktada yardımcı olur: tamamlanan bir oturumu bilinen yanıtlara karşı puanlandırın veya aracıdan istediğiniz şey bağlamında bir araç çağrısını inceleyin. + + + + Tamamlanan bir oturumu birkaç bilinen yanıtı olan bir soruya karşı puanlandırabileceğiniz zaman Jev değerlendirmesi kullanın; örneğin "Müşteri iade talebinde bulundu mu? Evet veya hayır cevap verin." Bu, oturumlar arasındaki desenleri bulmanıza yardımcı olur. + + ## Bir değerlendirme oluşturun + + Cloud panelinde **Analyze → eval authoring → new eval** seçeneğini açın. Tek bir sabit yanıtlı soru girin, **draft** seçin ve sınıflandırıcı puanı seçtiğini kontrol edin. [Bunu](/tr/evaluations/test) gerçek oturumlarla test edin, ardından dağıtın. + + ![Bir soruyu açıkladığınız, taslağı incelediğiniz ve dağıttığınız paylaşılan değerlendirme yazma formu. Bu ekran görüntüsü bir kod taslağını gösterir; Jev için sabit yanıtlı bir soru kullanın.](/images/dashboard/eval-authoring-draft.png) + + ## Puanları okuyun + + Yeni bir oturum tamamlandıktan sonra **Observe → Evaluations** seçeneğini açın veya Cloud CLI'yi kullanın: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI puanları okur; Jev değerlendirmesi oluşturmak şu anda panoyu kullanır. Soru türleri ve örnekler için [Jev değerlendirmeleri](/tr/evaluations/jev) bölümüne bakın. + + + Dize eşleştirmesi ilkesinin istediğiniz bağlamına göre bir araç çağrısının güvenli olup olmadığına karar vermesi gerektiğinde Jev ilkesi incelemesini kullanın. **observe** modunda başlayın; böylece yüklü ilkeleriniz her çağrıya karar verirken Jev'in yanıtlarını inceleyebilirsiniz. + + Jev'in denetimleri bir paketten gelir; Failproof AI hiçbirini göndermez. Bunları yükleyene kadar, yapılandırılmış olsa bile Jev hiçbir şey sormaz: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Cloud Jev'i ayarlayın + + Cloud panelinde **Administration → Keys** seçeneğini açın ve **machine** ön ayarıyla bir anahtar oluşturun. [Hızlı başlangıçta](/tr/start/quickstart) gösterildiği şekilde `failproofai config` ile kullanın. Mevcut bir Jev yapılandırması olmayan bir makinede, bu Cloud Jev'i observe modunda etkinleştirir. Bağlantıyı şu şekilde kontrol edin: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Kendi bitiş noktanızı kullanın + + Yerel panelde **Settings → Jev** seçeneğini açın. Sağlayıcıyı seçin, belirtecini yapıştırın, **observe** seçin ve Jev'i açın. + + ![Sağlayıcı, belirteç alanı ve observe modu seçili olan yerel Jev ayarları paneli.](/images/dashboard/jev-settings.png) + + Veya bitiş noktanızı bir terminalden yapılandırın ve test edin: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Bağlantılı bir aracıdan `README.md` üzerinde dosya okuma aracını kullanmasını isteyin. Araç çağrısının oturumda göründüğünü doğrulayın, ardından yerel panelde **Policies → Activity** altında inceleyin. Observe sonuçları doğru göründüğünde, ne zaman uygulanacağını açıklamak için [Jev ilkeleri](/tr/policies/jev) bölümünü okuyun. Sağlayıcı ayrıntıları ve yapılandırma için [entegrasyon başvurusuna](/tr/reference/jev) bakın. + + \ No newline at end of file diff --git a/docs/vi/admin/product-analytics.mdx b/docs/vi/admin/product-analytics.mdx new file mode 100644 index 000000000..08bb2a57b --- /dev/null +++ b/docs/vi/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "Phân tích sản phẩm" +description: "Telemetry sử dụng mà Failproof AI Cloud gửi về chính nó, những gì không bao giờ được thu thập, và cách tắt nó." +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud gửi telemetry sử dụng **về phần mềm của chính nó** cho những người duy trì nó. Nó không bao giờ bao gồm dữ liệu của các agent của bạn. Trên cài đặt tự lưu trữ, nó được bật theo mặc định, và bạn có thể tắt nó. + +## Những gì được thu thập + +Mỗi sự kiện mang năm chiều và không có bất cứ gì xác định một người: + +| Chiều | Ví dụ | Nó là gì | +| --- | --- | --- | +| `product` | `agenteye` | Sản phẩm nào đã gửi nó | +| `component` | `dashboard`, `server`, `cli` | Phần nào của sản phẩm đã gửi nó | +| `app_version` | `0.0.1-beta.81` | Bản dựng bạn đang chạy | +| `deployment_kind` | `self_hosted` | Đây là cài đặt khách hàng, bản demo của chúng tôi, QA của chúng tôi, hay máy dev | +| `org_id` | một UUID | Tổ chức nào mà hành động xảy ra, như một định danh không rõ | + +Ngoài những cái đó, các sự kiện ghi lại **những gì được sử dụng, không bao giờ những gì trong đó**: trang nào được xem (dưới dạng mẫu route như `/:org/sessions/:id`, không bao giờ URL thực tế), có bao nhiêu bộ lọc loại nào được áp dụng, liệu một hành động có thành công hay không, và nó mất bao lâu. + +Ứng dụng Slack ghi lại các kết nối và ngắt kết nối workspace, liên kết tài khoản, những câu hỏi được hỏi, biểu đồ được đăng, quyết định phê duyệt, và lỗi theo một danh mục cố định. Nó không bao giờ bao gồm ID workspace, người dùng hoặc kênh Slack, email, câu hỏi, câu trả lời, SQL, hoặc token. + +### Tên của tổ chức bạn + +Cùng với `org_id` không rõ, chúng tôi ghi lại tên tổ chức, slug URL, và địa chỉ dashboard của bạn một lần, trong một bản ghi tổ chức chứ không phải trên mỗi sự kiện. Nó cho phép chúng tôi biết được tài khoản nào mà một mẫu thuộc về khi chúng tôi nhìn vào việc chấp nhận hoặc điều tra một vấn đề bạn đã báo cáo. Đây là thông tin xác định duy nhất mà sản phẩm gửi về bạn. + +### Tổng sử dụng của bạn + +Server báo cáo tổng sử dụng được đo lường của mỗi tổ chức, các số giống như bạn thấy trên trang Sử dụng. Đây chỉ là đếm: sự kiện, phiên, agent, môi trường, chạy đánh giá, điểm số, chạy kiểm toán, truy vấn được lưu, dashboard, cảnh báo, vấn đề, khóa API, và thành viên, cộng với ngày của cửa sổ đo lường. Chúng không chứa bất kỳ định danh, tên, hoặc văn bản truy vấn nào, và chúng đến cho dù có ai đăng nhập hay không. + +## Những gì không bao giờ được thu thập + +- **Không có prompt, phản hồi mô hình, hoặc nội dung sự kiện**, không phải dưới dạng văn bản, tiền tố, hay hash +- **Không có định danh phiên, agent, hoặc trace** +- **Không có tên điểm đánh giá** +- **Không có thông báo lỗi, văn bản ngoại lệ, hoặc phần thân phản hồi**, chỉ mã trạng thái và danh mục từ danh sách cố định +- **Không có đối số công cụ, SQL, hoặc văn bản truy vấn** +- **Không có chi tiết ứng dụng được kết nối.** Kết nối hoặc thu hồi một khách hàng MCP gửi một số lượng quyền tối đa, không bao giờ tên ứng dụng hoặc bất kỳ token nào +- **Không có địa chỉ email** +- **Không có URL referrer hoặc chuỗi truy vấn** +- **Không có ghi hình màn hình, quзахạt DOM, hoặc theo dõi nhấp chuột và con trỏ** + +## Tắt nó trên cài đặt tự lưu trữ + +Đặt `DO_NOT_TRACK=1` trên cả dashboard và server. Chúng quyết định riêng biệt, vì vậy đặt nó chỉ trên một cái để lại cái kia báo cáo. Khởi động lại server để thay đổi có hiệu lực. + +README phát hành của bạn mô tả các cài đặt từ chối khác và cách xác nhận telemetry đã tắt. + +## Một ping khi bạn từ chối + +Nếu bạn từ chối với cài đặt sản phẩm thay vì `DO_NOT_TRACK`, dashboard có thể gửi **một ping ẩn danh** ghi lại điều đó, với xác suất 1 trên 1000 cho mỗi bắt đầu quy trình. Nó cho chúng tôi biết có bao nhiêu nhà khai thác tắt telemetry. Nó không chứa bất kỳ định danh: không có tổ chức, người dùng, hostname, URL, hoặc IP, chỉ sản phẩm, thành phần, phiên bản, loại triển khai, và lý do. Một server từ chối không gửi bất cứ gì. + +Nó không bao giờ được gửi khi bạn sử dụng `DO_NOT_TRACK`, đó là lý do tại sao đó là cài đặt cần sử dụng nếu chính sách của bạn không cho phép bất kỳ telemetry đi ra nào. + +## Nó đi đâu + +Đến PostHog (`us.i.posthog.com`) qua TLS trên cổng 443. Đó là một hostname, vì vậy bạn cũng có thể chặn nó bằng một quy tắc egress duy nhất. + +Để biết cách chúng tôi xử lý thông tin cá nhân rộng hơn, xem [chính sách bảo mật](https://befailproof.ai/privacy/). \ No newline at end of file diff --git a/docs/vi/agenteye/opentelemetry.mdx b/docs/vi/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..e10487270 --- /dev/null +++ b/docs/vi/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "Gửi các dấu vết của coding-agent và telemetry ứng dụng đến FailproofAI Cloud bằng giao thức OTLP." +icon: "radio" +--- + +OpenTelemetry cho phép bạn gửi dấu vết agent, bản ghi và số liệu đo lường đến FailproofAI Cloud bằng cách sử dụng giao thức tiêu chuẩn OTLP/HTTP. Tính năng này là tùy chọn. Các tích hợp FailproofAI hiện tại của bạn sẽ tiếp tục hoạt động mà không cần bật nó. + +## Bật ingest cho tổ chức của bạn + +Một quản trị viên tổ chức mở **Settings → OpenTelemetry** và bật ingest. Sử dụng một khóa Cloud API có quyền `events:add`, quyền tương tự được sử dụng để báo cáo agent. + +Nếu ingest bị tắt, Cloud sẽ từ chối các lần xuất OTLP, vì vậy `failproofai otel enable` không thay đổi gì và các agent của bạn tiếp tục gửi phiên theo cách thông thường. Chạy `failproofai otel status` để kiểm tra công tắc tổ chức và yêu cầu quản trị viên bật nó. + +## Kết nối một coding agent + +Kết nối máy của bạn bằng `failproofai config`, sau đó chọn một agent: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +Lệnh thiết lập hỗ trợ Claude Code, Codex và Copilot và chọn Cloud hoặc một bộ chuyển tiếp xác thực cục bộ nếu thích hợp. Copilot sử dụng bộ chuyển tiếp cục bộ tự động. Khởi động daemon FailproofAI đã được định cấu hình của bạn trước khi sử dụng bộ chuyển tiếp. + +Nếu FailproofAI đã gửi bảng điểm phiên của một agent, thiết lập sẽ hỏi xem có nên chuyển agent đó sang OTEL không. Giá trị mặc định là Không. Chấp nhận sẽ dừng tải lên bảng điểm cho agent đó; nó không thay đổi thực thi chính sách hoặc báo cáo từ các agent khác. + +## Kết nối một ứng dụng + +Sử dụng công cụ OpenTelemetry của ứng dụng của bạn với các biến môi trường sau: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +Điểm cuối là cơ sở OTLP của Cloud, `https://app.befailproof.ai/otel`; bộ xuất của bạn sẽ thêm `/v1/traces`, `/v1/logs` hoặc `/v1/metrics` chính nó. Các biến riêng cho mỗi tín hiệu chẳng hạn như `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` được sử dụng nguyên trạng, vì vậy chúng cần đường dẫn đầy đủ, ví dụ `https://app.befailproof.ai/otel/v1/logs`. + +Thay thế `` bằng khóa API của bạn. Giữ bí mật ra khỏi lịch sử shell, bản ghi màn hình và cấu hình đã được commit. Đối với máy được định cấu hình, `failproofai otel env --service my-agent` in khối với khóa hiện tại của nó. Đầu ra của nó chứa một thông tin xác thực. + +Cloud chấp nhận các lần xuất OTLP/HTTP cho dấu vết, bản ghi và số liệu đo lường dưới dạng protobuf hoặc JSON, bao gồm cả các yêu cầu được nén bằng gzip. Nó không chấp nhận OTLP/gRPC. + +Số liệu đo lường được xác nhận để tương thích bộ xuất nhưng không được lưu trữ hoặc hiển thị. Các dấu vết agent được hỗ trợ và bản ghi coding-agent trở thành phiên; các trường mà agent không xuất sẽ vẫn bị thiếu. + +## Chụp văn bản prompt + + +Chụp văn bản có thể bao gồm các prompt, đối số công cụ và nội dung nhạy cảm khác. `failproofai otel enable` bật nó. Thêm `--no-content` để giữ chụp prompt và chi tiết công cụ tắt. + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +Đối với một agent mà bạn định cấu hình theo cách thủ công, hãy sử dụng các điều khiển chụp nội dung của riêng nó: + + + + Thêm các biến này vào môi trường của agent cùng với khối ứng dụng ở trên: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + Đặt cả hai biến nội dung thành `0` để tránh chụp các prompt và chi tiết công cụ. + + + Trong cấu hình người dùng Codex, hãy sử dụng cài đặt OTEL của nó: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Nội dung cuộc trò chuyện Codex nằm trong bản ghi; để dấu vết thời gian chạy nội bộ và số liệu đo lường bị tắt. Codex sử dụng điểm cuối hoàn chỉnh mà bạn cung cấp. Đặt `log_user_prompt` thành `false` để bỏ qua các prompt; lệnh thiết lập bảo toàn một `false` rõ ràng. + + + Sử dụng cài đặt telemetry của Gemini với bộ chuyển tiếp cục bộ: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI không được hỗ trợ bởi `failproofai otel enable`. Định cấu hình nó theo cách thủ công bằng một bộ sưu tập xác thực của riêng bạn. Đặt `logPrompts` thành `false` để không chụp prompt. + + + Sử dụng các cài đặt người dùng VS Code này: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + Chạy `failproofai otel enable copilot` để bật bộ chuyển tiếp xác thực. Đặt `captureContent` thành `false` để bỏ qua nội dung. + + + +## Kiểm tra hoặc hoàn tác thiết lập + +Bộ chuyển tiếp lưu giữ telemetry qua các lỗi mạng và máy chủ tạm thời và thử lại sau khi phục hồi. Một lỗi `400` vĩnh viễn, bao gồm một sự kiện quá lớn để lưu trữ, yêu cầu sửa lại tải trọng. Bộ chuyển tiếp giữ lại lô bị từ chối để kiểm tra thay vì liên tục gửi nó. + +Sau `401` hoặc `403`, thay thế thông tin xác thực bằng một khóa cấp `events:add` cho cùng một tổ chức. Kết nối lại không tự động gửi lại các lần xuất OTLP được lưu giữ bị từ chối do thông tin xác thực; yêu cầu người điều hành của bạn khôi phục những lô đó. Giữ chúng trong tổ chức gốc của chúng. + +```bash +failproofai otel status +failproofai otel disable all +``` + +Trạng thái phân biệt các cài đặt được quản lý bởi FailproofAI từ telemetry bạn đã định cấu hình ở nơi khác. Tắt sẽ khôi phục các cài đặt được quản lý trước đó và lựa chọn tải lên bảng điểm trước đó của agent. + + + Tùy chọn lệnh, thiết lập bộ chuyển tiếp cục bộ và khắc phục sự cố. + \ No newline at end of file diff --git a/docs/vi/evaluations/jev.mdx b/docs/vi/evaluations/jev.mdx new file mode 100644 index 000000000..998486ed9 --- /dev/null +++ b/docs/vi/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev evaluations" +description: "Sử dụng Jev để chấm điểm một phiên hoàn tất dựa trên một câu hỏi có câu trả lời đã biết." +icon: "list-checks" +--- + +Một Jev evaluation đọc một **phiên hoàn tất** và cho điểm từ 0 đến 1. Sử dụng nó khi câu trả lời đã biết trước, chẳng hạn như "Khách hàng có bày tỏ sự khẩn cấp không?" hoặc "Khách hàng bực bội đến mức nào?". Nó giúp bạn tìm ra các mô hình trong các lần chạy; nó không ngăn chặn một lệnh gọi công cụ. Đối với các quyết định được đưa ra **trước** khi một công cụ chạy, sử dụng [Jev policies](/vi/policies/jev). + +## Tạo một trong bảng điều khiển + +1. Mở **Analyze → eval authoring** và chọn **new eval**. +2. Mô tả một câu hỏi và các câu trả lời có thể có của nó. Ví dụ: "Agent có hứa hoàn tiền trước khi kiểm tra chính sách hoàn tiền không? Trả lời có hoặc không." Chọn **draft** và kiểm tra xem kết quả có phải là điểm phân loại. +3. [Kiểm tra nó](/vi/evaluations/test) trên các phiên gần đây, sau đó [triển khai](/vi/evaluations/deploy). Các phiên hoàn tất mới được chấm điểm; [backfill](/vi/evaluations/deploy#score-sessions-you-already-have) nếu bạn cũng cần lịch sử. + +![Mẫu eval authoring được chia sẻ, nơi bạn mô tả một câu hỏi có câu trả lời cố định, xem xét bản nháp và triển khai sau khi kiểm tra. Ví dụ hiển thị là một đánh giá mã; một câu hỏi Jev sử dụng cùng quy trình tạo tác.](/images/dashboard/eval-authoring-draft.png) + +Trợ lý có thể chọn giữa mã, phân loại Jev và một [judge](/vi/evaluations/judge). Kiểm tra lựa chọn của nó trước khi triển khai. Jev cho điểm mà không có lý do bằng văn bản; chọn judge khi bạn cần một lời giải thích. Xem [tài liệu tham khảo Jev evaluation](/vi/reference/jev-evaluations) để biết các loại câu hỏi và giới hạn điểm. + +## Đọc các điểm + +Mở **Observe → Evaluations** để biểu đồ kết quả theo agent và thời gian. Từ một terminal, Cloud CLI có thể đọc các kết quả tương tự: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI đọc kết quả; tạo tác và triển khai diễn ra trong bảng điều khiển. Xem [tài liệu tham khảo Cloud CLI](/vi/reference/cloud-cli#evaluations) để biết các bộ lọc. \ No newline at end of file diff --git a/docs/vi/evaluations/judge.mdx b/docs/vi/evaluations/judge.mdx new file mode 100644 index 000000000..3a8d12925 --- /dev/null +++ b/docs/vi/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLM judges" +description: "Đánh giá các phiên làm việc dựa trên những yếu tố mà code không thể đo lường — tính chính xác, tông đề, liệu agent có tuân theo chính sách — bằng cách mô tả tiêu chuẩn tốt là như thế nào và để một model đọc cuộc trò chuyện." +icon: "scale" +--- + +Một bài đánh giá Python được lưu trữ có thể đếm và so sánh: có bao nhiêu lần gọi tool, có bao nhiêu lỗi, phiên làm việc mất bao lâu. Nó không thể cho bạn biết liệu câu trả lời có *chính xác* hay không, liệu phản hồi có thô lỗ hay không, hoặc liệu agent có kiểm tra chính sách trước khi hành động hay không. + +Một **LLM judge** có thể. Bạn mô tả tiêu chuẩn tốt bằng ngôn ngữ tự nhiên, và model đọc phiên làm việc rồi trả về một điểm từ 0 đến 1 kèm theo lý luận của nó. + + +Một judge tốn một lần gọi model cho mỗi phiên làm việc mà nó chạy, còn một code evaluation thì không tốn gì. Chỉ sử dụng judge cho những câu hỏi cần phải *hiểu* cuộc trò chuyện — và đặt một điều kiện cho nó, để nó chỉ chạy trên những phiên làm việc mà câu hỏi thực sự liên quan. + + +## Tôi muốn cái nào? + +| Câu hỏi | Sử dụng | +| --- | --- | +| Nó có gọi cùng một tool hai lần không? | code | +| Có bao nhiêu lỗi? | code | +| Phiên làm việc có dưới 30 giây không? | code | +| Khách hàng có thể hiện sự khẩn cấp không? | [classifier](/vi/evaluations/jev) | +| Khách hàng bực bội đến mức độ nào? | [classifier](/vi/evaluations/jev) | +| Câu trả lời có thực sự chính xác không? | **judge** | +| Phản hồi có thô lỗ hoặc coi thường không? | **judge** | +| Nó có kiểm tra chính sách hoàn tiền trước khi hứa hoàn tiền không? | **judge** | + +Quy tắc chung: **có thể đếm được → code, câu trả lời bạn có thể liệt kê trước → [classifier](/vi/evaluations/jev), cần lời giải thích → judge.** Judge là cái viết văn bản về những gì nó thấy; sử dụng nó khi con số sẽ khiến ai đó hỏi "tại sao?". + +Bạn không phải quyết định trước. Mô tả những gì bạn muốn đo lường và trợ lý sẽ chọn, sau đó cho bạn biết nó chọn cái nào và tại sao. Bạn có thể chuyển đổi. + +## Viết một cái + +1. Đi tới **Analyze → eval authoring** và chọn **new eval**. +2. Mô tả những gì bạn muốn đánh giá, và chọn **draft**. +3. Xem xét **criteria**, **threshold**, và **condition**, rồi triển khai. + +### Criteria + +Một hoặc hai câu, viết như một yêu cầu chứ không phải một câu hỏi: + +> Trợ lý không được hứa hoặc phê duyệt hoàn tiền mà không kiểm tra chính sách hoàn tiền trước. + +Hãy cụ thể về những gì sẽ khiến nó *thất bại*. "Phản hồi có tốt không?" cho bạn một con số không có nghĩa gì; câu ở trên cho bạn một con số bạn có thể hành động. + +### Threshold + +Điểm tại hoặc phía trên đó phiên làm việc được xem là thành công. `0.7` là một điểm khởi đầu hợp lý. Điểm đầy đủ từ 0 đến 1 luôn được lưu trữ, nên threshold chỉ quyết định thành công/thất bại — bạn có thể xem phân phối và điều chỉnh. + +### Condition + +Điều kiện Python giống như bất kỳ đánh giá nào khác, và nó quan trọng hơn nhiều ở đây. Không có điều kiện, judge sẽ chạy trên **mọi** phiên làm việc trong tổ chức của bạn, mỗi lần một lần gọi model: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +Bảng điều khiển sẽ cảnh báo bạn nếu bạn triển khai một judge mà không có điều kiện. Điều này đôi khi là đúng — một agent lưu lượng thấp mà bạn muốn đánh giá hoàn toàn — nhưng nó phải là một quyết định, không phải một tai nạn. + +## Judge thấy gì + +Cuộc trò chuyện, dưới dạng các lượt, mới nhất trước nếu phiên làm việc dài: + +- những gì người dùng nói +- những gì trợ lý trả lời +- **mọi tool mà agent gọi, và lệnh gọi đó trả về cái gì, theo thứ tự** + +Phần cuối cùng là những gì làm cho "nó có làm X *trước khi* Y không" trở thành một câu hỏi công bằng. Một lệnh gọi tool thất bại được hiển thị như một lỗi, nên "nó có phục hồi một cách thanh lịch từ một lỗi không" cũng hoạt động. + +Các phiên làm việc rất dài được cắt ngắn để phù hợp với ngữ cảnh của model. Khi điều đó xảy ra, lý luận nói rõ ràng — bạn sẽ không bao giờ thấy một phán quyết được đưa ra trên một phần của phiên làm việc được trình bày như được đưa ra trên toàn bộ nó. + +## Đọc kết quả + +Một judge tạo ra một **score** giống như bất kỳ đánh giá được tính điểm nào khác, vì vậy nó tạo biểu đồ, lọc, và kích hoạt cảnh báo theo cách tương tự. Cùng với con số, nó lưu trữ **lý luận** của judge — đoạn văn giải thích những gì nó thấy. Hãy đọc trước tiên khi một điểm bất ngờ; nó thường là một phiên làm việc thực sự thú vị hoặc một dấu hiệu rằng criteria cần được tinh chỉnh. + +Các điểm ổn định đối với các trường hợp rõ ràng nhưng không xác định chính xác từng bit. Coi một điểm biên giới duy nhất là một lời nhắc để đi đọc phiên làm việc, không phải là một phán quyết. + +## Giới hạn + +- **Kiểm thử hiện chưa có sẵn.** Một lần chạy khô không có phân công phiên làm việc đằng sau nó, và phân công đó là những gì cho phép chi tiêu ngân sách model của bạn — vì vậy không có gì để một lệnh gọi kiểm thử tính phí. Triển khai với một điều kiện hẹp và đọc một vài kết quả đầu tiên. +- **Backfill không có sẵn.** Lấp đầy một code evaluation trong vài tháng lịch sử miễn phí; làm điều đó với một judge sẽ chi tiêu toàn bộ ngân sách của bạn trong vài phút. +- **Chỉnh sửa criteria xuất bản một phiên bản mới.** Các điểm cũ và mới không thể so sánh được, vì vậy chúng được giữ riêng biệt thay vì trộn thành một đường xu hướng. +- **Một judge luôn tạo ra một điểm**, không bao giờ là một metric hoặc một assertion. + +## Khi ngân sách của bạn hết + +Judge chi tiêu ngân sách model của tổ chức bạn. Khi nó cạn kiệt, các đánh giá judge dừng lại với một lý do rõ ràng thay vì thất bại im lặng, và **code evaluations tiếp tục chạy bình thường**. Tăng ngân sách và chúng tiếp tục trên phiên làm việc tiếp theo. \ No newline at end of file diff --git a/docs/vi/policies/authority.mdx b/docs/vi/policies/authority.mdx new file mode 100644 index 000000000..545cd2d1f --- /dev/null +++ b/docs/vi/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "Quyền hạn của chính sách" +description: "Những phán quyết nào của trình đánh giá ngữ nghĩa Jev có thể được xóa, và những phán quyết nào là cuối cùng." +icon: "scale" +--- + +Khi bạn cấu hình [xem xét chính sách Jev](/vi/policies/jev) thông qua FailproofAI Cloud hoặc khóa riêng của bạn, mỗi lệnh gọi công cụ được gated được đánh giá bởi các chính sách bạn chạy và bởi Jev, công cụ này hỏi những gì lệnh gọi thực sự thực hiện và liệu người đã nhập tác vụ có yêu cầu nó hay không. **Quyền hạn** của mỗi chính sách quyết định điều gì xảy ra khi hai bên không đồng ý. + +Không có Jev được cấu hình, quyền hạn không có tác dụng. Mỗi chính sách thực thi chính xác như luôn luôn. + +## Cứng và có thể xem xét + +- **Cứng** là mặc định. Phán quyết từ chối hoặc hướng dẫn của chính sách cứng là cuối cùng: Jev không thể xóa nó, và từ chối cứng dừng lệnh gọi mà không chờ Jev. +- **Có thể xem xét** có nghĩa là Jev có thể xóa phán quyết của chính sách, nhưng chỉ thông qua các kiểm tra ngữ nghĩa mà chính sách đặt tên trong `reviewedBy`. Phán quyết chỉ được xóa khi **mỗi** kiểm tra được đặt tên đã được hỏi về lệnh gọi này và mỗi kiểm tra hoặc không tìm thấy gì hoặc ghi lại người dùng yêu cầu điều này. Một kiểm tra **bắn** — tìm thấy mối quan tâm — không có người dùng yêu cầu sẽ giữ lại khối, ngay cả khi phán quyết của riêng nó chỉ là một cảnh báo. Kiểm tra mà Jev không được hỏi, vì nó không áp dụng cho công cụ đó, không bao giờ xóa bất cứ điều gì, dù những kiểm tra khác nói gì. Một sự làm mềm đếm là sự đồng ý: khi lệnh gọi là một bước của tác vụ người dùng đã đưa ra và không đi xa hơn, Jev biến phán quyết từ chối thành cảnh báo, và cảnh báo đó xóa khối của chính sách và là những gì tác nhân được cho biết. + +Một chính sách chỉ có thể xem xét khi tất cả những điều này giữ: + +1. Nó khai báo `authority: "reviewable"`. +2. `reviewedBy` là một danh sách không rỗng, và mỗi mục là kiểm tra Jev mà gói đã cài đặt khai báo. Failproof AI không có kiểm tra Jev nào: [mười sáu kiểm tra dưới đây](#semantic-policy-names) đến từ `failproofai policies add FailproofAI/jev-policies`. Không có gói nào khai báo kiểm tra, mỗi chính sách là cứng. +3. Nó không phải `alwaysOn`. Bảo vệ dừng tác nhân khỏi vô hiệu hóa Failproof AI luôn cứng. + +Bất cứ điều gì khác là cứng: một trường bị thiếu, một giá trị bị chính tả sai, `reviewedBy` trống hoặc định dạng sai, hoặc một tên không phải kiểm tra mà máy này có thể hỏi. Một tên không xác định làm cho toàn bộ khai báo cứng thay vì bị bỏ qua, bởi vì `reviewedBy` có nghĩa là "tất cả những kiểm tra này phải được hỏi, và không có kiểm tra nào được phép từ chối", và bỏ qua một tên sẽ cho phép Jev xóa chính sách trên ít kiểm tra hơn bạn yêu cầu. + +Khi Jev được cấu hình, Failproof AI ghi một cảnh báo khi nó từ chối khai báo `reviewable`, một lần mỗi quy trình. Không có Jev nó không nói gì, bởi vì quyền hạn khi đó không quyết định gì. `failproofai publish` từ chối xây dựng gói mang khai báo như vậy, vì vậy tác giả gói sẽ phát hiện ra trước khi bất cứ ai cài đặt nó. Nó đánh giá `reviewedBy` so với các kiểm tra mà gói khai báo khi nó khai báo bất kỳ, và so với mười sáu tên `FailproofAI/jev-policies` nếu không. + +## Nơi quyền hạn được khai báo + +Mỗi cách một chính sách đến máy có một nơi quyết định quyền hạn của nó: + +| Nguồn | Được khai báo trong | Mặc định | +| --- | --- | --- | +| Chính sách tích hợp | Bảng dưới đây | Cứng trừ khi được liệt kê là có thể xem xét | +| Tệp chính sách của bạn | `authority` và `reviewedBy` trên `customPolicies.add` | Cứng | +| Gói chính sách | Mục nhập của mỗi chính sách trong bảng kê khai gói (`failproofai-pack.json`) | Cứng | +| Chính sách được quản lý bởi Cloud | Việc gán chính sách trong triển khai hoạt động | Cứng. Triển khai hiện tại không đặt nó, vì vậy mỗi chính sách được quản lý bởi cloud là cứng ngày hôm nay. | + +Đối với gói hoặc chính sách được quản lý bởi cloud, các trường được đặt bên trong mã chính sách bị bỏ qua; bảng kê khai hoặc việc gán quyết định. Gói chỉ có thể mô tả các chính sách của riêng nó: tên chính sách của nó không thể chứa `/` và được đăng ký dưới tiền tố của riêng gói, vì vậy không có bảng kê khai nào có thể đánh dấu chính sách tích hợp hoặc chính sách của gói khác là có thể xem xét. Chính sách mà mã gói đăng ký mà không khai báo nó trong bảng kê khai là cứng. + +Hai gói, hoặc hai chính sách được quản lý bởi cloud, có mã giống hệt byte nhau chia sẻ một hiệu ứng và tải như một chính sách. Chính sách đó chỉ có thể xem xét nếu tất cả chúng khai báo nó có thể xem xét, và Jev khi đó phải xóa mỗi kiểm tra mà bất kỳ chúng nào đặt tên. Nếu bất kỳ chúng nào khai báo nó cứng, hoặc không khai báo nó, nó sẽ ở lại cứng. Thứ tự các gói hoặc chính sách được liệt kê không bao giờ quan trọng. + +Hầu hết các máy nhận các chính sách tích hợp từ gói `FailproofAI/policies`, và đọc quyền hạn của chúng từ bảng kê khai của gói đó. Các mục có thể xem xét dưới đây có hiệu lực khi phát hành gói mang chúng được cài đặt; phát hành cũ không mang bất kỳ mục nào, vì vậy mỗi chính sách trong nó ở lại cứng. + +## Khai báo quyền hạn trong chính sách riêng của bạn + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` sao chép cả hai trường vào bảng kê khai gói, vì vậy chính sách được xuất bản dưới dạng gói giữ quyền hạn mà tác giả đã cho nó. Nó từ chối xây dựng gói nếu khai báo không được đáp ứng: giá trị khác với `"hard"` hoặc `"reviewable"`, `reviewedBy` không phải danh sách tên, hoặc tên không phải kiểm tra — một trong [kiểm tra Jev](/vi/policies/publish-a-pack#jev-checks-in-a-pack) của riêng gói khi nó khai báo bất kỳ, kiểm tra tích hợp nếu không. + +## Chính sách tích hợp + +Có thể xem xét chỉ khi kiểm tra ngữ nghĩa thực sự bao gồm mối quan tâm tương tự. Mỗi chính sách tích hợp khác là cứng. + +Bao gồm mối quan tâm là cần thiết nhưng không đủ, và cả hai cách làm sai đều yên tĩnh: + +- **Kiểm tra không bao giờ được hỏi** làm cho khối vĩnh viễn. `reviewedBy` là một liên từ và kiểm tra không được hỏi không bao giờ xóa, vì vậy chính sách ghép nối với kiểm tra có điều kiện tiên quyết không kích hoạt cho các hình dạng mà chính sách khớp không thể xóa được. +- **Kiểm tra được hỏi nhưng không kích hoạt** trả lời không có mối quan tâm, và không có mối quan tâm xóa. Vì vậy ghép nối với kiểm tra không mô hình hình dạng chính sách của bạn không xem xét chính sách — nó chuyển nó tắt cho chính xác các đầu vào mà kiểm tra không hiểu. + +Chính sách ngữ nghĩa ở chế độ hướng dẫn không bao giờ có thể trả lời từ chối, nhưng nó vẫn có thể giữ lại khối: khi nó kích hoạt và người dùng không yêu cầu lệnh gọi, chính sách mà nó xem xét không bị xóa. Sáu trong số kiểm tra `FailproofAI/jev-policies` chỉ hướng dẫn — `push-to-protected-branch`, `commit-on-protected-branch`, `read-outside-workspace`, `system-modification`, `env-secrets-dump` và `external-data-egress` — và [bảng dưới đây](#semantic-policy-names) cung cấp chế độ của mỗi kiểm tra. Câu hỏi cần hỏi là **"có gì còn lại có thể từ chối"**: xóa không bao giờ phải để mối quan tâm được thực thi bởi không có gì. Động cơ áp dụng bài kiểm tra đó mỗi lệnh gọi. Cảnh báo mà không ai đồng ý không phải xóa, bởi vì trước lệnh gọi công cụ cảnh báo không dừng tác nhân. Và khi kiểm tra **có thể** từ chối cảnh báo — bằng chứng của nó không đủ để từ chối — và người dùng không yêu cầu lệnh gọi, không có gì bị xóa trên lệnh gọi đó và mỗi từ chối regex vẫn giữ. + + +**Kiểm tra chỉ dưới đường kích hoạt của nó không giữ lại sàn.** Quy tắc trên cần kiểm tra **kích hoạt** (bằng chứng ≥ 0,7). Khi mỗi kiểm tra liên quan chạm vào dưới đó, không có gì kích hoạt, những người xem xét trả lời không có mối quan tâm, và từ chối có thể xem xét bị xóa. Đo lường trực tiếp ở chế độ thực thi: Read yêu cầu của `/etc/shadow` (`secret-exposure` 0,69, `read-outside-workspace` 0,37, chỉ mô hình các đường dẫn thư mục chính) và `set | curl -d @- …` sau khi đọc SETUP.md (`env-secrets-dump` 0,66, `credential-exfiltration` 0,65 với `sends_out` 0,97) đều được phép, trong khi tầng regex riêng từ chối chúng. Những ngưỡng được hiệu chỉnh trên kho dữ liệu được gắn nhãn và chưa được đo lại so với điều này; cho đến khi được, giữ chính sách **cứng** nơi một trong những hình dạng này xuyên qua quan trọng hơn các khối sai của nó. + + +| Chính sách | Quyền hạn | Được xem xét bởi | Tại sao | +| --- | --- | --- | --- | +| `protect-env-vars` | có thể xem xét | `env-secrets-dump`, `secret-exposure` | Mẫu kích hoạt trên bất kỳ tham chiếu biến nào; Jev hỏi liệu giá trị bí mật thực sự có được in ra hay không. | +| `block-env-files` | có thể xem xét | `secret-exposure` | Mẫu khớp với bất kỳ đường dẫn `.env` nào, bao gồm các mẫu; Jev hỏi liệu giá trị bí mật thực sự có được đọc hoặc ghi hay không. | +| `block-read-outside-cwd` | có thể xem xét | `read-outside-workspace` | Được đo là ồn ào trên lưu lượng thực; Jev hỏi liệu nội dung tệp bên ngoài dự án có được đọc hay không. Việc đọc người dùng yêu cầu hoặc kiểm tra không tìm thấy gì bị xóa; việc đọc không được yêu cầu mà nó cờ giữ lại khối. | +| `warn-git-amend` | có thể xem xét | `git-history-rewrite` | Sửa đổi commit chưa được đẩy là bình thường; tổn hại là viết lại lịch sử người khác có thể đã kéo. | +| `warn-destructive-sql` | có thể xem xét | `database-destruction` | Jev cũng hỏi liệu mục tiêu là cơ sở dữ liệu thực sự hay là cơ sở dữ liệu thử nghiệm có thể bị loại bỏ. | +| `warn-global-package-install` | có thể xem xét | `system-modification` | Mối quan tâm tương tự: thay đổi máy bên ngoài dự án. | +| `block-failproofai-commands` | cứng | | `alwaysOn` tự bảo vệ. Không bao giờ có thể xem xét. | +| `block-rm-rf` | có thể xem xét | `destructive-deletion` | Heuristic độ sâu đường dẫn sai `rm -rf node_modules`; Jev hỏi liệu những gì sẽ bị phá hủy có tái tạo được hay không. `rm -rf /` giữ cả hai kiểm tra đúng. | +| `block-sudo` | cứng | | Tăng quyền lực. | +| `block-curl-pipe-sh` | cứng | | Chạy mã được tải xuống từ internet. | +| `block-push-master` | cứng | | Đẩy trực tiếp vào nhánh được bảo vệ. | +| `block-work-on-main` | cứng | | `commit-on-protected-branch` bao gồm chính xác mối quan tâm này nhưng ở chế độ hướng dẫn, vì vậy nó không bao giờ có thể trả lời từ chối, và không có kiểm tra nào khác bao gồm nó. | +| `block-force-push` | có thể xem xét | `git-history-rewrite` | Kiểm tra của Jev là tập hợp con của người phù hợp và đếm `--force-with-lease`; những gì xóa là force-pushing nhánh của riêng bạn. | +| `block-secrets-write` | có thể xem xét | `secret-exposure` | Kết hợp đường dẫn không được neo, vì vậy `src/auth/credentials.ts` bị bắt; Jev hỏi liệu tài liệu khóa thực sự có được viết hay không. | +| `block-kubectl` | có thể xem xét | `production-infra-change` | Từ chối toàn bộ CLI, bao gồm các lệnh con chỉ đọc; Jev hỏi liệu lệnh gọi có thay đổi và liệu mục tiêu có phải là sản xuất hay không. | +| `block-terraform` | có thể xem xét | `production-infra-change` | Giống như: xóa `terraform plan` và `validate`. | +| `block-aws-cli` | có thể xem xét | `production-infra-change` | Giống như: xóa `aws s3 ls`, `aws sts get-caller-identity`. | +| `block-gcloud` | có thể xem xét | `production-infra-change` | Giống như: xóa `gcloud auth list`, `gcloud config list`. | +| `block-az-cli` | có thể xem xét | `production-infra-change` | Giống như: xóa `az account show`. | +| `block-helm` | có thể xem xét | `production-infra-change` | Giống như: xóa `helm list`, `helm status`. | +| `block-gh-pipeline` | cứng | | Kích hoạt đường ống, hợp nhất và thay đổi bí mật. | +| `warn-git-stash-drop` | cứng | | Không có kiểm tra ngữ nghĩa nào bao gồm loại bỏ công việc được lưu trữ. | +| `warn-git-clean` | cứng | | `destructive-deletion` bao gồm mối quan tâm nhưng rõ ràng không thể kích hoạt trên nó: `git clean` không đặt tên đường dẫn, vì vậy kiểm tra `irreplaceable` của nó không có gì để đánh giá và trả lời thấp, và bằng chứng là mức tối thiểu trên các kiểm tra của chính sách. Kiểm tra được hỏi và không kích hoạt xóa phán quyết, vì vậy ghép nối ở đây sẽ chuyển chính sách tắt. | +| `warn-all-files-staged` | cứng | | Không có kiểm tra ngữ nghĩa nào bao gồm những gì rộng `git add` chọn. | +| `warn-schema-alteration` | cứng | | `database-destruction` bao gồm thả dữ liệu, không thay đổi lược đồ. | +| `warn-package-publish` | cứng | | Xuất bản không thể hoàn tác và không có kiểm tra ngữ nghĩa nào bao gồm nó. | +| `prefer-package-manager` | cứng | | Một quy ước nhóm, không phải phán quyết an toàn. | +| `warn-large-file-write` | cứng | | Một ngưỡng kích thước, không phải phán quyết Jev có thể đưa ra. | +| `warn-background-process` | cứng | | Không có kiểm tra ngữ nghĩa nào bao gồm quá trình tách rời. | +| `warn-repeated-tool-calls` | cứng | | Đếm lệnh gọi; Jev không thể đếm. | +| `sanitize-jwt` | cứng | | Redact đầu ra công cụ; không phải cổng lệnh gọi công cụ. | +| `sanitize-api-keys` | cứng | | Redact đầu ra công cụ; không phải cổng lệnh gọi công cụ. | +| `sanitize-connection-strings` | cứng | | Redact đầu ra công cụ; không phải cổng lệnh gọi công cụ. | +| `sanitize-private-key-content` | cứng | | Redact đầu ra công cụ; không phải cổng lệnh gọi công cụ. | +| `sanitize-bearer-tokens` | cứng | | Redact đầu ra công cụ; không phải cổng lệnh gọi công cụ. | +| `require-commit-before-stop` | cứng | | Cổng hoàn thành phiên, không phải cổng lệnh gọi công cụ. | +| `require-push-before-stop` | cứng | | Cổng hoàn thành phiên, không phải cổng lệnh gọi công cụ. | +| `require-pr-before-stop` | cứng | | Cổng hoàn thành phiên, không phải cổng lệnh gọi công cụ. | +| `require-no-conflicts-before-stop` | cứng | | Cổng hoàn thành phiên, không phải cổng lệnh gọi công cụ. | +| `require-ci-green-before-stop` | cứng | | Cổng hoàn thành phiên, không phải cổng lệnh gọi công cụ. | + +## Tên chính sách ngữ nghĩa + +Đây là những kiểm tra `FailproofAI/jev-policies` khai báo, và những giá trị `reviewedBy` chấp nhận khi nó được cài đặt. Failproof AI không có bất kỳ kiểm tra nào: không có gói đó (hoặc gói khác khai báo những tên này), không có chính sách đặt tên chúng là có thể xem xét. Mỗi kiểm tra là một kiểm tra Jev trả lời về lệnh gọi công cụ phía trước nó. **Chế độ** là những gì kiểm tra có thể trả lời: kiểm tra `deny` chặn trên bằng chứng mạnh, trong khi kiểm tra `instruct` chỉ cảnh báo. Cả hai giữ phán quyết từ chối của chính sách khi nó kích hoạt và người dùng không yêu cầu lệnh gọi. **Người dùng có thể ghi đè** cho biết liệu yêu cầu tường minh của chính con người có xóa nó hay không. + +Jev hỏi chính xác [kiểm tra Jev](/vi/policies/publish-a-pack#jev-checks-in-a-pack) mà gói đã cài đặt khai báo, và đó là những tên `reviewedBy` chấp nhận. Tên hai gói khai báo khác nhau không được vinh danh cho tên nào. Một trong mười sáu tên này được khai báo bởi gói không được cài đặt từ kho lưu trữ FailproofAI bị bỏ qua trong gói đó: phiên bản của nó không bao giờ được hỏi và không tranh cãi với phiên bản của FailproofAI, vì vậy gói của bên thứ ba không thể trở thành kiểm tra xóa chính sách gói lõi của nó cũng không chuyển một trong những kiểm tra này tắt. Danh sách gói không thể đọc được, hoặc gói mà mỗi kiểm tra không thể sử dụng được, để Jev không hỏi gì. + +| Tên | Chế độ | Người dùng có thể ghi đè | Jev kiểm tra cái gì | +| --- | --- | --- | --- | +| `destructive-deletion` | từ chối | có | Xóa vĩnh viễn dữ liệu không thể tái tạo được. | +| `production-infra-change` | từ chối | có | Thay đổi cơ sở hạ tầng trực tiếp. | +| `git-history-rewrite` | từ chối | có | Viết lại hoặc loại bỏ lịch sử git được chia sẻ. | +| `push-to-protected-branch` | hướng dẫn | có | Đẩy trực tiếp vào nhánh được bảo vệ. | +| `commit-on-protected-branch` | hướng dẫn | có | Commit trực tiếp trên nhánh được bảo vệ. | +| `secret-exposure` | từ chối | có | Đọc hoặc sao chép thông tin xác thực. | +| `credential-exfiltration` | từ chối | không | Gửi bí mật hoặc tệp riêng tư ra ngoài máy. | +| `remote-code-execution` | từ chối | có | Chạy mã được tải xuống từ internet. | +| `privilege-escalation` | từ chối | có | Chạy với quyền nâng cao. | +| `database-destruction` | từ chối | có | Phá hủy hoặc sửa đổi hàng loạt dữ liệu cơ sở dữ liệu. | +| `read-outside-workspace` | hướng dẫn | có | Đọc tệp bên ngoài dự án. | +| `agent-config-tampering` | từ chối | không | Thay đổi cấu hình an toàn của chính tác nhân. | +| `system-modification` | hướng dẫn | có | Thay đổi hệ thống bên ngoài dự án. | +| `env-secrets-dump` | hướng dẫn | có | In các bí mật môi trường. | +| `external-destructive-action` | từ chối | có | Hành động không thể hoàn tác thông qua công cụ bên ngoài. | +| `external-data-egress` | hướng dẫn | có | Gửi dữ liệu riêng tư tới công cụ bên ngoài. | \ No newline at end of file diff --git a/docs/vi/policies/jev-byok.mdx b/docs/vi/policies/jev-byok.mdx new file mode 100644 index 000000000..f1f7851be --- /dev/null +++ b/docs/vi/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev evaluator (đưa khóa của riêng bạn)" +description: "Để trình phân loại Jev của TypeSafe đánh giá các lệnh gọi công cụ của agent vượt quá giới hạn regex cứng, thông qua điểm cuối Jev và khóa của riêng bạn." +icon: "key-round" +--- + +Các chính sách regex khớp chuỗi. Chúng không thể phân biệt `rm -rf build/` mà bạn yêu cầu với `rm -rf ~` bị lọt vào kế hoạch, vì vậy chúng chặn quá nhiều ở một chỗ và quá ít ở chỗ khác. **Jev**, trình phân loại của TypeSafe, đọc lệnh gọi so với những gì bạn thực sự yêu cầu và trả lời một tập hợp các câu hỏi có/không về nó trong một yêu cầu nhanh. + +Với điểm cuối Jev và khóa của riêng bạn được cấu hình, Failproof AI hỏi Jev về mỗi lệnh gọi công cụ **cùng với** các chính sách regex, chứ không phải thay vì chúng: + +- Một phủ định chính sách **cứng** là cuối cùng. Jev không thể xóa nó. Mọi chính sách đều cứng trừ khi được đánh dấu rõ ràng là có thể xem xét và đặt tên các kiểm tra Jev bao gồm nó, vì vậy chính sách tùy chỉnh, gói hoặc Cloud mà không nói gì là cứng, và bảo vệ tự động lúc nào cũng cứng. +- Một phủ định chính sách **có thể xem xét** có thể bị xóa, nhưng chỉ khi Jev được hỏi về mối quan tâm chính xác mà chính sách đó bao gồm và trả lời "không có gì ở đây" hoặc "người dùng yêu cầu điều này". Một kiểm tra phát hiện mối quan tâm là thực, khi người dùng không yêu cầu lệnh gọi, giữ phủ định — ngay cả khi phán quyết của nó chỉ là một cảnh báo, vì trước khi gọi công cụ một cảnh báo không dừng agent. Và khi kiểm tra đó là một kiểm tra có thể phủ định (tiếp xúc bí mật, exfiltration thông tin xác thực, xóa hủy diệt, …), không có gì được xóa trên lệnh gọi đó. +- Một khối vẫn có thể trở thành **cảnh báo** khi lệnh gọi là một bước của nhiệm vụ bạn đưa ra và không đi xa hơn: Jev làm mềm phủ định của nó thành cảnh báo, và cảnh báo đó — đặt tên những gì thực sự sai với lệnh gọi — thay thế khối của chính sách. +- Jev cũng có thể cảnh báo hoặc phủ định trên riêng mình, vì những tổn hại mà regex không mô tả. +- Nếu Jev không thể trả lời (timeout, giới hạn tốc độ, lỗi máy chủ, không có tín dụng, phiên bản mô hình không mong đợi), lệnh gọi đó nhận kết quả regex, chính xác như không có Jev. +- Jev không bao giờ làm cho lệnh gọi cho phép hơn các chính sách của bạn trừ khi nó đọc toàn bộ lệnh gọi và được hỏi về mối quan tâm chính xác. Bất cứ điều gì ít hơn — một lệnh gọi quá lớn để gửi toàn bộ, một injection được nghi ngờ — rút lại các miễn cấp và giữ mọi phủ định. + + +Không có cấu hình Jev thì không có gì thay đổi: các hook chạy các chính sách regex chính xác như họ luôn làm. Cấu hình là toàn bộ opt-in. + + + +Trên FailproofAI Cloud? Bạn không cần khóa của riêng bạn: một máy được kết nối với khóa mang `jev:evaluate` có thể sử dụng Jev trên kế hoạch của tổ chức bạn. Xem [Jev thông qua FailproofAI Cloud](/vi/policies/jev-cloud). + + +## Chọn nhà cung cấp + +Jev có thể tiếp cận thông qua năm tuyến đường. Mang khóa cho bất kỳ một trong số chúng. + +| Nhà cung cấp | `--provider` | Điểm cuối | Mô hình mặc định | Ghi chú | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Ghim phiên bản chính xác. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Yêu cầu được định tuyến đến các điểm cuối chỉ nắm giữ không dữ liệu, không có dự phòng cho nhà cung cấp khác. Báo cáo phiên bản được đánh ngày như `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Chỉ đặt tên Jev bằng bí danh, vì vậy phiên bản trả lời được ghi lại là chưa được xác minh. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Cần `--account-id`. Khoảng sáu lệnh gọi mỗi giây trên mỗi khóa được đo trước HTTP 429. | +| Điểm cuối của riêng bạn | `custom` | `/systemone` | `jev-1.13.0` | Bất kỳ điểm cuối nào chấp nhận phần thân yêu cầu của TypeSafe và báo cáo mô hình nào đã trả lời. Chỉ `https`; `http://localhost` dưới dạng yên tĩnh được chấp nhận chỉ ở chế độ bóng. | + + +Với tính năng đưa khóa của riêng bạn của Vercel, một yêu cầu không thành công sẽ được thử lại im lặng với thông tin xác thực của Vercel. Nếu bạn cần mọi lệnh gọi được tính phí cho và nhìn thấy bởi tài khoản TypeSafe của riêng bạn, hãy sử dụng TypeSafe trực tiếp. + + +## Thiết lập nó + +Một lệnh, điểm cuối và khóa: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL chọn nhà cung cấp + +Bạn không phải đặt tên nhà cung cấp: **máy chủ** của URL là cái nào. + +| Máy chủ URL | Nhà cung cấp | Cũng cần | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| máy chủ khác bất kỳ | `custom` | — URL bạn đưa ra là URL cơ sở | + +Ba điều theo sau từ đó: + +- **Một URL là API của chính nhà cung cấp không viết ghi đè.** `--url https://api.typesafe.ai/v1` tạo ra chính xác cấu hình mà `--provider typesafe` sẽ tạo ra. Đưa ra một đường dẫn hoặc máy chủ khác trên nhà cung cấp đã biết và nó được lưu trữ dưới dạng URL cơ sở, như `--base-url` sẽ lưu trữ nó. +- **`--provider` vẫn ghi đè suy luận**, đó là cách bạn đạt được proxy nói API của nhà cung cấp từ máy chủ của riêng bạn: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Một `--provider` mâu thuẫn với máy chủ bị từ chối**, không được đoán. `--provider openrouter --url https://api.typesafe.ai/v1` không viết gì và nói tại sao: hai cách viết không đồng ý về nơi khóa của bạn sắp được gửi đến. Cặp đó cũng bị từ chối từ `jev setup --base-url` và từ cài đặt Jev của bảng điều khiển. (`--provider custom` không phải là mâu thuẫn — nó có nghĩa là "coi URL này là chính nó" — ngoại trừ trên máy chủ của Cloudflare, mà một tuyến đường tùy chỉnh không thể đạt được điểm cuối cho mỗi tài khoản.) + +`--url` được xác thực chính xác như `baseUrl` trong tệp cấu hình, và bị từ chối với các từ giống nhau: `https`, hoặc `http://localhost` dưới dạng yên tĩnh chỉ ở chế độ bóng. + +### Khóa + +Đưa nó vào với `--key-stdin`, hoặc chạy lệnh trong terminal mà không có nó và dán khóa ở lời nhắc được che khuất. Dù bằng cách nào nó cũng đi thẳng vào tệp cấu hình và không bao giờ được in lại. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` lấy các flag giống nhau và là hình thức dài tay cho tất cả nó: `setup --provider ` nơi bạn muốn đặt tên nhà cung cấp hơn là URL. + +### `--token`, và nó có giá là bao nhiêu + +`--token ` đặt khóa trên dòng lệnh, đó là cách nhanh nhất để cấu hình máy và cách viết duy nhất để để khóa ở bất kỳ nơi nào ngoài tệp cấu hình: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Một đối số dòng lệnh nằm trong tệp lịch sử của shell bạn sau đó, và khi lệnh chạy nó nằm trong danh sách quy trình — có thể đọc được từ `/proc` bởi bất cứ điều gì chạy như bạn. `setup` nói như vậy mỗi khi `--token` được sử dụng. Thích `--key-stdin` trên máy bạn chia sẻ, trong phiên ghi, hoặc ở bất kỳ nơi nào tệp lịch sử được đồng bộ; xoay khóa bạn đã chuyển qua theo cách này nếu nó quan trọng. + + +`--token`, `--key-stdin` và `--key-from-env` loại trừ lẫn nhau: cung cấp một. + +Sau đó gửi một yêu cầu trực tiếp nhỏ để kiểm tra khóa, điểm cuối và Jev nào đã trả lời: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` thoát 1, và nói như vậy trong tiêu đề của nó, khi câu trả lời đến sau timeout (mỗi hook sẽ quay lại regex là `timeout`) hoặc trả lời câu hỏi kiểm tra của nó sai. + +Hooks đọc cấu hình trên mỗi lệnh gọi công cụ, vì vậy nó áp dụng từ cái tiếp theo. Không có gì để khởi động lại, có hoặc không có daemon. + +## Kiểm tra nó đang làm gì + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` hiển thị nhà cung cấp, điểm cuối, mô hình, chế độ, tệp cấu hình và các quyền của nó, và không bao giờ khóa. Dưới đó nó tóm tắt hoạt động gần đây: Jev đã đánh giá bao nhiêu lệnh gọi, nó quay lại regex bao thường lần và tại sao, độ trễ của nó, và chính sách có thể xem xét nào nó đã xóa. + +## Chế độ bóng + +`enforce` là mặc định. Để xem Jev mà không để nó thay đổi bất kỳ quyết định nào, chuyển sang `shadow`: Jev vẫn được hỏi và các phán quyết của nó được ghi lại, nhưng kết quả regex là những gì được thực thi. + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` giữ cấu hình — điểm cuối và khóa — và dừng hỏi Jev: hooks chạy các chính sách regex chính xác như không có cấu hình, và `failproofai jev status` nói "off (switched off)". Chuyển lại với `--mode shadow` hoặc `--mode enforce`. + +Chạy lại `setup` cho cùng nhà cung cấp giữ khóa được lưu trữ, vì vậy chuyển đổi chế độ là một flag. Nhà cung cấp chuyển đổi bắt đầu lại và yêu cầu khóa của nhà cung cấp đó. `--base-url` cũng vậy nếu nó di chuyển yêu cầu đến máy chủ khác: khóa được lưu trữ chỉ được gửi đến máy chủ nó được đưa ra, hoặc đến API của chính nhà cung cấp của nó. + +## Tệp cấu hình + +Mọi thứ nằm trong một tệp, `~/.failproofai/jev.json`, được viết bởi `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Trường | Ý nghĩa | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` hoặc `custom` — hoặc `failproofai`, mà khóa của nó đến từ kết nối FailproofAI Cloud thay vì tệp này (xem [Jev thông qua FailproofAI Cloud](/vi/policies/jev-cloud)). | +| `apiKey` | Được gửi dưới dạng `Authorization: Bearer `. | +| `baseUrl` | Bắt buộc cho `custom`; thay thế cơ sở API của nhà cung cấp ngoài ra. Phải là `https`. Đơn `http` đến `localhost` chỉ được chấp nhận với `mode: shadow`: không có gì xác thực cổng cục bộ, vì vậy khi proxy của bạn bị down bất kỳ quy trình nào trên máy, bao gồm agent đang bị phán quyết, có thể trả lời thay cho nó. | +| `accountId` | Chỉ Cloudflare: 32 ký tự hex chữ thường. | +| `model` | Thay thế id mô hình mặc định của nhà cung cấp. Một id có phiên bản phải đặt tên Jev 1.13. Một giá trị hình dạng như khóa API bị từ chối (và không được lặp lại), vì vậy khóa dán vào `--model` không bao giờ được lưu trữ hoặc gửi dưới dạng mô hình. | +| `timeoutMs` | Lâu bao lâu một lệnh gọi công cụ chờ Jev trước khi sử dụng kết quả regex. 100–10000, mặc định 3000. | +| `mode` | `enforce` (mặc định), `shadow`, hoặc `off` (giữ cấu hình, không chạy Jev). | + +Ba quy tắc bảo vệ nó: + +- **Chỉ chủ sở hữu.** Nó được viết với quyền `0600`. Bản sao mà bất kỳ người dùng hoặc nhóm nào khác có thể đọc hoặc viết bị **từ chối**, và hooks quay lại regex cho đến khi bạn chạy `chmod 600 ~/.failproofai/jev.json` hoặc `setup` lại. Thư mục cũng được kiểm tra: `~/.failproofai` không được **ghi** bởi bất kỳ người nào khác, vì ai cũng có thể ghi ở đó có thể thay thế tệp bất kỳ quyền của nó. `setup` tắt các bit ghi đó nếu tìm thấy. `failproofai jev status` nói khi cấu hình bị từ chối và hiển thị điểm cuối tệp đặt tên: có người khác có thể đã thay đổi nó, vì vậy hãy kiểm tra nó là của bạn trước khi bạn `chmod`. Chạy lại `setup` trên tệp như vậy chỉ mang khóa được lưu trữ của nó đến API của chính nhà cung cấp; bất kỳ điểm cuối nào khác nó đặt tên cần khóa lại (`--key-stdin`), hoặc `--base-url default` để gửi yêu cầu trở lại nhà cung cấp. +- **Toàn cầu chỉ.** Một kho lưu trữ không thể bật Jev, chỉ nó ở điểm cuối khác hoặc chọn mô hình của nó: một `.failproofai/jev.json` bên trong dự án bị bỏ qua, và nhà cung cấp, URL, mô hình và id tài khoản chỉ được đọc từ tệp đó — không bao giờ từ môi trường, mà cài đặt agent của kho lưu trữ có thể đặt. (`FAILPROOFAI_HOME` không phải là cách xung quanh đó: nó di chuyển toàn bộ thư mục failproofai, chính sách của bạn bao gồm, thay vì chỉ chuyển hướng Jev.) +- **Chỉ khóa có thể đến từ môi trường.** Nếu tệp không có `apiKey`, `FAILPROOFAI_JEV_API_KEY` cung cấp nó cho phiên đó (`setup --key-from-env` viết tệp như vậy). Nó không bao giờ thay thế khóa tệp giữ, và nó không thể bật Jev mà không tệp. Nơi biến không được đặt, Jev chỉ là tắt cho shell đó: `failproofai jev status` nói như vậy, thoát 0 và để cấu hình một mình (`status --json` báo cáo `"status": "key-missing"` với `"reason": "no-env-key"`). Daemon `failproofaid` không nhìn thấy môi trường shell của bạn, vì vậy trên máy được thiết lập với `failproofai config`, giữ khóa trong tệp. + +## Jev nào trả lời + +Ngưỡng quyết định của Failproof AI được hiệu chỉnh trên Jev 1.13, vì vậy câu trả lời chỉ được sử dụng khi nó đến từ gia đình đó: `jev-1.13.x`, hoặc OpenRouter's `typesafe/jev-1.13-`. Nơi nhà cung cấp chỉ đặt tên Jev bằng bí danh và không báo cáo phiên bản (Vercel, và Cloudflare khi nó không nói), câu trả lời được sử dụng và ghi lại là chưa được xác minh. Điểm cuối `custom` phải báo cáo mô hình đã trả lời; ngoại lệ duy nhất là tên `--model` không có phiên bản bạn cấu hình cho nó, nó, được phát lại, được ghi lại là chưa được xác minh theo cách tương tự. Một câu trả lời báo cáo bất kỳ phiên bản nào khác, hoặc câu trả lời `custom` không báo cáo bất kỳ cái nào, không được sử dụng: lệnh gọi đó quay lại regex với lý do `model-mismatch`. + +## Khi Jev không thể trả lời + +Mỗi cái này quay lại kết quả regex cho lệnh gọi đó và được ghi lại với lý do của nó, mà `failproofai jev status` tổng cộng: + +| Lý do | Nguyên nhân | +| --- | --- | +| `timeout` | Không có câu trả lời trong `timeoutMs`. | +| `http-429` | Nhà cung cấp đã giới hạn tốc độ khóa. | +| `rate-limited` | Bộ giới hạn riêng của Failproof AI đã giữ lệnh gọi trước khi gửi nó: 5 yêu cầu mỗi giây, trong loạt tối đa 5, và không có gì trong một khoảnh khắc sau khi nhà cung cấp trả lời `429`. Không phải nhà cung cấp. | +| `http-500`, `http-502`, `http-503`, … | Lỗi máy chủ tại nhà cung cấp. Trạng thái chính xác được ghi lại. | +| `out-of-credits` | HTTP 402: tài khoản nhà cung cấp không có tín dụng còn lại. | +| `provider-refused` | HTTP 402 từ Cloudflare đọc "Model execution failed (Payment error)": nhà cung cấp từ chối chạy mô hình trên yêu cầu này. Thường không phải hóa đơn, vì vậy bổ sung sẽ không di chuyển nó. | +| `http-401`, `http-403` | Khóa bị từ chối. | +| `http-404` | Không có gì được phục vụ tại `/systemone`, vì vậy URL cơ sở sai — `/systemone` được thêm vào nó, và mỗi nhà cung cấp phục vụ nó tại gốc phiên bản của nó. `failproofai jev models` hiển thị những gì điểm cuối làm phục vụ. | +| `network` | Không thể tiếp cận được điểm cuối. | +| `http-301`, `http-302`, `http-307`, `http-308` | Điểm cuối trả lời với chuyển hướng. Chuyển hướng không bao giờ được theo dõi, vì vậy câu trả lời chỉ bao giờ đến từ URL trong cấu hình của bạn; đặt `--base-url` thành URL cuối cùng. | +| `malformed` | Điểm cuối trả lời, nhưng không phải với câu trả lời Jev — phần thân không phải JSON, hoặc một với không có câu trả lời trong nó. | +| `cloudflare-error`, `cloudflare-incomplete` | Phong bì của Cloudflare báo cáo một thất bại, hoặc một công việc chưa hoàn thành. | +| `model-mismatch` | Phiên bản Jev khác 1.13 đã trả lời, hoặc điểm cuối `custom` không nói mô hình nào đã trả lời. | +| `request-cut` | **Không phải mất điện.** Jev trả lời; nó chỉ được hiển thị một phần của lệnh gọi, vì vậy câu trả lời của nó không xóa gì. Xem [Khi Jev trả lời, nhưng không phải trên toàn bộ lệnh gọi](#when-jev-answered-but-not-on-the-whole-call). | + +`failproofai jev status` có thể hiển thị một vài lý do hiếm hơn, chẳng hạn như `upstream-error` (câu trả lời mang lỗi của chính nhà cung cấp) hoặc `config`, và tổng cộng bất kỳ lý do nào mà nó không thể đặt tên là `other`. + +`request-cut` nằm trong bảng này vì `failproofai jev status` tổng cộng nó với phần còn lại, và vì nó cũng để mỗi phủ định đứng. Đó là lý do duy nhất ở đây không nói gì về nhà cung cấp của bạn: yêu cầu đã đến và Jev trả lời nó. Không giống như mọi hàng phía trên nó, câu trả lời đó vẫn tính — phủ định hoặc cảnh báo của Jev áp dụng trên top kết quả regex thay vì bị loại bỏ. Vì vậy lần chạy của chúng có nghĩa là lệnh gọi đang tiếp cận bộ đánh giá quá lớn để gửi toàn bộ, không phải điểm cuối của bạn không khỏe mạnh, và bổ sung tín dụng hoặc thay đổi URL sẽ không di chuyển số. + +## Khi Jev trả lời, nhưng không phải trên toàn bộ lệnh gọi + +Hai điều nữa có thể xảy ra, và không ai là Jev không trả lời. Cả hai đều về bao nhiêu lệnh gọi, hoặc cuộc trò chuyện, vừa vào một yêu cầu. + +**Một phần của lệnh gọi chính nó không vừa.** Một lệnh gọi công cụ được gửi bên trong ngân sách cố định, và một cái lớn — một `Write` rất lớn, phần thân MCP khổng lồ, lệnh đệm để lên tập — được gửi với những gì vừa. Jev vẫn trả lời, và câu trả lời của nó vẫn tính: phủ định hoặc cảnh báo của nó áp dụng như thường lệ. Những gì nó không thể làm là **xóa** bất cứ điều gì, vì phán quyết được đưa ra trên một phần của lệnh gọi không phải là phán quyết về lệnh gọi. Vì vậy mỗi phủ định chính sách đứng, và lệnh gọi được ghi lại là một dự phòng với lý do `request-cut`, mà `failproofai jev status` tổng cộng cùng với những lý do ở trên. Quy tắc này cung cấp cho bạn: làm cho lệnh gọi lớn hơn có thể làm nó mất các miễn cấp của nó, và không bao giờ có thể mua một. + +**Một tin nhắn không vừa.** Một lời nhắc dài bạn dán, tin nhắn cuối cùng của agent, hoặc lời nhắc bộ đánh giá này của riêng nó đã cấp. **Không có gì thay đổi**: lệnh gọi được phán quyết, xóa và ghi lại chính xác như bất kỳ cái nào khác, và nó không được tính là dự phòng. Độ dài của những gì bạn gõ không bao giờ quyết định phán quyết, và một cắt không thể tạo ra sự đồng ý: nơi một lời nhắc đã đến được cấp, "bạn đã không yêu cầu điều này" ngừng là kết luận có thể được rút ra từ nó ở tất cả, thay vì trở thành một. + +Đường ranh giới giữa hai là ai đã viết văn bản. Lệnh gọi là của agent, và một quy tắc để dài của nó trừ đi mức độ nghiêm trọng sẽ là quy tắc agent có thể sử dụng; lời nhắc của bạn là của bạn, và coi độ dài của nó là tín hiệu chỉ bao giờ bị phạt dán một spec hoặc stack trace. + +## Cái gì rời khỏi máy + +Cho mỗi lệnh gọi công cụ Jev đánh giá, một yêu cầu đi đến nhà cung cấp của bạn, mang: + +- lệnh gọi công cụ chính nó, với bí mật như khóa API, mã thông báo mang và các gán `KEY=` được biên tập lại; +- các lời nhắc gần đây bạn đã gõ, với văn bản harness của agent bạn đã thêm bị xóa; +- tin nhắn cuối cùng của agent trước lời nhắc cuối cùng của bạn, được dán nhãn là agent-viết; +- sự thật được tính toán cục bộ, chẳng hạn như liệu một đường dẫn nằm bên trong dự án — cái mà phiên được ở lần gọi được xem xét đầu tiên, [ghim cho phiên](/vi/reference/jev-intent#the-project-root) — và chi nhánh git hiện tại. + +Nó đi chỉ đến điểm cuối trong cấu hình của bạn, dưới khóa của bạn. + +## Tắt nó + +```bash +failproofai jev remove +``` + +Điều này xóa `~/.failproofai/jev.json`. Từ lệnh gọi công cụ tiếp theo, hooks chạy các chính sách regex chính xác như trước. Các cửa hàng per-session dưới `~/.failproofai/state/semantic/` (lời nhắc được ghi lại trong `sessions/`, gốc dự án trong `roots/`) được để lại và tuổi ra. Để dừng hỏi Jev nhưng giữ cấu hình, hãy sử dụng `failproofai jev setup --mode off` thay thế. + +## Tham chiếu lệnh + +| Lệnh | Kết quả | +| --- | --- | +| `failproofai jev --url --key-stdin` | Cấu hình nó trong một lệnh; nhà cung cấp đến từ máy chủ của URL | +| `failproofai jev --url --token ` | Giống nhau, với khóa trên dòng lệnh — lịch sử của bạn và danh sách quy trình xem nó | +| `failproofai jev setup --provider --key-stdin` | Viết cấu hình từ khóa piped trên stdin | +| `failproofai jev setup --provider ` | Giống nhau, yêu cầu khóa ở lời nhắc được che khuất | +| `failproofai jev setup --key-from-env` | Không lưu trữ khóa; đọc `FAILPROOFAI_JEV_API_KEY` mỗi phiên | +| `failproofai jev setup --mode shadow` | Chuyển đổi chế độ (`enforce`, `shadow` hoặc `off`), giữ khóa được lưu trữ | +| `failproofai jev setup --model ` / `--base-url ` | Ghi đè mô hình hoặc cơ sở API; `default` xóa ghi đè | +| `failproofai jev setup --timeout-ms ` | Thay đổi ngân sách per-call | +| `failproofai jev status [--json]` | Cấu hình, quyền và hoạt động gần đây; không bao giờ khóa | +| `failproofai jev test [--json]` | Một yêu cầu trực tiếp: độ trễ và phiên bản đã trả lời | +| `failproofai jev models [--provider ] [--url ] [--json]` | Các id mô hình mà `/models` của điểm cuối báo cáo, đánh dấu cái được cấu hình | +| `failproofai jev remove` | Xóa cấu hình; Jev tắt | \ No newline at end of file diff --git a/docs/vi/policies/jev-cloud.mdx b/docs/vi/policies/jev-cloud.mdx new file mode 100644 index 000000000..b76f4fc39 --- /dev/null +++ b/docs/vi/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "Jev thông qua FailproofAI Cloud" +description: "Cho phép Jev đánh giá các lệnh gọi công cụ của agents của bạn thông qua FailproofAI Cloud, theo gói của tổ chức của bạn, mà không cần tài khoản hoặc khóa TypeSafe của riêng bạn." +icon: "cloud" +--- + +[Jev](/vi/policies/jev-byok), bộ phân loại của TypeSafe, đọc từng lệnh gọi công cụ so với những gì bạn thực sự yêu cầu và trả lời cùng với các chính sách của bạn, không bao giờ thay thế chúng. Thông qua **FailproofAI Cloud**, một máy được kết nối sử dụng Jev với cùng một khóa mà nó đã kết nối: không cần tài khoản TypeSafe, không cần khóa thứ hai, không cần điểm cuối để cấu hình. Mỗi lệnh gọi được tính phí vào hạn mức gói hiện có của tổ chức bạn. + +Mọi thứ Jev làm đều không thay đổi so với [cài đặt mang theo khóa của riêng bạn](/vi/policies/jev-byok): các chính sách cứng vẫn là quyết định cuối cùng, việc từ chối của một chính sách có thể xem xét được chỉ được xóa khi Jev được hỏi về chính xác những mối quan tâm đó, và bất kỳ lỗi nào cũng quay lại kết quả regex cho lệnh gọi đó. + + +Yêu cầu **failproofai 1.0.8-beta.0** hoặc mới hơn. 1.0.7 không có Jev, mặc dù nó sắp xếp phía trên các phiên bản beta 1.0.7. Nếu không có cấu hình Jev, không có gì thay đổi: hooks chạy các chính sách regex chính xác như họ luôn làm. + + +## Bật nó + +1. **Tạo một khóa với Jev.** Trong bảng điều khiển FailproofAI Cloud, hãy mở **Keys → Create key** và chọn cài đặt **machine**. Nó cấp ba quyền mà một máy cần: `events:add` (gửi hoạt động), `policies:pull` (nhận chính sách) và `jev:evaluate` (Jev, được tính phí vào gói của tổ chức của bạn). Một khóa không thể mang `jev:evaluate` mà không có hai khóa còn lại. +2. **Kết nối máy** với khóa đó: + + ```bash + failproofai config --token + ``` + + Nếu tổ chức của bạn chạy FailproofAI Cloud riêng của nó thay vì cái được lưu trữ, hãy thêm địa chỉ của nó: `--url https://` (hoặc xuất `FAILPROOFAI_CLOUD_URL`). Nếu không có nó, khóa được kiểm tra so với dịch vụ được lưu trữ và kết nối không thành công. Nếu chứng chỉ của máy chủ đó đến từ một CA riêng, hãy cài đặt CA vào kho tin cậy hệ thống của máy (ví dụ với `update-ca-certificates`), không chỉ trong `NODE_EXTRA_CA_CERTS`: daemon gửi sự kiện và lấy chính sách đọc kho hệ thống. Xem [Troubleshooting](/vi/reference/troubleshooting). + +Đó là tất cả. Kết nối lưu trữ khóa và, khi máy **không** có cấu hình Jev, sẽ bật Jev thông qua FailproofAI Cloud ở chế độ **shadow**: Jev được hỏi về mỗi lệnh gọi công cụ được gated và các phán quyết của nó được ghi lại, nhưng kết quả của các chính sách của bạn là những gì được thực thi. Đầu ra nói như vậy: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**Với `--no-transcripts`, kết nối không bật Jev.** Jev gửi từng lệnh gọi công cụ được kiểm tra và prompt gần đây tới FailproofAI Cloud, có nhiều hơn một kết nối chỉ quyết định được yêu cầu gửi. Khóa vẫn được lưu trữ, và đầu ra nói rằng Jev có sẵn và cách bật nó: + +```bash +failproofai jev setup --provider failproofai +``` + +Nó cũng không tắt Jev. Nếu `jev.json` của máy đã chạy Jev thông qua FailproofAI Cloud, nó được để nguyên như vậy, và đầu ra nói rằng Jev vẫn gửi từng lệnh gọi công cụ được kiểm tra và prompt gần đây, và rằng `failproofai jev setup --mode off` tắt nó. + + +Kết nối **không bao giờ ghi đè** một `~/.failproofai/jev.json` hiện có. Nếu bạn đã sử dụng điểm cuối Jev của riêng mình, nó tiếp tục được sử dụng, và đầu ra nói rằng tệp được để lại như đã cấu hình — và, khi tệp đó để Jev tắt (từ chối hoặc tắt), nói như vậy và cách khắc phục nó. Để chuyển máy đó sang FailproofAI Cloud, hãy chạy `failproofai jev setup --provider failproofai`. + + +## Shadow, enforce hoặc off + +Bắt đầu ở shadow, xem những gì Jev đã làm trên trang chính sách, sau đó để nó hoạt động: + +```bash +failproofai jev setup --mode enforce # Các phán quyết của Jev được áp dụng: nó có thể xóa một từ chối có thể xem xét được và thêm của riêng nó +failproofai jev setup --mode shadow # Jev được hỏi và ghi lại; kết quả của các chính sách của bạn được thực thi +failproofai jev setup --mode off # giữ lại cấu hình, dừng yêu cầu Jev +``` + +Công tắc tương tự cũng có trong bảng điều khiển cục bộ: **Settings → Jev** có công tắc bật/tắt và shadow/enforce. Nó viết lại chế độ và không có gì khác. Hooks đọc cấu hình trên mỗi lệnh gọi công cụ, vì vậy một thay đổi được áp dụng từ lệnh gọi tiếp theo, không cần khởi động lại. + +## Kiểm tra những gì nó đang làm + +```bash +failproofai jev status +failproofai jev test +``` + +`status` hiển thị nhà cung cấp là **FailproofAI Cloud**, máy chủ Cloud mà máy kết nối đến, chế độ và nguồn khóa là **FailproofAI Cloud connection**, không bao giờ là khóa. Khi `jev.json` của FailproofAI Cloud đã sẵn sàng nhưng Jev không thể chạy, nó nói lý do tại sao: + +| `status` nói | `status --json` | Ý nghĩa | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | Máy được kết nối, nhưng không có khóa Jev được lưu trữ cho nó: khóa thiếu `jev:evaluate`, hoặc kết nối không thể xác nhận nó. Chạy `failproofai config --token ` lại với cùng một khóa; nếu nó thiếu quyền, hãy sử dụng khóa **machine**. | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | Không có kết nối FailproofAI Cloud trên máy này để khóa Jev thuộc về. | + +Sau `failproofai config --disconnect`, không còn `jev.json` FailproofAI Cloud nữa (trừ khi nó bị tắt, được giữ lại), vì vậy `status` đơn giản báo cáo Jev là tắt. `status --json` mang cùng một sự kiện (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), cũng khi cấu hình bị mất hoặc từ chối. `permissions` luôn là của `jev.json`; một từ chối về `credentials.json` thêm `credentialsPermissions`, và `fix` khi một lệnh khắc phục nó. `test` gửi một yêu cầu trực tiếp và báo cáo độ trễ và phiên bản Jev đã trả lời. Nó thoát 1, và nói như vậy trong tiêu đề của nó, khi câu trả lời đến sau thời gian chờ của hook (hooks sẽ ghi lại `timeout`) hoặc trả lời câu hỏi kiểm tra của nó sai. + +Bảng điều khiển **Settings → Jev** cũng hiển thị **FailproofAI Cloud connection**: máy báo cáo đến tổ chức nào và liệu khóa của nó có mang Jev. Nó được đọc từ các tệp của máy riêng, không có lệnh gọi mạng. + +## Những gì đạt tới trang chính sách + +Máy đã gửi hoạt động hook của nó tới FailproofAI Cloud (`events:add`). Với Jev bật, bản ghi mỗi lệnh gọi được gated cũng nói đánh giá nào đã chạy, Jev quyết định gì, chính sách nào nó xóa, tại sao nó quay lại khi nó làm, độ trễ của nó và mô hình đã trả lời — quyết định, mã và tên, không bao giờ là lệnh hoặc prompt của bạn. Trên trang **Policies** của tổ chức bạn: + +- một lệnh gọi mà phán quyết riêng của Jev quyết định (chế độ enforce) được quy cho **Jev**, và khi kiểm tra quyết định đó đến từ một pack, bản ghi cũng đặt tên cho pack đó và phiên bản của nó; +- ở chế độ shadow, từ chối hoặc cảnh báo của Jev xuất hiện dưới dạng **would-have**, bên cạnh những rollout bạn đang quan sát; +- các chính sách Jev xóa, hoặc sẽ xóa ở chế độ shadow, được đếm trên mỗi chính sách. + +## Khi Jev không thể trả lời + +Mỗi một trong số này quay lại kết quả của các chính sách của bạn cho lệnh gọi đó và được ghi lại với lý do của nó: + +| Lý do | Nguyên nhân | +| --- | --- | +| `out-of-credits` | Tổ chức của bạn đã sử dụng hạn mức gói của nó. | +| `http-401`, `http-403` | Khóa bị thu hồi, hoặc không mang `jev:evaluate`. Kết nối lại với một khóa có. | +| `http-429` | FailproofAI Cloud đang giới hạn tốc độ Jev cho tổ chức của bạn. Cho đến khi thời gian chờ mà nó yêu cầu kết thúc (của nó `Retry-After`, tối đa 60 giây), máy không gửi nó gì và mỗi lệnh gọi quay lại ngay lập tức. Các lệnh gọi được giữ lại bằng cách đó được ghi lại là `http-429`, hoặc là `rate-limited` khi giới hạn tốc độ của máy riêng giữ chúng trước tiên. | +| `http-429` (giới hạn hàng ngày) | Tổ chức của bạn đã sử dụng các lệnh gọi Jev hàng ngày của nó: **10,000 mỗi ngày UTC**, trừ khi ai điều hành FailproofAI Cloud của bạn đặt một giới hạn khác. Mỗi lệnh gọi quay lại cho đến khi số lượng được đặt lại vào 00:00 UTC; máy vẫn hỏi lại tối đa một lần một phút, vì vậy nó nhận được reset trong vòng một phút. `failproofai jev test` nói "Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev từ chối yêu cầu của lệnh gọi này, thường là vì lệnh gọi công cụ chứa văn bản dày đặc (base64, hex, minified code) vượt quá ngân sách token của Jev. Lệnh gọi đó quay lại mỗi lần; nó không phải là một outage. | +| `http-502` | Jev không khả dụng ngay bây giờ. | +| `http-503` | Cloud này không thể phục vụ Jev cho tổ chức của bạn: không có gateway mô hình, một tổ chức chưa được cấp phép, hoặc gateway đã hạ. Hỏi quản trị viên của bạn; hooks hỏi lại tối đa một lần một phút. | +| `http-404` | FailproofAI Cloud này chưa phục vụ Jev. | +| `timeout` | Không có câu trả lời trong `timeoutMs` (mặc định 3000). | +| `model-mismatch` | Phiên bản Jev khác 1.13 đã trả lời. | + +## Nơi khóa sống và nơi nó đi + +- Khóa được lưu trữ một lần, trong `~/.failproofai/credentials.json` (`0600`, trong một thư mục chỉ dành cho chủ sở hữu), bên cạnh các thông tin xác thực FailproofAI Cloud khác. `jev.json` không giữ khóa cho tuyến đường này; một khóa viết ở đó làm cho cấu hình không hợp lệ. +- Nếu `credentials.json` mang **bất kỳ** quyền nào cho bất kỳ ai ngoài bạn (nhóm hoặc người khác, đọc hoặc ghi), hoặc thư mục của nó có thể **được ghi** bởi bất kỳ ai ngoài bạn, nó **bị từ chối**, không được đọc, và Jev đang tắt cho đến khi bạn khắc phục: `chmod 600` trên tệp, `chmod 700` trên thư mục (hoặc kết nối lại, sẽ viết lại tệp ở `0600` và chỉ dành cho chủ sở hữu thư mục). Một thư mục mà những người khác chỉ có thể đọc là được; một người họ có thể ghi để họ có thể hoán đổi tệp. +- Khóa chỉ được tính khi kết nối nó đến từ trên máy: một chính sách hoặc thông tin xác thực báo cáo cho cùng một FailproofAI Cloud **với cùng một khóa**, trong cùng một tệp. Một khóa Jev bị bỏ lại mà không có một được bỏ qua, và Jev ở lại tắt. Điều đó xảy ra khi `config --disconnect` của failproofai cũ để lại khóa Jev (nó không biết cần loại bỏ), hoặc khi `config --token` của failproofai cũ kết nối với một khóa khác, trên FailproofAI Cloud có thể thuộc về một tổ chức khác. Để bật Jev trở lại, kết nối lại với một khóa **machine**. +- Khóa chỉ được gửi đến nguồn gốc Cloud mà nó được xác minh chống lại. Một `jev.json` chỉ đến nơi khác bị từ chối. +- **Một agent trên máy có thể đọc nó.** `credentials.json` chỉ dành cho chủ sở hữu, và agent chạy dưới tư cách là chủ sở hữu đó. Đọc các tệp của failproofai được phép cố ý (chỉ thay đổi chúng bị chặn, bởi `block-failproofai-commands`), vì vậy điều duy nhất giữa một agent và tệp này là `block-read-outside-cwd` — một chính sách **reviewable** — và từ một phiên bắt đầu trong thư mục chính của bạn, không có gì. Một khóa có `jev:evaluate` chi tiêu hạn mức Jev của tổ chức bạn (lên đến giới hạn hàng ngày) từ bất cứ nơi nó được sử dụng, vì vậy hãy coi một khóa máy giống như bất kỳ thông tin xác thực chi tiêu nào khác: nếu một agent có thể đã đọc nó, vô hiệu hóa nó trên trang Keys và kết nối lại với một khóa mới. +- Chỉ có các tệp toàn cầu của bạn quyết định điều này. Một kho lưu trữ không thể bật Cloud Jev, chỉ đến nơi khác hoặc cung cấp khóa của nó, và `FAILPROOFAI_JEV_API_KEY` bị bỏ qua cho tuyến đường này. +- Đối với mỗi lệnh gọi Jev đánh giá, một yêu cầu đi tới FailproofAI Cloud, mang những gì [trang bring-your-own-key](/vi/policies/jev-byok#what-leaves-the-machine) liệt kê (bí mật được sửa). FailproofAI Cloud chuyển tiếp nó đến TypeSafe và không ghi lại hoặc giữ nó. + +## Tắt nó + +| Lệnh | Kết quả | +| --- | --- | +| `failproofai jev setup --mode off` | Giữ lại cấu hình; Jev không được hỏi. **Đây là công tắc kéo dài:** kết nối lại không bao giờ viết lại một `jev.json` hiện có, vì vậy Jev ở lại tắt cho đến khi bạn chuyển nó lại bằng `--mode shadow`. | +| `failproofai jev remove` | Xóa `~/.failproofai/jev.json`; Jev tắt — cho đến `failproofai config --token` tiếp theo với một khóa mang `jev:evaluate`, tìm thấy không có `jev.json` và bật Jev lại ở chế độ shadow (trừ khi nó chạy với `--no-transcripts`). Để giữ nó tắt, hãy sử dụng `--mode off`. | +| `failproofai config --disconnect` | Ngắt kết nối máy: khóa bị loại bỏ, và cũng là `jev.json` khi nó đặt tên FailproofAI Cloud và không bị tắt. Một `jev.json` cho điểm cuối của riêng bạn ở lại, và cũng như một cái bị tắt, vì vậy Jev ở lại tắt khi bạn kết nối lại. | + +Từ lệnh gọi công cụ tiếp theo, hooks chạy các chính sách regex chính xác như trước. \ No newline at end of file diff --git a/docs/vi/policies/jev.mdx b/docs/vi/policies/jev.mdx new file mode 100644 index 000000000..a31c1140b --- /dev/null +++ b/docs/vi/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "Thêm đánh giá trực tiếp của Jev vào các lệnh gọi công cụ bị hạn chế, sau đó kiểm tra trước khi thực thi quyết định của nó." +icon: "shield-check" +--- + +Jev đọc một lệnh gọi công cụ so với những gì người dùng yêu cầu agent thực hiện. Sử dụng nó khi chính sách khớp chuỗi chặn công việc hợp lệ hoặc bỏ lỡ hành động rủi ro cần ngữ cảnh. Nó trả lời cùng với các chính sách của bạn tại cổng `PreToolUse` hoặc `PermissionRequest`. Để có điểm số **sau** khi phiên kết thúc, hãy sử dụng [Jev evaluations](/vi/evaluations/jev). + +## Bắt đầu ở chế độ quan sát + +Cài đặt Failproof AI và gắn hooks vào một [harness được hỗ trợ](/vi/reference/harnesses). Sử dụng failproofai 1.0.8-beta.0 trở lên. + +Failproof AI không được gửi kèm với các kiểm tra Jev. Cài đặt chúng dưới dạng một gói, nếu không Jev không có gì để hỏi và sẽ không bao giờ được gọi: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +Sau đó chọn cách các yêu cầu được gửi tới Jev: + +| Tuyến đường | Bước đầu tiên | +| --- | --- | +| FailproofAI Cloud | Kết nối với khóa **machine** mang `jev:evaluate`. Trên máy không có cấu hình Jev, `failproofai config` bật Jev ở chế độ quan sát. | +| Nhà cung cấp của bạn | Trong bảng điều khiển cục bộ, mở **Settings → Jev**, chọn nhà cung cấp, dán mã thông báo của nó và chọn **observe**. Hoặc chạy `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`. | + +![Cài đặt Jev của bảng điều khiển cục bộ: nhà cung cấp, endpoint, mã thông báo và chế độ quan sát trước khi bật Jev.](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` kiểm tra endpoint. Để kiểm tra đường dẫn hook, yêu cầu agent có hook sử dụng công cụ đọc tệp của nó trên `README.md`. Xác nhận rằng lệnh gọi công cụ đó xuất hiện trong phiên, sau đó kiểm tra **Policies → Activity** trong [bảng điều khiển cục bộ](/vi/reference/local-dashboard#review-policy-activity). Số lượng Jev trong `status` sẽ tăng lên. Chế độ quan sát ghi lại những gì Jev sẽ quyết định trong khi kết quả chính sách hiện tại của bạn vẫn được áp dụng. + +## Quyết định khi nào để thực thi + +Một chính sách **hard** luôn có quyền quyết định cuối cùng. Jev chỉ có thể xóa một từ chối từ một chính sách được đánh dấu rõ ràng là **reviewable** và chỉ khi nó kiểm tra mối quan tâm được đặt tên của chính sách đó. Xem [policy authority](/vi/policies/authority) trước khi dựa vào một phê duyệt. Jev cũng có thể cảnh báo hoặc từ chối riêng. Nếu nó không thể trả lời, kết quả chính sách sẽ quyết định lệnh gọi đó. + +Khi kết quả quan sát trông đúng, chuyển sang chế độ thực thi trong **Settings → Jev** hoặc chạy: + +```bash +failproofai jev setup --mode enforce +``` + +Để tìm URL nhà cung cấp, khóa Cloud, cấu hình, fallbacks và dữ liệu được gửi với mỗi yêu cầu, hãy xem [tài liệu tham khảo tích hợp Jev](/vi/reference/jev). \ No newline at end of file diff --git a/docs/vi/reference/custom-agents-typescript.mdx b/docs/vi/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..bce107dc9 --- /dev/null +++ b/docs/vi/reference/custom-agents-typescript.mdx @@ -0,0 +1,433 @@ +--- +title: "Custom agents (TypeScript)" +description: "Configuration, the event catalog, the scopes and the framework adapters for @failproofai/sdk." +icon: "square-js" +--- + +Mô tả chi tiết về các setting, method và field trong SDK TypeScript. Nếu bạn mới bắt đầu integrate, hãy xem hướng dẫn — trang này dành cho tra cứu. + + + + Cài đặt, integrate, các event method, ví dụ thực tế và các vấn đề thường gặp. + + + Các event tương tự, định dạng wire như nhau, cùng một spool — từ Python. + + + +Node 20.9 trở lên. ESM và CommonJS. Không có runtime dependencies. + + + SDK này và SDK Python viết **các event giống nhau vào cùng một spool**. Một fleet có agent Node và agent Python tạo ra một tập hợp session, không phải hai, và không có gì trong dashboard phân biệt chúng. Chọn theo từng dịch vụ, không phải theo công ty. + + +## Cài đặt + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +Các framework adapter được ship trong package. Các framework là **optional peer dependencies** — được khai báo để các phạm vi được hỗ trợ có thể nhìn thấy, không bao giờ được cài đặt thay bạn và chỉ được import khi bạn gọi `instrument()`. + +## Kết nối daemon Failproof + +Giống hệt SDK Python: tạo một khóa `events:add` trong **Admin → Keys**, sau đó [kết nối daemon](/vi/start/setup#connect-a-machine-to-cloud) trên máy agent. SDK viết vào đĩa; daemon ship nó. + +## Cấu hình + +### OpenTelemetry spans (opt in) + +Cài đặt OpenTelemetry riêng biệt với `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`. +Sau đó thêm FailproofAI vào processor của provider: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +Với một provider hiện tại, giữ lại các processor khác trong cùng một danh sách. Các provider +hiển thị `addSpanProcessor` có thể được truyền là `{ provider }`. Không có option, +setup chỉ đăng ký một provider mới nếu chưa có provider được đăng ký. +`OtelSpanExporter` cũng có thể được sử dụng trực tiếp với processor của bạn. + +Export đi qua daemon FailproofAI đã kết nối; SDK không gửi request mạng +và không cần khóa hoặc local listener. Yêu cầu admin bật +[OpenTelemetry ingest](/vi/agenteye/opentelemetry). `instrument()` không có option +không bật exporter này. `uninstrument("otel")` chỉ vô hiệu hóa processor của nó. +Span attribute của bạn kiểm soát việc capture content; flush provider trước khi thoát. +OpenTelemetry vẫn là một optional application dependency, không phải hard SDK dependency. + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| Option | Công dụng | +| --- | --- | +| `environment` | Nhãn trên mỗi event — `production`, `staging`, `prod-eu`. Mặc định là `dev`. | +| `flushInterval` | Bao lâu timer ghi vào đĩa, tính bằng giây. Mặc định là `0.5`. | +| `baseDir` | Nơi ghi. Mặc định là spool của daemon, đó là những gì bạn muốn trừ khi bạn biết cách khác. | + +Không có gì được áp dụng trừ khi tất cả đều xác thực, vì vậy một lệnh bị từ chối sẽ để SDK chính xác như nó đã là thay vì có một `baseDir` mới và interval cũ. + +Đặt bằng biến môi trường thay thế: + +| Biến | Công dụng | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Đặt `environment` mà không cần thay đổi code. Option `configure()` sẽ thắng nó. | +| `FAILPROOFAI_HOME` | Di chuyển root Failproof AI giữ spool. | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`, `info`, `warn` (mặc định), `error`, `silent`. | +| `FAILPROOFAI_SDK_STRICT` | `1` làm cho lỗi instrumentation throw thay vì được log. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` làm cho vấn đề framework-compatibility throw thay vì warn và tiếp tục. | + + + **Không có dấu phẩy trong `environment`.** Ingest chia field đó trên dấu phẩy để xây dựng các filter của nó, và bỏ qua bất kỳ event nào có nhãn chứa một — vì vậy cả một run âm thầm biến mất. Viết `prod-eu`, không phải `prod,eu`. + + `configure({ environment: "prod,eu" })` throw để bạn phát hiện ngay lập tức. `AGENTEYE_ENVIRONMENT` không thể throw — không có gì gọi bạn — vì vậy nó cảnh báo một lần và quay lại `dev`. + + +Định tuyến các dòng log của SDK vào logger của bạn với `failproofai.setLogger({ debug, info, warn, error })`. + +## Tắt + +Các event được buffered được flush trên `process.on("exit")`. + +Một process bị giết bởi tín hiệu không bao giờ đạt đến điều đó, và mặc định của Node cho `SIGTERM` là chấm dứt mà không chạy exit handler — vì vậy một agent được containerize sẽ mất những gì interval cuối cùng không ghi được. + + + **SDK này sẽ không cài đặt signal handler cho bạn.** Đăng ký một cái thay đổi hành vi process của bạn: một listener triệt tiêu mặc định của Node, vì vậy một library thêm một cái sẽ âm thầm dừng Ctrl-C từ hoạt động. Thêm của riêng bạn: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +Một script ngắn hạn hoặc handler serverless nên `await failproofai.flush()` trước khi trả về — interval một mình không đảm bảo delivery. + +## Identity + +Mỗi event thuộc về một session và một agent. **Các scope điền cả hai**, vì vậy bạn hiếm khi truyền chúng: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +Truyền `sessionId` hoặc `agentId` rõ ràng vẫn hoạt động và thắng. Với cả hai không bound cũng không truyền, lệnh gọi throw thay vì phát ra một event Cloud sẽ âm thầm discard. + + + Identity chạy trên `AsyncLocalStorage`. Nó theo `await`, `.then()`, timer và bất kỳ callback nào được tạo bên trong scope. Nó **không** theo một callback được lưu trữ trong một run và gọi trong một run khác, hoặc công việc handed qua một boundary `worker_threads` — wrap những cái trong `failproofai.propagate()` hoặc các event của chúng land unattached. + + +### Scopes + +| Scope | Phát ra | Trả về | +| --- | --- | --- | +| `session(body)` | nothing — identity chỉ | whatever `body` trả về | +| `agent(id, options?, body)` | `agent_start`, sau đó `agent_end` | whatever `body` trả về | +| `toolCall(name, options?, body)` | `tool_use`, sau đó `tool_result` | whatever `body` trả về | + +Một body đồng bộ vẫn đồng bộ: `agent("x", () => 1)` trả về `1`, không phải promise. + +`toolCall` ghi lại giá trị resolved của body như `output` của tool, trừ khi bạn gán `call.output` của bạn. + + + +| Điều gì xảy ra | Events | `outcome` | +| --- | --- | --- | +| block trả về | `agent_end` | `"success"`, hoặc `outcome` của bạn | +| block throw | `error`, sau đó `agent_end` | `"failed"` | +| một `AbortError` | `agent_end` chỉ | `"cancelled"` | + +Error luôn được re-throw. + +Một tool failure được ghi trên leaf — `tool_result` với một string `error` — và phát ra **không có** run-level `error` event. Một cái agent loop bắt không phải là run failure, và một cái mà propagate được báo cáo chính xác một lần, bởi enclosing `agent()`. + + + + + +Khi công việc không phải là một hàm duy nhất — một scope mở trong constructor và đóng trong teardown, hoặc một straddle existing control flow: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, sau đó agent_end +``` + +Cả hai hình thức phát ra byte-identical events. Ưu tiên hình thức callback: nó chạy bên trong `AsyncLocalStorage.run()`, vì vậy không có gì để unwind và toàn bộ class của các bug "opened here, closed over there" không thể tiếp cận. + +Một `using` block bắt lỗi của riêng nó báo cáo nó với `span.fail(error)` — disposer không có exception channel của riêng nó. + + + +## Event catalog + +Mười lăm method giống như SDK Python, trong camelCase. Hầu hết đi kèm **cặp** — bạn gọi opener, sau đó closer, và SDK time the gap. + +| | Opens | Closes | +| --- | --- | --- | +| **Agents** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **Models** | `modelRequest` | `modelResponse` | +| **Tools** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **Humans** | `humanWait` | `humanInput` | + +Ba đứng riêng: `error`, `humanPause`, `humanInterrupt`. + + + +Mỗi method cũng nhận `sessionId` và `agentId`, mà các scope điền cho bạn. Bất kỳ điều gì được bỏ qua được dropped thay vì được gửi như JSON `null`. + +| Method | Yêu cầu | Tùy chọn | +| --- | --- | --- | +| `agentStart` | — | `goal`, `parentId` | +| `agentEnd` | — | `outcome`, `summary` | +| `agentPause` | `pauseId` | `reason`, `userId` | +| `agentResume` | `pauseId` | `reason`, `userId` | +| `modelRequest` | — | `model`, `messages`, `system`, `tools`, `requestId` | +| `modelResponse` | — | `model`, `stopReason`, `inputTokens`, `outputTokens`, `content`, `role`, `requestId` | +| `toolUse` | `toolName`, `toolCallId` | `input` | +| `toolResult` | `toolName`, `toolCallId` | `output`, `error` | +| `hookTriggered` | `hookName`, `hookId` | `triggerEvent`, `input` | +| `hookCompleted` | `hookName`, `hookId` | `outcome`, `output`, `error` | +| `error` | `errorType`, `message` | `traceback` | +| `humanWait` | `inputId` | `prompt`, `options`, `reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`, `userId` | +| `humanInterrupt` | — | `reason`, `userId`, `atStep` | + +Bất kỳ key nào khác bạn thêm trở thành một custom payload field. Namespace bất kỳ điều gì framework-specific `fw_*`; một tên va chạm với một declared field bị từ chối thay vì âm thầm overwriting một promoted column. + + + + + **`duration_ms` được tính toán, không được chấp nhận.** Bốn closing method time the gap từ opener của chúng và từ chối một caller-supplied `duration_ms` — một reported duration không thể giả mạo được. + + Các cặp được khớp trên **session** và id, không bao giờ trên agent. Một tool mở dưới `planner` và đóng dưới `worker` vẫn khớp, đó là những gì nested multi-agent runs thực sự làm. + + +## Framework adapters + +```ts +await failproofai.instrument(); // whatever nó có thể tìm thấy +await failproofai.instrument("langchain"); // chính xác một +failproofai.uninstrument(); // đặt mọi thứ lại +``` + +| Framework | Được hỗ trợ | Cách nó attach | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x, LangGraph.js 0.4 – 1.x | `CallbackManager.configure`, vì vậy mỗi `invoke`/`stream`/`batch` được bao phủ mà không truyền `callbacks:` ở bất kỳ nơi nào — hoặc truyền `langchainHandler()` của riêng bạn và không patch bất kỳ điều gì. | +| **Vercel AI SDK** | `ai` 4 – 7 | `telemetry()` tại call site, hoặc `instrument("ai")` cho toàn bộ process trên `ai` 7 (trên 4–6 đó là opt-in — xem dưới). | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`, model của agent và tool resolution, và workflow run/step engine. | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager` (subscribed) cộng với `AgentWorkflow.runStream`, cho workflow run và step của chúng. | + +Mỗi phạm vi được kiểm tra đối với real framework release, ở cả hai đầu, như một ES module và như CommonJS, trên mỗi CI run. + +Ánh xạ là của SDK Python, vì vậy chương trình tương tự vẽ cây tương tự trong một ngôn ngữ. Một construct chỉ là một **agent** nếu nó sở hữu LLM decision loop — một graph hoặc chain run, một AI SDK `generateText`/`streamText` call, một Mastra agent, một LlamaIndex agent run. Một LangGraph node hoặc một workflow step là một **hook** (`hook_triggered`/`hook_completed`), không bao giờ là một nested agent. Model call là `model_request`/`model_response` cặp với token count; tool call mang tool call id của chính model. Một failure được ghi một lần, trên event nó xảy ra. + +Một adapter mà lỗi cài đặt được log và skipped; những cái khác vẫn cài đặt, bởi vì một broken LlamaIndex không nên mất bạn LangGraph. + + + `instrument()` không có argument phát hiện framework bằng cách nó **resolve**, không phải bằng cách nó đã được import — Node không hiển thị tương đương Python của `sys.modules` cho ES module. Một framework bạn đã cài đặt nhưng không sử dụng sẽ được import và patch. Đặt tên cái bạn muốn nếu điều đó quan trọng. + + + + Hầu hết các framework này ship một ES-module build và một CommonJS build, mà Node tải như hai unrelated copy. Các adapter patch the copy application của bạn tải (và CommonJS copy cũng nếu cái gì đó đã `require` nó), vì vậy cả hai module system hoạt động. Một framework **bundled thành output của bạn** bởi esbuild hoặc webpack là out of reach — sử dụng call-site helpers ở đó: `langchainHandler()`, `telemetry()`, `wrapTool()`. + + +### LangChain không patching + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +Handler hoạt động với hoặc không có `instrument()` và không bao giờ double-record. `instrument("langchain")` nhận `sessionId`, `captureContent`, `includeChains`, `graphCallbacks` và `captureLimit`, như adapter Python làm; `metadata: { failproofai_sdk_session_id }` trên một call chọn session cho invocation đó. + +### Vercel AI SDK + +AI SDK xuất các hàm plain từ một ES module, và một ES module namespace là immutable theo specification — không có nơi nào để patch. Nó sử dụng các extension point mà SDK chính nó tài liệu: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // trên ai 7, `telemetry: telemetry({ … })` — cùng một object, tên mới +}); +``` + +Đó là toàn bộ integration: một agent span, một model request/response cặp mỗi step với token count, và mỗi tool call. Một call site hoạt động trên mỗi major — `ai` 4–6 đọc the tracer nó mang, `ai` 7 the telemetry integration. + +`instrument("ai")` làm process-wide **trên `ai` 7**: mỗi call, qua AI SDK's global telemetry-integration list, mà là additive và không lấy gì từ ai khác. + +**Trên `ai` 4–6, `instrument("ai")` ghi không có gì bằng chính nó, và log một cảnh báo nói như vậy.** Duy nhất process-wide hook những major đó có là global OpenTelemetry tracer provider — một single slot OpenTelemetry từ chối hand over một khi taken. Đăng ký của chúng tôi sẽ âm thầm từ chối `NodeSDK.start()` của bạn sau trong startup và gửi http/database span của bạn đến một tracer mà export không có gì. Sử dụng `telemetry()` tại call site hoặc `wrapModel` ở đó. Nếu process chạy không có OpenTelemetry của riêng nó, opt in với `instrument("ai", { registerGlobalTracer: true })`: nó sau đó ghi mỗi call mà pass `experimental_telemetry: { isEnabled: true }`, và chỉ nhận slot nếu nó vẫn empty. `registerGlobalTracer: false` giữ default và silence the warning. + +Nếu bạn thích wrap model một lần, `wrapModel` thấy model call chỉ, bởi vì tool call xảy ra trên model layer. Một wrapped model gọi với không có gì xung quanh nó được ghi như run của riêng nó. Một streamed call đóng bất cách như stream dừng — `stop_reason: "cancelled"` khi consumer cancel nó, `"error"` với error khi nó fail part-way: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +Sử dụng cả hai tốt: middleware nhận thấy call đã được ghi lại và defer, vì vậy mỗi call được ghi một lần. + +`functionId` tên agent span. Giữ nó low-cardinality — nó land trong `agent_id`, primary dashboard facet. + +### Next.js + +`next build` bundled dependency của server theo mặc định, và một framework bundled vào build là một copy `instrument()` không thể tiếp cận. Wrap config một lần và gọi `instrument()` từ Next's startup hook: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` thêm LangChain, Mastra, LlamaIndex và SDK chính nó để `serverExternalPackages`, giữ danh sách của riêng bạn. Không có nó, `instrument()` cảnh báo một lần mỗi framework nó không thể tiếp cận thay vì fail âm thầm; nếu bạn danh sách các package chính bạn, đặt `FAILPROOFAI_NEXT_EXTERNALS=1`. Vercel AI SDK và call-site helper hoạt động bất kỳ cách. Một Edge route nhận một no-op build: import SDK an toàn và ghi không có gì. + +### Token count trên streamed call + +OpenAI-compatible API chỉ báo cáo usage trên một stream khi client hỏi. LangChain và Vercel AI SDK hỏi; cho LlamaIndex pass `additionalChatOptions: { stream_options: { include_usage: true } }` tới `OpenAI` LLM của nó, và cho Mastra xây dựng model với usage bật (ví dụ `createOpenAICompatible({ includeUsage: true })`). Nếu không streamed model call mang không token count. + +### Runtimes + +Node ≥ 20.9, Bun và Deno — mỗi framework, như một ES module và như CommonJS, được kiểm tra trên mỗi đối với Node's trace. SDK chạy bên cạnh daemon `failproofaid`, mà ship những gì nó viết. + +## Agent của riêng bạn — không có framework + +Cho một agent loop bạn viết chính bạn, hoặc một framework không có adapter. Bạn phát ra các event với API tương tự adapters sử dụng dưới, vì vậy trace có hình dạng và chất lượng tương tự. + +Bạn không cần biết agent được tổ chức như thế nào. Mỗi hand-built agent đã có ba nơi, cho dù các hàm của nó được gọi là gì, và ba cái đó là toàn bộ integration: + +| Nơi | Những gì để thêm | Phát ra | +| --- | --- | --- | +| Nơi **một run** bắt đầu và kết thúc | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **Một hàm duy nhất gọi model** | `event.modelRequest` trước, `event.modelResponse` sau — cả hai nửa, thậm chí trên failure | một cặp mỗi model turn | +| **Một hàm duy nhất chạy tool** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +Identity là ambient: mọi thứ bên trong `agent()` land trên run's session mà không lấy một id, và không có gì khác trong chương trình thay đổi — bao gồm bất kỳ agent đã viết vào database của nó. + +- **Một dịch vụ hoặc một worker:** truyền request của riêng bạn hoặc job id như `sessionId`, vì vậy một session trên dashboard và record trong log hoặc database của riêng bạn là cùng một string. +- **Sub-agents:** nest `agent()` call. Cái bên trong join session với cái bên ngoài như `parent_id`. +- **Phát ra các cặp.** Một `modelRequest` không có `modelResponse` là một span dashboard hiển thị như chạy mãi mãi — do đó `catch`. + +[`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) trong repository là toàn bộ, runnable version: một real OpenAI tool loop instrumented chính xác như thế này, chạy trong CI trên mỗi thay đổi như một ES module và như CommonJS. + +## Evaluations + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +Xem [Evaluator SDK reference](/vi/reference/evaluator-sdk) cho protocol, worker setting và result type. + + + **Một evaluation phải yield.** Một synchronous function mà không bao giờ trả về block cái một thread Node có, và không timeout có thể fire khi nó làm. Viết `async` evaluation. + + +## Những gì nó sẽ không làm với process của bạn + +| | | +| --- | --- | +| **Block agent loop của bạn** | Event đi vào một in-memory queue; một timer ghi chúng. Timer là `unref`'d, vì vậy import package này không bao giờ dừng script từ thoát. | +| **Grow không bound** | Queue được capped bằng count *và* bằng measured byte. Quá một, các event cũ nhất được discarded và một cảnh báo nói như vậy — một telemetry outage phải không trở thành OOM kill. | +| **Take process xuống** | Một event không thể mã hóa được dropped một mình, không batch xung quanh nó. Một throwing getter, một circular reference, một `BigInt`, một lone surrogate: mỗi được handle thay vì propagated. | +| **Leave một half-written batch** | Content là `fsync`ed trước một atomic rename, directory là `fsync`ed sau, và một failed write làm sạch temporary file của nó. | +| **Leave transcript readable** | Batch là `0600` bên trong một `0700` directory. Chúng mang goal, prompt, tool argument và tool output. | +| **Ship credential** | API key, token, JWT, bearer header và secret-shaped assignment được redacted trước byte tiếp cận đĩa. Daemon redact lại trước upload. | \ No newline at end of file diff --git a/docs/vi/reference/custom-agents.mdx b/docs/vi/reference/custom-agents.mdx index a5753f9dd..7c26483c1 100644 --- a/docs/vi/reference/custom-agents.mdx +++ b/docs/vi/reference/custom-agents.mdx @@ -15,7 +15,7 @@ Mỗi cài đặt, phương thức và trường làm gì. Nếu bạn lần đ -Python 3.10 hoặc mới hơn. Không có phụ thuộc thời gian chạy. +Python 3.11 hoặc mới hơn. Không có phụ thuộc thời gian chạy. ## Cài đặt diff --git a/docs/vi/reference/jev-cloud.mdx b/docs/vi/reference/jev-cloud.mdx new file mode 100644 index 000000000..924657558 --- /dev/null +++ b/docs/vi/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "Jev thông qua FailproofAI Cloud" +description: "Các khóa máy Cloud, trạng thái kết nối, giới hạn và hành vi khi xảy ra lỗi để xem xét chính sách Jev trực tiếp." +icon: "cloud" +--- + +Đây là tài liệu tham khảo tuyến Cloud cho [chính sách Jev](/vi/policies/jev). Jev, trình phân loại của TypeSafe, đọc từng lệnh gọi công cụ so với những gì bạn thực sự yêu cầu và trả lời cùng với chính sách của bạn, không phải thay thế chúng. Thông qua **FailproofAI Cloud**, một máy được kết nối sử dụng Jev với cùng khóa mà nó đã kết nối với: không cần tài khoản TypeSafe, không cần khóa thứ hai, không cần cấu hình điểm cuối. Mỗi lệnh gọi được tính vào phép cấp kế hoạch hiện tại của tổ chức bạn. + +Mọi thứ Jev thực hiện đều không thay đổi từ [cách thiết lập mang khóa của riêng bạn](/vi/reference/jev-providers): chính sách cứng vẫn cuối cùng, việc từ chối của chính sách có thể xem xét chỉ được xóa khi Jev được hỏi về mối quan tâm chính xác đó, và bất kỳ lỗi nào cũng quay lại kết quả regex cho lệnh gọi đó. + + +Yêu cầu **failproofai 1.0.8-beta.0** hoặc mới hơn. 1.0.7 không có Jev, mặc dù nó xếp cao hơn các phiên bản beta 1.0.7. Nếu không có cấu hình Jev, không có gì thay đổi: các móc chạy các chính sách regex chính xác như trước đây. + + +## Trước khi bắt đầu + +Cài đặt Failproof AI trên máy nơi tác nhân của bạn chạy và gắn các móc của nó vào [một harness được hỗ trợ](/vi/reference/harnesses). Nếu bạn bắt đầu từ đầu, hãy làm theo [hướng dẫn khởi động nhanh](/vi/start/quickstart) thông qua cài đặt móc. Kiểm tra CLI đã cài đặt với `failproofai --version`; cập nhật nó nếu nó trước Jev. Bạn cũng cần truy cập vào trang **Administration → Keys** của tổ chức để tạo khóa máy. + +Jev xem xét các lệnh gọi công cụ được đặt tên tại cổng `PreToolUse` hoặc `PermissionRequest`. Nó không xem xét mọi sự kiện trong một phiên. Để xem Jev xóa việc từ chối chính sách, bạn cần một chính sách đã cài đặt được đánh dấu [có thể xem xét](/vi/policies/authority); tất cả các từ chối chính sách khác vẫn cuối cùng. + +## Bật nó lên + +1. **Tạo khóa với Jev.** Trong bảng điều khiển FailproofAI Cloud, mở **Administration → Keys → Create key** và chọn cài đặt **machine**. Nó cấp ba quyền mà máy cần: `events:add` (gửi hoạt động), `policies:pull` (nhận chính sách) và `jev:evaluate` (Jev, tính vào kế hoạch của tổ chức bạn). Một khóa không thể mang `jev:evaluate` mà không có hai khóa khác. +2. **Kết nối máy** với khóa đó. Đọc bí mật một lần tại lời nhắc, sau đó chạy lệnh cài đặt đầy đủ: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` cài đặt daemon, gắn móc cho CLI tác nhân mà nó tìm thấy, và kết nối máy. Biến môi trường giữ khóa ra khỏi đối số của lệnh và lịch sử shell của bạn. Nếu harness của bạn được cài đặt sau, [gắn nó một cách rõ ràng](/vi/start/quickstart). + + Nếu tổ chức của bạn chạy FailproofAI Cloud của riêng nó thay vì cái được lưu trữ, hãy thêm địa chỉ của nó: `--url https://` (hoặc xuất `FAILPROOFAI_CLOUD_URL`). Nếu không có nó, khóa được kiểm tra so với dịch vụ được lưu trữ và kết nối không thành công. Nếu chứng chỉ của máy chủ đó đến từ một CA riêng, hãy cài đặt CA trong kho tin cậy hệ thống của máy (ví dụ với `update-ca-certificates`), không chỉ trong `NODE_EXTRA_CA_CERTS`: daemon gửi sự kiện và kéo chính sách đọc kho hệ thống. Xem [Khắc phục sự cố](/vi/reference/troubleshooting). + +Đó là tất cả. Kết nối lưu trữ khóa và, khi máy **chưa** có cấu hình Jev, viết một cho FailproofAI Cloud. Từ lần triển khai đầu tiên của máy (trong khoảng 30 s), FailproofAI Cloud đặt chế độ: `enforce` trong khi một chính sách Jev được triển khai cho nó, `off` khi không (xem [Ai đặt chế độ](#who-sets-the-mode)). Đầu ra nói như vậy: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +Các kiểm tra FailproofAI Cloud triển khai chạy trên Cloud. Để thêm kiểm tra của riêng bạn trên máy, hãy cài đặt một gói: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**Với `--no-transcripts`, kết nối không bật Jev.** Jev gửi từng lệnh gọi công cụ được kiểm tra và lời nhắc gần đây đến FailproofAI Cloud, đó là nhiều hơn những gì kết nối chỉ quyết định yêu cầu gửi. Khóa vẫn được lưu trữ, và đầu ra nói Jev có sẵn và cách bật nó: + +```bash +failproofai jev setup --provider failproofai +``` + +Nó cũng bật Jev thông qua FailproofAI Cloud **off**. Một `jev.json` chạy Jev qua FailproofAI Cloud (để lại bởi kết nối trước đó có bảng điểm bật) được xóa, theo quy tắc tương tự `config --disconnect` sử dụng, và đầu ra nói Jev qua FailproofAI Cloud vẫn tắt trên máy này. Một `jev.json` cho điểm cuối Jev của riêng bạn được để lại như cũ, và như vậy cũng là một CloudFailproofAI bạn tắt (`--mode off`). + + +Kết nối **không bao giờ ghi đè** một `~/.failproofai/jev.json` hiện có. Nếu bạn đã sử dụng điểm cuối Jev của riêng mình, nó sẽ tiếp tục được sử dụng, và đầu ra nói rằng tệp được để lại như đã cấu hình — và, khi tệp đó để Jev tắt (từ chối hoặc tắt), nói như vậy và cách khắc phục. Để chuyển máy đó sang FailproofAI Cloud, hãy chạy `failproofai jev setup --provider failproofai`. + + +## Ai đặt chế độ + +Trên một máy được kết nối với FailproofAI Cloud, **FailproofAI Cloud đặt chế độ Jev**; không có gì trên máy làm: + +- `enforce` trong khi bất kỳ chính sách Jev nào (hoặc regex + Jev) được triển khai cho máy: mọi lệnh gọi công cụ được kiểm tra từ một tác nhân mà một trong các chính sách đó nhắm tới sẽ đi đến FailproofAI Cloud, yêu cầu các kiểm tra của nó cùng với các kiểm tra của các gói được cài đặt ở đó. Một lệnh gọi từ một tác nhân mà không có chính sách Jev Cloud nhắm tới, không có kiểm tra gói nào của riêng nó, hoàn toàn không được gửi. Trong `enforce`, các kiểm tra từ chối của Jev cũng chặn các lệnh gọi cũng như xóa các kết quả regex mà chúng xem xét. +- `off` khi không: không có Jev nào cả, bất kể `jev.json` nói gì. + +Để thử một chính sách Jev trước khi nó hoạt động, triển khai nó có hiệu ứng **observe**: các kiểm tra của nó vẫn được yêu cầu, và những gì chúng sẽ làm được ghi lại là **would-have** trên trang chính sách, nhưng nó không bao giờ chặn lệnh gọi và không bao giờ xóa một. `failproofai jev setup --mode` và bảng điều khiển nói **Settings → Jev** chế độ được quản lý bởi FailproofAI Cloud và không thay đổi gì. `jev.json` không được sử dụng cho kiểm tra của Cloud, ngay cả khi nó đặt tên nhà cung cấp khác. `failproofai config --disconnect` giao lại Jev cho `jev.json` của máy. + +`failproofai jev status` sau đó nói `Jev checks run on FailproofAI Cloud (mode: enforce)`. Nó cũng đặt tên các kiểm tra xem xét từng chính sách `both`. Trang bộ máy cho thấy tại sao một máy có chế độ không thể yêu cầu: + +- `transcripts_disabled`: máy được kết nối với `--no-transcripts`, không bao giờ bật Jev. +- `jev_unconfigured`: khóa của máy không mang `jev:evaluate`. +- `jev_rate_limited`: FailproofAI Cloud từ chối một số lệnh gọi của máy cho giới hạn tỷ lệ Jev của tổ chức, và những lệnh gọi đó đã được quyết định bởi các chính sách regex một mình. +- `jev_unavailable`: nhiều lệnh gọi liên tiếp không thành công, vì vậy máy bỏ qua Jev của FailproofAI Cloud trong khoảng thời gian một phút. Nó thử lại tự động. + +Nếu FailproofAI Cloud không trả lời trong 5 giây, các chính sách regex quyết định một mình, như đối với bất kỳ mất điện Jev nào. Sau 3 lần thất bại liên tiếp, máy ngừng yêu cầu trong khoảng thời gian một phút tại một thời điểm, vì vậy mất điện Cloud không làm chậm mọi lệnh gọi công cụ. + +Một tạm dừng phiên (`failproofai config --pause`) không dừng các kiểm tra Jev của FailproofAI Cloud, cũng như nó không dừng các chính sách được quản lý bởi Cloud. Nó thực hiện tạm dừng các kiểm tra Jev của các gói được cài đặt trên máy. + +## Kiểm tra nó đang làm gì + +```bash +failproofai jev status +failproofai jev test +``` + +`status` hiển thị nhà cung cấp là **FailproofAI Cloud**, máy chủ Cloud mà máy được kết nối, chế độ, và nguồn khóa là **FailproofAI Cloud connection**, không bao giờ là khóa. Khi một `jev.json` của FailproofAI Cloud đang có nhưng Jev không thể chạy, nó nói tại sao: + +| `status` nói | `status --json` | Nghĩa | +| --- | --- | --- | +| **off — không có khóa Jev nào được lưu trữ cho kết nối FailproofAI Cloud của máy này** | `key-lacks-jev` | Máy được kết nối, nhưng không có khóa Jev nào được lưu trữ cho nó: khóa thiếu `jev:evaluate`, hoặc kết nối không thể xác nhận nó. Chạy `failproofai config` lại với khóa trong `FAILPROOFAI_CLOUD_TOKEN`; nếu nó thiếu quyền, hãy sử dụng khóa **machine**. | +| **off — máy này không được kết nối với FailproofAI Cloud** | `not-connected` | Không có kết nối FailproofAI Cloud trên máy này để khóa Jev thuộc về. | + +Sau `failproofai config --disconnect` không còn `jev.json` của FailproofAI Cloud nữa (trừ khi nó được tắt, được giữ), vì vậy `status` chỉ báo cáo Jev là tắt. `status --json` mang cùng dữ kiện (`provider: "failproofai"`, `keySource: "cloud"`, `cloudConnected`, `keyCarriesJev`), cũng khi cấu hình không có hoặc bị từ chối. `permissions` luôn là của `jev.json`; từ chối về `credentials.json` thêm `credentialsPermissions`, và `fix` khi một lệnh khắc phục nó. `test` gửi một yêu cầu trực tiếp và báo cáo độ trễ và phiên bản Jev đã trả lời. Nó thoát 1 và nói như vậy trong tiêu đề của nó, khi câu trả lời đến sau thời gian chờ móc (móc sẽ ghi `timeout`) hoặc trả lời câu hỏi kiểm tra sai. + +Panel **Settings → Jev** trên bảng điều khiển cũng hiển thị **kết nối FailproofAI Cloud**: tổ chức nào mà máy báo cáo và liệu khóa của nó mang Jev. Nó được đọc từ tệp của máy, không có lệnh gọi mạng. + +## Xác minh một lệnh gọi thực + +Bắt đầu một phiên mới trong tác nhân được móc. Yêu cầu nó sử dụng công cụ đọc tệp của nó trên `README.md` và báo cáo tiêu đề. Xác nhận rằng phiên chứa lệnh gọi công cụ đó, sau đó chạy `failproofai jev status` lại: số lượng cuộc gọi được đánh giá gần đây của nó sẽ tăng. Mở **Policies → Activity** trong [bảng điều khiển cục bộ](/vi/reference/local-dashboard#review-policy-activity) để kiểm tra kết luận Jev và chế độ của lệnh gọi đó. Trong Cloud, trang **Policies** của tổ chức hiển thị kết quả Jev cho hoạt động đã gửi. Ở chế độ observe, kết luận được ghi lại là **would-have** và kết quả chính sách vẫn quyết định cuộc gọi. Việc xóa chỉ xuất hiện khi một chính sách có thể xem xét phù hợp và Jev xóa các kiểm tra được đặt tên của nó. + +## Những gì đến trang chính sách + +Máy đã gửi hoạt động móc của nó đến FailproofAI Cloud (`events:add`). Với Jev bật, bản ghi của mỗi lệnh gọi được gated cũng nói được đánh giator nào chạy, Jev quyết định gì, chính sách nào nó xóa, tại sao nó quay lại khi nó làm, độ trễ và mô hình đã trả lời — quyết định, mã và tên, không bao giờ lệnh hoặc lời nhắc của bạn. Trên trang **Policies** của tổ chức bạn: + +- một lệnh gọi mà kết luận của Jev quyết định (chế độ enforce) được quy cho **Jev**, và khi kiểm tra quyết định đến từ một gói, bản ghi cũng đặt tên gói đó và phiên bản của nó; +- ở chế độ observe, việc từ chối hoặc cảnh báo của Jev xuất hiện là **would-have**, bên cạnh các bản triển khai bạn đang quan sát; +- các chính sách Jev xóa, hoặc sẽ xóa ở chế độ observe, được tính trên mỗi chính sách. +- một quyết định Jev tham gia (một khối, một cảnh báo, một xóa, hoặc một would-have ở chế độ observe) liệt kê từng kiểm tra mà nó yêu cầu và những gì kiểm tra đó kết luận: kết luận, tại sao (`not-detected`, `exempt`, `fired`, `op-requested`, …), bằng chứng `p`, câu trả lời `exempt` và câu trả lời của mỗi dò. Một kiểm tra của chính sách được triển khai để xem (observe) cũng được liệt kê, được đánh dấu watched; nó không bao giờ chặn. Jev trả lời với xác suất, không phải văn bản, vì vậy không có lý do văn bản tự do. Các cho phép thường xuyp tích hợp thành số đếm và không mang danh sách này. + +## Khi Jev không thể trả lời + +Mỗi một trong số này quay lại kết quả chính sách của bạn cho lệnh gọi đó, và được ghi lại với lý do của nó: + +| Lý do | Nguyên nhân | +| --- | --- | +| `out-of-credits` | Tổ chức bạn đã sử dụng hết phép cấp kế hoạch. | +| `http-401`, `http-403` | Khóa đã bị thu hồi, hoặc không mang `jev:evaluate`. Kết nối lại với một khóa làm được. | +| `http-429` | FailproofAI Cloud đang giới hạn tỷ lệ Jev cho tổ chức bạn. Cho đến khi chờ nó yêu cầu kết thúc (` Retry-After` của nó, tối đa 60 giây), máy không gửi gì cho nó và mọi lệnh gọi quay lại ngay lập tức. Các cuộc gọi bị tạm giữ bằng cách đó được ghi lại là `http-429`, hoặc là `rate-limited` khi giới hạn tỷ lệ của máy tự giữ chúng trước. | +| `http-429` (giới hạn hàng ngày) | Tổ chức bạn đã sử dụng cuộc gọi Jev hàng ngày của nó: **10.000 mỗi ngày UTC**, trừ khi ai vận hành FailproofAI Cloud của bạn đã đặt giới hạn khác. Mọi lệnh gọi quay lại cho đến khi số đếm được đặt lại lúc 00:00 UTC; máy vẫn yêu cầu lại tối đa một lần một phút, vì vậy nó nhận được reset trong một phút. `failproofai jev test` nói Daily Jev limit for this org reached; resets at 00:00 UTC. | +| `http-422` | Jev từ chối yêu cầu lệnh gọi này, thường là vì lệnh gọi công cụ chứa văn bản dày đặc (base64, hex, mã minified) vượt quá ngân sách mã thông báo của Jev. Lệnh gọi đó quay lại mỗi lần; nó không phải là mất điện. | +| `http-502` | Jev không có sẵn ngay bây giờ. | +| `http-503` | Cloud này không thể phục vụ Jev cho tổ chức bạn: không có cổng mô hình, tổ chức chưa được cấp phép, hoặc cổng xuống. Hãy hỏi quản trị viên của bạn; móc yêu cầu lại tối đa một lần một phút. | +| `http-404` | FailproofAI Cloud này chưa phục vụ Jev. | +| `timeout` | Không có câu trả lời trong `timeoutMs` (mặc định 3000). Trong khi FailproofAI Cloud đặt chế độ Jev của máy, thời gian chờ là 5000 ms và `timeoutMs` của `jev.json` không được sử dụng. | +| `model-mismatch` | Một phiên bản Jev khác 1.13 đã trả lời. | + +## Nơi khóa sống, và nơi nó đi + +- Khóa được lưu trữ một lần, trong `~/.failproofai/credentials.json` (`0600`, trong một thư mục chỉ chủ sở hữu), bên cạnh các thông tin đăng nhập FailproofAI Cloud khác. `jev.json` không giữ khóa nào cho tuyến này; cái được viết ở đó làm cho cấu hình không hợp lệ. +- Nếu `credentials.json` mang **bất kỳ** quyền nào cho bất kỳ ai ngoài bạn (nhóm hoặc khác, đọc hoặc ghi), hoặc thư mục của nó có thể được **ghi** bởi bất kỳ ai ngoài bạn, nó **bị từ chối**, không đọc, và Jev tắt cho đến khi bạn sửa nó: `chmod 600` trên tệp, `chmod 700` trên thư mục (hoặc kết nối lại, viết lại tệp ở `0600` và làm cho thư mục chỉ chủ sở hữu). Một thư mục mà những người khác chỉ có thể đọc là tốt; một họ có thể ghi cho phép họ hoán đổi tệp. +- Khóa chỉ tính được trong khi kết nối mà nó đến từ đó trên máy: một chính sách hoặc thông tin đăng nhập báo cáo cho cùng FailproofAI Cloud **với cùng khóa**, trong cùng tệp. Một khóa Jev bị bỏ lại mà không có khóa sẽ bị bỏ qua, và Jev vẫn tắt. Điều đó xảy ra khi `config --disconnect` của failproofai cũ hơn để lại khóa Jev tại chỗ (nó không biết xóa nó), hoặc khi `config --token` của failproofai cũ hơn kết nối với khóa khác, có thể trên FailproofAI Cloud thuộc về tổ chức khác. Để bật Jev trở lại, kết nối lại với một khóa **machine**. +- Khóa chỉ được gửi đến nguồn Cloud mà nó được xác minh chống lại. Một `jev.json` chỉ vào nơi khác bị từ chối. +- **Một tác nhân trên máy có thể đọc nó.** `credentials.json` chỉ có chủ sở hữu, và tác nhân chạy như chủ sở hữu đó. Đọc tệp của failproofai được cho phép có mục đích (chỉ thay đổi chúng bị chặn, bởi `block-failproofai-commands`), vì vậy điều duy nhất giữa tác nhân và tệp này là `block-read-outside-cwd` — một chính sách **có thể xem xét** — và từ một phiên bắt đầu trong thư mục chính của bạn, không có gì. Một khóa với `jev:evaluate` chi tiêu phép cấp Jev của tổ chức bạn (lên tới giới hạn hàng ngày) từ bất kỳ nơi nào nó được sử dụng, vì vậy hãy coi một khóa máy như bất kỳ thông tin đăng nhập chi tiêu nào khác: nếu tác nhân có thể đã đọc nó, hãy vô hiệu hóa nó trên trang Khóa và kết nối lại với khóa mới. +- Chỉ tệp toàn cầu của bạn quyết định điều này. Một kho lưu trữ không thể bật Cloud Jev, chỉ vào nơi khác hoặc cung cấp khóa của nó, và `FAILPROOFAI_JEV_API_KEY` bị bỏ qua cho tuyến này. +- Đối với mỗi lệnh gọi Jev đánh giá, một yêu cầu đi đến FailproofAI Cloud, mang những gì trang [mang khóa của riêng bạn](/vi/reference/jev-providers#what-leaves-the-machine) liệt kê (bí mật được chỉnh sửa). FailproofAI Cloud chuyển tiếp nó đến TypeSafe và không ghi nhật ký hoặc giữ nó. + +## Tắt nó + +Trên một máy được kết nối, Jev tắt khi FailproofAI Cloud không triển khai chính sách Jev nào cho nó: xóa hoặc lưu trữ các chính sách Jev ở đó. + +| Lệnh | Kết quả | +| --- | --- | +| Xóa các chính sách Jev của máy trong FailproofAI Cloud | Chế độ của Cloud trở thành `off` vào lần khảo sát tiếp theo (khoảng 30 s): không có Jev nào cả, bất kể `jev.json` nói gì. | +| `failproofai config --disconnect` | Ngắt kết nối máy: khóa được xóa, và cũng vậy `jev.json` khi nó đặt tên FailproofAI Cloud và không bị tắt. Một `jev.json` cho điểm cuối của riêng bạn ở lại. | + +Từ lệnh gọi công cụ tiếp theo, móc chạy các chính sách regex chính xác như trước. \ No newline at end of file diff --git a/docs/vi/reference/jev-evaluations.mdx b/docs/vi/reference/jev-evaluations.mdx new file mode 100644 index 000000000..ee620a741 --- /dev/null +++ b/docs/vi/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Tham khảo đánh giá Jev" +description: "Các loại câu hỏi, điểm số được hiệu chuẩn, giới hạn và backfill cho các đánh giá phiên Jev." +icon: "list-checks" +--- + +Trang này mô tả các hình dạng câu hỏi và quy tắc chấm điểm đằng sau [các đánh giá Jev](/vi/evaluations/jev). Một số câu hỏi yêu cầu mô hình *đọc* cuộc trò chuyện, nhưng không phải *viết* về nó. "Khách hàng có bày tỏ sự khẩn cấp không?" có hai câu trả lời. "Họ bực dị đến mức nào?" có một vài câu, theo thứ tự. Bạn biết mọi câu trả lời trước khi hỏi. + +Một **đánh giá phân loại** là dành cho chính xác những cái đó. Bạn viết câu hỏi và các câu trả lời nó có thể đưa ra, và một mô hình nhỏ được xây dựng để phân loại sẽ trả về một số được hiệu chuẩn — không bao giờ là văn bản tự do. + + +Giống như một thẩm phán, một đánh giá phân loại có chi phí là một lần gọi mô hình cho mỗi phiên. Khác với thẩm phán ở chỗ nó là một mô hình nhỏ, có mục đích duy nhất thay vì một mô hình chung, vì vậy nó nhanh hơn và rẻ hơn — nhưng nó sẽ không bao giờ giải thích chính nó. Nếu bạn cần lý do, hãy sử dụng một [thẩm phán](/vi/evaluations/judge). + + +## Tôi muốn cái nào? + +| Câu hỏi | Sử dụng | +| --- | --- | +| Có bao nhiêu lệnh gọi công cụ? | code | +| Phiên có dưới 30 giây không? | code | +| Khách hàng có bày tỏ sự khẩn cấp không? | **phân loại** | +| Nhóm nào nên xử lý: thanh toán, kỹ thuật hoặc bán hàng? | **phân loại** | +| Khách hàng bực dị đến mức nào? | **phân loại** | +| Câu trả lời thực sự có chính xác không? | **thẩm phán** | +| Nó có tuân theo chính sách thang máy của chúng ta không, và tại sao bạn nghĩ như vậy? | **thẩm phán** | + +Quy tắc chung: **có thể đếm được → code, các câu trả lời bạn có thể liệt kê → phân loại, cần giải thích → thẩm phán.** + +Bạn không phải quyết định trước. Mô tả những gì bạn muốn đo lường và trợ lý chọn, cho bạn biết nó chọn cái nào và tại sao, và bạn có thể chuyển đổi. + +## Hai loại câu hỏi + +### `noul` — cái này có đúng không? + +Hai câu trả lời, và bạn mô tả cả hai. Kết quả là xác suất mà mô tả "đúng" phù hợp: + +```json +{ + "instructions": "Did the assistant promise a refund without first checking the refund policy?", + "criteria": { + "true": "A refund was promised or issued with no prior policy check or approval", + "false": "No refund was promised, or every refund followed a policy check" + } +} +``` + +Mô tả cả hai phía. "Không bày tỏ sự khẩn cấp" là một câu trả lời thực sự và nói như vậy làm cho câu kia sắc nét hơn. + +### `score` — có bao nhiêu cái này? + +Một thang đánh giá có thứ tự, **tệ nhất trước tiên**. Kết quả là nơi phiên hạ cánh trên nó, được tỷ lệ lại thành 0–1: + +```json +{ + "instructions": "How frustrated is the customer?", + "criteria": ["Calm", "Frustrated", "Very angry"] +} +``` + +**Một thang đánh giá cần ba đến năm cấp, và chúng phải tất cả khác nhau.** Cả hai giới hạn được đo lường, không phải theo kiểu dáng: + +- **Hai cấp** sụp đổ vào những gì `noul` đã làm tốt hơn, và **hơn năm cấp** khiến mô hình nằm vùng về phía giữa thay vì cam kết. Câu hỏi tương tự trên cùng một phiên được chấm 0.00 với hai cấp, 0.01 với ba cấp, và 0.55 với mười cấp. +- **Các cấp lặp lại** chia câu trả lời một cách tùy ý giữa chúng. Một phiên rõ ràng là tức giận đã ghi 1.00 so với `["Calm", "Frustrated", "Very angry"]` và 0.66 so với `["Angry", "Angry", "Angry"]` — một con số được hình thành tốt không có nghĩa gì. + +Các danh mục không có thứ tự — "thanh toán, kỹ thuật hoặc bán hàng" — không phải là một thang đánh giá. Hỏi chúng như một `noul` cho mỗi danh mục, hoặc sử dụng một thẩm phán. + +## Đọc kết quả + +Một bộ phân loại tạo ra một **điểm** từ 0 đến 1, giống như một thẩm phán, vì vậy nó biểu đồ, lọc và kích hoạt cảnh báo theo cách tương tự. Hai sự khác biệt đáng để biết: + +- **Không có lý do.** Trường này trống, có chủ đích. Mô hình này không giải thích chính nó, và bày tỏ một lời giải thích sẽ là một sự bịp bợm thay vì một tính năng. +- **Sự không chắc chắn được gắn nhãn.** Một câu hỏi `score` báo cáo độ tin cậy của chính nó, và một kết quả mà mô hình không chắc chắn được gắn thẻ `low_confidence` — vì vậy "cái nào trong những cái này mà con người nên xem xét" là một bộ lọc thay vì một phỏng đoán. Một câu hỏi `noul` không báo cáo độ tin cậy, vì vậy nó không bao giờ được gắn thẻ. + +Các phiên rất dài được đọc trong các đoạn trích và kết hợp lại. Khi một phiên quá dài để đọc toàn bộ, kết quả cho biết bao nhiêu lượt được bỏ qua — bạn sẽ không bao giờ thấy một phán quyết được đưa ra trên một phần của một phiên được trình bày như một phán quyết trên tất cả nó. + +## Giới hạn + +- **Ba đến năm cấp thang đánh giá, tất cả khác nhau.** Xem ở trên; cả hai giới hạn được thực thi tại thời điểm tác giả. +- **Một câu hỏi cho mỗi đánh giá.** Hỏi hai điều và bạn nhận được hai đánh giá, đó cũng là những gì bạn muốn trên một biểu đồ. +- **Chỉnh sửa câu hỏi xuất bản một phiên bản mới.** Các điểm cũ và mới không thể so sánh được, vì vậy chúng được giữ riêng biệt thay vì trộn thành một đường xu hướng. +- **Một bộ phân loại luôn tạo ra một điểm**, không bao giờ là một số liệu hoặc một khẳng định. +- **Không có lý do**, như ở trên. Nếu một con số sẽ khiến ai đó hỏi "tại sao?", hãy viết một thẩm phán. + +## Kiểm tra và backfill + +Không giống như một thẩm phán, một đánh giá phân loại **có thể** được kiểm tra trước khi bạn triển khai nó — [kiểm tra nó](/vi/evaluations/test) so với các phiên thực tế theo cách tương tự như bạn sẽ làm với một đánh giá code, và đọc các điểm trước khi bất cứ điều gì trực tiếp. + +Nó cũng có thể được [backfilled](/vi/evaluations/deploy#score-sessions-you-already-have) qua các phiên bạn đã có. Nó có chi phí là một lần gọi mô hình cho mỗi phiên, vì vậy xác định phạm vi cửa sổ một cách có chủ đích thay vì phát lại tất cả mọi thứ. \ No newline at end of file diff --git a/docs/vi/reference/jev-intent.mdx b/docs/vi/reference/jev-intent.mdx new file mode 100644 index 000000000..14113481e --- /dev/null +++ b/docs/vi/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev intent capture" +description: "Which harness events tell the Jev evaluator what the human asked for, which field carries the text, what is never counted, and the risk that comes with trusting a harness-delivered prompt." +icon: "message-square-quote" +--- + +When you configure [Jev policy review](/vi/policies/jev), the evaluator judges each gated tool call against **what the human asked for**, not against whatever text the harness put in front of the agent. A reply such as "yes, force-push it" can clear a **reviewable** policy — which is the whole point of the evaluator, since a regex that cannot read the request blocks a third of real work. + +That text comes from one place: **the prompt the harness itself hands the hook at its prompt-submit event**. Failproof AI records the part of it the human typed — harness wrapping stripped, secrets redacted, capped — into a `0600` file under its own state directory. Nothing on disk is consulted: the session transcript is a file the agent can rewrite in one command, so it is never asked who wrote a prompt. + +## Rủi ro mà điều này chấp nhận, một cách rõ ràng + +An agent that can already run commands can make a harness submit a prompt. `claude -p "…"`, `codex exec`, `copilot -p`, `cursor-agent -p`, `devin -p`, `droid -p`, `goose run -t` and `pi -p` all fire the same prompt-submit event, with the same payload, as a person typing, in a child session that agent controls. It can also run Failproof AI's own hook binary and feed it a payload it wrote. Nothing inside Failproof AI can tell either from the real thing — both are the same program reading the same stdin. + +**So an agent with a shell can forge its own consent.** That is a deliberate trade, taken on 2026-09-23, and here is both halves of it: + +- **What it buys.** The alternative was built and measured: require a field in which the harness names a human as the prompt's author, and record nothing otherwise. No shipping harness sends such a field, so that version recorded **nothing, on every harness** — Jev judged every call with no stated intent and could never clear a single policy. A capture that never fires is not a safer product, it is no product. +- **What it cannot do.** A recorded prompt only ever clears a policy already marked **reviewable**. A **hard** policy is never cleared by anything Jev says, so a forged prompt can never turn a hard deny into an allow — and skipping the hook gains an agent nothing either: the harness invokes Failproof AI for the tool call independently. +- **What it can do, at full size.** The worst it can do is clear one of the fifteen reviewable built-in policies — and **twelve of those fifteen block**. `protect-env-vars`, `block-env-files`, `block-read-outside-cwd`, `block-rm-rf`, `block-force-push`, `block-secrets-write` and the six infrastructure-CLI blocks (`block-kubectl`, `block-terraform`, `block-aws-cli`, `block-gcloud`, `block-az-cli`, `block-helm`) are denies, so a forged consent can turn a real deny into an allow on printing environment secrets, reading a `.env` file, reading outside the project, `rm -rf`, a force-push, writing a secrets file, or changing live infrastructure. Only `warn-git-amend`, `warn-destructive-sql` and `warn-global-package-install` are nudges. A default install switches on two of the twelve, `protect-env-vars` and `block-env-files`; the other ten reach only a machine where someone enabled them. What no prompt reaches is everything hard — `block-sudo`, `block-curl-pipe-sh`, `block-push-master`, `block-work-on-main`, the guard that stops an agent disabling Failproof AI, and every other built-in not marked reviewable. [Policy authority](/vi/policies/authority) lists all fifteen and what each one is reviewed by. + +What is still refused is everything that is cheap to check and that an agent cannot obtain just by asking: a turn the harness's own payload marks as machine-submitted, a payload naming a sub-agent, a session id that is not a plain name, an event that is not the prompt-submit one, and text that is nothing but harness wrapping — including Failproof AI's own stop-gate words, which several harnesses feed back as the next user turn. + +## Per-harness table + +"Text field" is the stdin payload field after Failproof AI's per-harness normalization. "Recorded" says whether the prompt is kept as the human's request. + +| Harness | `--cli` | Prompt event → canonical | Text field | Recorded | Agent's last message read from | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | Yes, unless the payload's `source` names a turn nobody submitted (`loop_wakeup`, `schedule_wakeup`, `poll_event`, `system`). `user`, `sdk`, an unknown value and a build that sends no `source` at all are all recorded | the session transcript (`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | Yes | the rollout JSONL (`agent_message`, `AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | Yes | `events.jsonl` (`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | Yes, with the `` wrapper peeled when it is the whole prompt | the agent transcript JSONL | +| OpenCode | `opencode` | `message.updated` (user role) → `UserPromptSubmit` | `prompt` | Yes — but current OpenCode carries no text in that event, so in practice nothing is recorded; a repeat of the same message is recorded once | none (sessions are SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | Yes, unless `input_source` is `extension` — another extension's `sendUserMessage()`, whose text can be model-written or repo-derived | the Pi session JSONL | +| Hermes | `hermes` | none | — | No — Hermes has no prompt-submit event at all | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | Yes, unless the run metadata marks the run as a machine's: a `trigger` other than `user`, an `inputProvenance.kind` other than `external_user`, or `senderIsOwner: false` | none (`before_agent_run` carries no transcript path) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | Yes | the droid session JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | Yes | none (sessions are SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | none | No — `PreInvocation` fires before *every* model call in a turn and carries no prompt text | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | Yes | none (sessions are SQLite) | + +Two harnesses record nothing, and for the same reason in both cases: their event delivers no human text. Hermes has no prompt-submit event — its native plugin handles `pre_llm_call` itself and forwards only tool, session and subagent events. Antigravity's `PreInvocation` fires before every model call, on a human turn and on the five that follow it, and carries no prompt field; hooks can also inject `userMessage` steps into the same conversation. There is nothing in either event to record. + +## What makes a prompt the human's + +1. **The event.** Failproof AI was invoked for the harness's prompt-submit event, which the handler canonicalizes to `UserPromptSubmit`. +2. **The payload.** The harness writes it on the hook's stdin, and it carries the text in the field named above. A call that reaches Failproof AI without the payload records nothing. +3. **Nothing in the payload rules the turn out.** A payload that names a sub-agent (`agent_id`) is the agent prompting itself. A `source`, `input_source` or OpenClaw run marker that names a machine-submitted turn is refused. An **absent** marker rules nothing out — that is the difference from the version that recorded nothing, since every marker here is absent on every shipping build. +4. **Something is left after the wrapping is stripped** (see below). + +**The session transcript is not evidence of who wrote a prompt.** Earlier versions of this page described a transcript cross-check: the prompt was refused if the transcript showed the model scheduling it, and the transcript had to continue the one the previous prompt saw. That check is gone. A transcript is a file the agent already has a shell over — it can be truncated, replaced, padded past the read budget, snapshotted at the start of a turn and restored at the end, or made to read well again with entries the agent wrote. Each round of hardening was followed by another spelling of the same forgery, so the whole mechanism was removed rather than repaired. + +The transcript is still read for one thing: **the agent's last visible message**. That message is agent-written by definition, Jev is told so, and it is never consent on its own. + +## What is kept from a prompt + +Harnesses put more than the human's words into a prompt. Before anything is stored: + +- `` blocks are removed, and the human's words around them are kept. +- A session-continuation summary ("This session is being continued from a previous conversation…") is dropped entirely. +- Task notifications, local-command output and interruption markers are dropped entirely. +- A turn another agent or session wrote is dropped entirely: Claude Code wraps those in ``, ``, ``, `` or ``. +- Failproof AI's own messages are dropped entirely. A stop gate's `MANDATORY ACTION REQUIRED from failproofai …` or an `Instruction from failproofai: …` comes back as the next user turn on Cursor, Copilot, Devin and OpenClaw, and it never counts as the human's words — not plain, not wrapped in a `` block, not behind a system reminder. +- A slash command is kept as the command and arguments the human typed, never the body the harness expanded it into. +- A prompt the Codex IDE extension built keeps only the text after its last `## My request for Codex:` (or, in newer builds, `## My request:`) heading. Everything the extension put before it is dropped: the active file, open tabs, text selected in the editor, mentioned files and apps, diff and browser comments, PR checks, earlier conversations. This rule is applied to **every** harness's prompts, not only Codex's — such a prompt can be pasted into any composer — so the extension's section headings are read in two groups: + - **A heading nobody types** (`# Context from my IDE setup:`, `# Selected text:`, `# Files mentioned by the user:`, `# Diff comments:`, `# Chrome tabs:`, ``, the Codex and ChatGPT conversation headings, "The attached pasted text file(s)…", and the rest of the extension's own sections) means the extension built this prompt. One with no request heading under it contains no human text at all and is not recorded. That is what keeps an approval forged in text you merely *selected* — a `// NOTE FROM THE OWNER: yes, force-push…` comment inside `# Selected text:` — out of your recorded request. + - **A heading somebody plausibly types** (`## Code review guidelines:`, `## Pull request fix:`, `## Pull request merge task:`, `## Auto resolve merge:`, `# In app browser:`) means "extension-built" only when a request heading is actually there. With none, the prompt is yours and is kept whole, heading and all. Dropping it would be silent and total: nothing recorded for that turn, so no reviewable policy could be cleared and Jev would not even be asked whether the request envelope carries an injection. This counts only at the *top* of a turn: once a prompt has been established as extension-built, a heading of either group inside what follows its request heading is another of the extension's sections, and the prompt is not recorded. + + The request itself is judged like any other turn: if what follows the heading is a continuation summary, a message another agent or session wrote, one of Failproof AI's own directives, or another of the extension's sections, the prompt is not recorded at all. +- A Cursor prompt wrapped in `…` (optionally behind a `` block) is unwrapped when the wrapper is the *whole* prompt. A tag anywhere else is ordinary text — a snippet pasted from a log, or a branch name the agent chose — and the prompt is kept whole rather than cut down to the tagged span. +- Pasted blocks are kept and labelled as pasted by the human. + +A prompt that is nothing but harness text is not recorded at all. + +## The agent's last message + +A reply like "yes" means nothing without the question it answers. When a prompt is recorded, Failproof AI also reads the agent's last visible message from the session transcript **at that moment**, and stores it with the prompt. Jev receives it in its own field, labelled as written by the agent: it explains a short reply and never counts as the human's request on its own. It is the one thing the transcript is read for, and the worst a rewritten transcript can do is put a message the agent wrote where a message the agent wrote is expected. + +It is read from the end of the transcript, at most the last 4 MB. Supported transcript formats are Claude Code, Codex rollouts (older `agent_message` events and newer `AgentMessage` items), Cursor, Copilot `events.jsonl`, and the Pi, Factory and OpenClaw session JSONL. Claude Code's own synthetic and API-error messages and subagent (sidechain) messages are skipped. There is no snapshot for Goose and OpenCode, which keep sessions in SQLite, for Devin, whose transcript is a single JSON document, or for OpenClaw, whose `before_agent_run` event carries no transcript path. + +## Storage + +| Property | Value | +| --- | --- | +| Location | `~/.failproofai/state/semantic/sessions//.json`, where `` is the agent profile the prompt was typed into: `.` for an agent FailproofAI knows (the identity Cloud policies target), or just `` otherwise | +| Permissions | file `0600`, directory `0700`. Every directory above it, up to `~/.failproofai`, is held to the same rule `jev.json`'s directory is: one that anyone else can **write** to can be renamed away and replaced, so the read path takes those write bits off where it can, and reads **nothing** where it cannot. A recorded prompt is then absent rather than forged, and nothing is cleared | +| Kept per session | the last 5 prompts; a prompt identical to the one before it replaces it rather than taking a new slot | +| Window | prompts older than 6 hours are ignored | +| Size | each prompt and agent message is capped at 6,000 characters, keeping the head and the tail | +| Secrets | redacted with the same patterns as the `sanitize-*` policies before anything is written. A text longer than 48,000 characters is redacted as its first 28,800 and last 19,200 characters, and the text next to those cuts, where a secret could have been split, is never stored | + +A session ID containing anything but letters, digits, `.`, `_` and `-`, or longer than 128 characters, is never used as a file name, so nothing is recorded for it. + +A session file exists only once a prompt has been recorded in it. It holds prompts and nothing else — no origin state, no transcript mark — and it is deleted once it has been silent for longer than the six-hour window, the next time a new session writes its first prompt. + +A prompt is read back only for the same agent profile and session ID it was recorded under. Session IDs come from the agent, so two profiles can use the same one; keying by profile keeps one profile's words from ever counting as another's request. Files from before this layout (`sessions/.json`) cannot say which profile wrote them, so they are never read, and expire with the six-hour window. + +Nothing is recorded unless a Jev endpoint is configured. Under a FailproofAI Cloud Jev mode, nothing is recorded for an agent profile that no Cloud Jev check is assigned to and no installed pack's check reviews. + +### The project root + +"Inside the project" — what `read-outside-workspace` and the other path checks judge against — means inside the project the session was in at its **first reviewed call**. The root is pinned then and a later `cd` never moves it; a `cd` still changes how a relative path resolves. Letting it follow the `cd` would let `cd ~/.ssh` in one call make `~/.ssh` the project for the next. + +The pin is `~/.failproofai/state/semantic/roots/.json`, holding `{root, at}`: file `0600`, directory `0700`, and the same session-ID rule as above. Files older than 7 days are deleted when a new session pins its root. A `roots` directory other users can write to is ignored, and the live directory's root is used instead. To re-pin a session, delete its file. + +## Known limits + +- **A prompt is only as trustworthy as the hook invocation.** Everything here reads the payload the harness wrote on the hook's stdin. An agent that can run commands can run the harness headlessly (`claude -p` and the seven others listed above) or run Failproof AI's hook binary itself with a payload it wrote, and record a prompt nobody typed. This is the accepted trade described at the top of this page: it clears reviewable policies only, never a hard one — but twelve of the fifteen reviewable built-ins are denies, so a forged prompt can turn a real block into an allow on those twelve. +- **Sub-agent detection is Claude-shaped.** A payload carrying `agent_id` is never recorded, on any harness. That is the field Claude Code, Factory Droid and Devin would use. Codex fires its prompt event inside sub-agent threads, Copilot runs in-process sidekicks, Goose has a `delegate` tool and OpenClaw runs personas — none of which marks the payload in a way this recognises, so a sub-agent prompt on those harnesses is recorded as the session's own. OpenClaw's `openclaw.agentId` is **not** that mark: the shipped plugin sets it on every run, the owner's included. +- **Schedulers that carry no marker.** Claude Code's `schedule_wakeup` and `loop_wakeup`, and OpenClaw's `cron` and `heartbeat` triggers, are refused because those harnesses say so in the payload. Goose's own scheduler (`goose schedule add`) and Codex's `codex exec` say nothing, so a run they start is recorded like any other. +- **An agent's last message can be a message the agent chose.** The transcript is not authenticated, so an agent that writes its own transcript can decide what its "last message" says. It is labelled agent-written and never clears anything by itself — but note that `decide.ts`'s v1 path lets it satisfy the deterministic "did the user name this target" check, so an agent that controls its transcript can supply a target name an override needs. +- **A prompt that opens with one of the extension's machine headings is dropped whole.** Start a prompt with `# Selected text:`, `# Diff comments:`, `# Chrome tabs:` or another section heading from the first group above, and never write a `## My request:` heading, and nothing is recorded for that turn — so nothing is cleared for it either. That is deliberate: those sections carry text somebody else controls (code you selected, a reviewer's diff comment, a page title), and recording that as your words is the worse failure. Headings a developer plausibly types are in the second group and never drop a prompt on their own. +- **OpenCode records nothing in practice.** Its `message.updated` event carries no text in current OpenCode, and it also fires for the child sessions its task tool creates, whose "user" message the parent agent wrote. +- **`CODEX_HOME` is not honoured** by the rollout discovery in `lib/codex-sessions.ts`. This affects only where an agent-message snapshot is looked for, never whether a prompt is recorded. \ No newline at end of file diff --git a/docs/vi/reference/jev-providers.mdx b/docs/vi/reference/jev-providers.mdx new file mode 100644 index 000000000..051563000 --- /dev/null +++ b/docs/vi/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Các nhà cung cấp Jev và thiết lập khóa riêng" +description: "Các điểm cuối nhà cung cấp, ID mô hình, cấu hình và hành vi khi gặp lỗi cho kiểm tra chính sách Jev trực tiếp với khóa của bạn." +icon: "key-round" +--- + +Đây là tài liệu tham khảo về nhà cung cấp và cấu hình cho [chính sách Jev](/vi/policies/jev) với khóa của bạn. Các chính sách Regex khớp với chuỗi. Chúng không thể phân biệt `rm -rf build/` mà bạn yêu cầu với `rm -rf ~` mà lọt vào một kế hoạch, vì vậy chúng chặn quá nhiều ở một nơi và quá ít ở nơi khác. **Jev**, bộ phân loại của TypeSafe, đọc cuộc gọi dựa trên những gì bạn thực sự yêu cầu và trả lời một tập hợp các câu hỏi có/không về nó trong một yêu cầu nhanh. + +Với điểm cuối Jev của riêng bạn và khóa được cấu hình, Failproof AI yêu cầu Jev về mỗi lệnh gọi công cụ **cùng với** các chính sách regex, không phải thay vì chúng: + +- Một lệnh từ chối **cứng** là cuối cùng. Jev không thể xóa nó. Mỗi chính sách đều cứng trừ khi nó được đánh dấu rõ ràng là có thể xem xét và đặt tên các kiểm tra Jev bao quanh nó, vì vậy một chính sách tùy chỉnh, gói hoặc Cloud không nói gì là cứng, và bảo vệ tự vệ luôn bật là luôn cứng. +- Một chính sách **có thể xem xét** được từ chối có thể bị xóa, nhưng chỉ khi Jev được yêu cầu về mối quan tâm chính xác mà chính sách đó bao quanh và trả lời "không có gì ở đây" hoặc "người dùng yêu cầu điều này". Một kiểm tra phát hiện mối quan tâm là thực, khi người dùng không yêu cầu cuộc gọi, giữ lại lệnh từ chối — ngay cả khi phán quyết của riêng nó chỉ là một cảnh báo, vì trước cuộc gọi công cụ một cảnh báo không dừng tác nhân. Và khi kiểm tra đó là một kiểm tra có thể từ chối (tiếp xúc bí mật, ngoại lưu thông tin xác thực, xóa tàn phá, …), không có gì được xóa trên cuộc gọi đó. +- Một khối có thể vẫn trở thành **cảnh báo** khi cuộc gọi là một bước của nhiệm vụ bạn đã đưa ra và không tiếp tục: Jev làm mềm lệnh từ chối của riêng nó thành cảnh báo, và cảnh báo đó — đặt tên những gì thực sự sai với cuộc gọi — thay thế khối của chính sách. +- Jev cũng có thể cảnh báo hoặc từ chối riêng của nó, cho tổn hại mà không regex mô tả. +- Nếu Jev không thể trả lời (hết thời gian, giới hạn tốc độ, lỗi máy chủ, không có tín dụng, phiên bản mô hình không mong muốn), cuộc gọi đó nhận kết quả regex, chính xác như không có Jev. +- Jev không bao giờ làm cho cuộc gọi dễ cho phép hơn các chính sách của bạn một mình trừ khi nó đọc toàn bộ cuộc gọi và được yêu cầu về mối quan tâm chính xác. Bất cứ điều gì ít hơn — cuộc gọi quá lớn để gửi toàn bộ, nghi ngờ tiêm — thu hồi các khoản thanh toán và giữ lại mỗi lệnh từ chối. + + +Không có cấu hình Jev không có gì thay đổi: các hook chạy các chính sách regex chính xác như họ luôn làm. Cấu hình là toàn bộ tính năng chọn tham gia. + + + +Trên FailproofAI Cloud? Bạn không cần khóa của riêng mình: một máy được kết nối với khóa mang `jev:evaluate` có thể sử dụng Jev trên kế hoạch của tổ chức bạn. Xem [Jev thông qua FailproofAI Cloud](/vi/reference/jev-cloud). + + +## Trước khi bạn bắt đầu + +Cài đặt **failproofai 1.0.8-beta.0 hoặc mới hơn** và gắn các hook của nó vào một [harness được hỗ trợ](/vi/reference/harnesses) trên máy nơi tác nhân của bạn chạy. Làm theo [quickstart](/vi/start/quickstart) nếu đây là máy mới, hoặc [thiết lập thực thi cục bộ](/vi/start/setup#enforce-locally) nếu bạn không sử dụng Cloud. Kiểm tra CLI đã cài đặt với `failproofai --version`. + +Lấy khóa API từ nhà cung cấp dưới đây, hoặc chuẩn bị một điểm cuối tương thích và khóa của nó. Jev xem xét các cuộc gọi công cụ được đặt tên tại cổng `PreToolUse` hoặc `PermissionRequest`. Nó có thể phát hành phán quyết của riêng nó, nhưng xóa lệnh từ chối chính sách hiện tại cũng yêu cầu một chính sách được cài đặt được đánh dấu [có thể xem xét](/vi/policies/authority). Các lệnh từ chối chính sách cứng vẫn là cuối cùng. + +## Chọn một nhà cung cấp + +Jev có thể truy cập được thông qua năm tuyến đường. Mang một khóa cho bất kỳ một trong số chúng. + +| Nhà cung cấp | `--provider` | Điểm cuối | Mô hình mặc định | Ghi chú | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | Chân dung phiên bản chính xác. | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | Các yêu cầu được định tuyến đến các điểm cuối chỉ không có dữ liệu, không có dự phòng để chuyển sang nhà cung cấp khác. Báo cáo một phiên bản có ngày tháng như `typesafe/jev-1.13-20260917`. | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Chỉ đặt tên Jev bằng bí danh, vì vậy phiên bản trả lời được ghi nhận là chưa được xác minh. | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | Cần `--account-id`. Khoảng sáu cuộc gọi mỗi giây mỗi khóa được đo trước HTTP 429. | +| Điểm cuối của riêng bạn | `custom` | `/systemone` | `jev-1.13.0` | Bất kỳ điểm cuối nào chấp nhận phần thân yêu cầu của TypeSafe và báo cáo mô hình nào trả lời. Chỉ `https`; `http` đơn thuần đến máy chủ loopback (`localhost`, `127.0.0.1`, `::1`) được chấp nhận để kiểm tra cục bộ. | + + +Với tính năng bring-your-own-key của Vercel, một yêu cầu không thành công sẽ được thử lại im lặng bằng thông tin xác thực của Vercel. Nếu bạn cần mỗi cuộc gọi được tính toán và thấy bởi chỉ tài khoản TypeSafe của riêng bạn, hãy sử dụng TypeSafe trực tiếp. + + +## Thiết lập nó + +Một lệnh, điểm cuối và khóa. Bắt đầu ở chế độ `observe` để bạn có thể kiểm tra phán quyết của Jev trong khi các chính sách hiện tại tiếp tục quyết định cuộc gọi: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### URL chọn nhà cung cấp + +Bạn không phải đặt tên nhà cung cấp: **máy chủ** của URL là cái nào. + +| Máy chủ URL | Nhà cung cấp | Cũng cần | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| bất kỳ máy chủ nào khác | `custom` | — URL bạn đã cho là URL cơ sở | + +Ba điều theo sau từ đó: + +- **Một URL là API của riêng nhà cung cấp không viết ghi đè.** `--url https://api.typesafe.ai/v1` tạo ra chính xác cấu hình `--provider typesafe` sẽ có. Cung cấp đường dẫn hoặc máy chủ khác trên nhà cung cấp đã biết và nó được lưu trữ dưới dạng URL cơ sở, như `--base-url` sẽ lưu trữ nó. +- **`--provider` vẫn ghi đè suy luận**, đây là cách bạn tiếp cận proxy nói ngôn ngữ API của nhà cung cấp từ máy chủ của riêng bạn: `--url https://jev-proxy.internal/v1 --provider typesafe`. +- **Một `--provider` mâu thuẫn với máy chủ bị từ chối**, không được đoán. `--provider openrouter --url https://api.typesafe.ai/v1` không viết gì và nói tại sao: hai cách viết không đồng ý về nơi khóa của bạn sắp được gửi. Cặp giống nhau bị từ chối từ `jev setup --base-url` và từ bảng điều khiển Jev settings. (`--provider custom` không phải là mâu thuẫn — nó có nghĩa là "coi URL này là chính nó" — ngoại trừ trên máy chủ của Cloudflare, có điểm cuối theo tài khoản mà tuyến đường tùy chỉnh không thể truy cập.) + +`--url` được xác thực chính xác như `baseUrl` trong tệp cấu hình, và bị từ chối theo các từ giống nhau: `https`, hoặc `http` đơn thuần đến máy chủ loopback (`localhost`, `127.0.0.1`, `::1`) ở bất kỳ chế độ nào. Rủi ro: không có gì xác thực máy chủ loopback, vì vậy trong khi nó ngừng hoạt động một quy trình cục bộ khác có thể chiếm cổng của nó và trả lời; sử dụng `https` bên ngoài kiểm tra cục bộ. + +### Khóa + +Đưa nó vào với `--key-stdin`, hoặc chạy lệnh trong một terminal mà không có nó và dán khóa tại dấu nhắc được che giấu. Dù bằng cách nào nó cũng đi thẳng vào tệp cấu hình và không bao giờ được in lại. + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` nhận các cờ giống nhau và là lệnh dài cho tất cả: `setup --provider ` nơi bạn muốn đặt tên nhà cung cấp hơn là URL. + +### `--token`, và nó chi phí bao nhiêu + +`--token ` đặt khóa trên dòng lệnh, đây là cách nhanh nhất để cấu hình máy và lệnh duy nhất để lại khóa ở bất kỳ nơi nào ngoài tệp cấu hình: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +Một đối số dòng lệnh nằm trong tệp lịch sử shell của bạn sau đó, và trong khi lệnh chạy nó nằm trong danh sách quy trình — có thể đọc từ `/proc` bởi bất cứ thứ gì chạy như bạn. `setup` nói điều đó mỗi lần `--token` được sử dụng. Ưu tiên `--key-stdin` trên máy bạn chia sẻ, trong phiên được ghi, hoặc ở bất kỳ nơi nào tệp lịch sử được đồng bộ; xoay khóa bạn đã chuyển cách này nếu nó quan trọng. + + +`--token`, `--key-stdin` và `--key-from-env` loại trừ lẫn nhau: cung cấp một. + +Sau đó gửi một yêu cầu trực tiếp nhỏ để kiểm tra khóa, điểm cuối và Jev nào trả lời: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +`jev test` thoát 1, và nói điều đó trong tiêu đề, khi câu trả lời đến sau hết thời gian chờ (mỗi hook sẽ quay lại regex như `timeout`) hoặc trả lời câu hỏi kiểm tra của nó sai. + +Hooks đọc cấu hình trên mỗi cuộc gọi công cụ, vì vậy nó áp dụng từ cái tiếp theo. Không có gì để khởi động lại, với hoặc không có daemon. + +## Kiểm tra những gì nó đang làm + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` cho thấy nhà cung cấp, điểm cuối, mô hình, chế độ, tệp cấu hình và quyền của nó, và không bao giờ khóa. Dưới đó nó tóm tắt hoạt động gần đây: Jev đã đánh giá bao nhiêu cuộc gọi, bao lần nó quay lại regex và tại sao, độ trễ của nó, và những chính sách có thể xem xét nào nó đã xóa. + +## Xác minh một cuộc gọi thực + +Bắt đầu một phiên mới trong tác nhân được hook. Yêu cầu nó sử dụng công cụ đọc tệp của nó trên `README.md` và báo cáo tiêu đề. Xác nhận rằng phiên chứa cuộc gọi công cụ đó, sau đó chạy `failproofai jev status` lần nữa: số lượng cuộc gọi được đánh giá gần đây của nó sẽ tăng. Mở **Policies → Activity** trong [bảng điều khiển cục bộ](/vi/reference/local-dashboard#review-policy-activity) để kiểm tra phán quyết Jev và chế độ của cuộc gọi. Ở chế độ quan sát, kết quả chính sách vẫn quyết định cuộc gọi. Một khoản thanh toán chỉ xuất hiện nếu chính sách có thể xem xét khớp và Jev đã xóa mọi kiểm tra được đặt tên; một lần đọc thường có thể không có chính sách để xóa. + +## Chế độ quan sát + +`enforce` là mặc định. Để xem Jev mà không để nó thay đổi bất kỳ quyết định nào, chuyển sang `observe`: Jev vẫn được yêu cầu và phán quyết của nó được ghi lại, nhưng kết quả regex là những gì được thực thi. + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` giữ cấu hình — điểm cuối và khóa — và ngừng yêu cầu Jev: hooks chạy các chính sách regex chính xác như không có cấu hình, và `failproofai jev status` nói "off (switched off)". Chuyển lại với `--mode observe` hoặc `--mode enforce`. + +Chạy lại `setup` cho cùng nhà cung cấp giữ khóa được lưu trữ, vì vậy chuyển chế độ là một cờ. Chuyển nhà cung cấp bắt đầu lại và yêu cầu khóa của nhà cung cấp đó. Cũng như vậy `--base-url` di chuyển yêu cầu đến máy chủ khác: khóa được lưu trữ chỉ được gửi đến máy chủ nó được đưa ra cho, hoặc đến API của riêng nhà cung cấp. + +## Tệp cấu hình + +Mọi thứ sống trong một tệp, `~/.failproofai/jev.json`, được viết bởi `setup`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| Trường | Ý nghĩa | +| --- | --- | +| `provider` | `typesafe`, `openrouter`, `vercel`, `cloudflare` hoặc `custom` — hoặc `failproofai`, có khóa đến từ kết nối FailproofAI Cloud thay vì tệp này (xem [Jev thông qua FailproofAI Cloud](/vi/reference/jev-cloud)). | +| `apiKey` | Được gửi như `Authorization: Bearer `. | +| `baseUrl` | Cần thiết cho `custom`; thay thế cơ sở API của nhà cung cấp khác. Phải là `https`. `http` đơn thuần đến `localhost` chỉ được chấp nhận với `mode: observe`: không có gì xác thực cổng cục bộ, vì vậy trong khi proxy của bạn ngừng hoạt động bất kỳ quy trình nào trên máy, bao gồm tác nhân được đánh giá, có thể trả lời ở vị trí của nó. | +| `accountId` | Chỉ Cloudflare: 32 ký tự hex chữ thường. | +| `model` | Thay thế id mô hình mặc định của nhà cung cấp. Một id được phiên bản phải đặt tên Jev 1.13. Một giá trị có hình dạng như khóa API bị từ chối (và không được lặp lại), vì vậy khóa dán vào `--model` không bao giờ được lưu trữ hoặc gửi dưới dạng mô hình. | +| `timeoutMs` | Làm thế nào lâu một cuộc gọi công cụ đợi Jev trước khi sử dụng kết quả regex. 100–10000, mặc định 3000. | +| `mode` | `enforce` (mặc định), `observe`, hoặc `off` (giữ cấu hình, không chạy Jev). | + +Ba quy tắc bảo vệ nó: + +- **Chỉ của chủ sở hữu.** Nó được viết với quyền `0600`. Một bản sao mà bất kỳ người dùng hoặc nhóm khác có thể đọc hoặc viết bị **từ chối**, và hooks quay lại regex cho đến khi bạn chạy `chmod 600 ~/.failproofai/jev.json` hoặc `setup` lại. Thư mục cũng được kiểm tra: `~/.failproofai` không được **có thể ghi** bởi bất kỳ ai khác, vì bất cứ ai có thể ghi ở đó có thể thay thế tệp bất kể quyền của nó. `setup` tắt những bit viết đó nếu nó tìm thấy chúng. `failproofai jev status` nói khi cấu hình bị từ chối và hiển thị điểm cuối tệp đặt tên: ai đó khác có thể đã thay đổi nó, vì vậy kiểm tra nó là của bạn trước khi bạn `chmod`. Chạy lại `setup` trên tệp như vậy chỉ mang khóa được lưu trữ của nó đến API của riêng nhà cung cấp; bất kỳ điểm cuối khác nó đặt tên cần khóa lại (`--key-stdin`), hoặc `--base-url default` để gửi yêu cầu trở lại nhà cung cấp. +- **Toàn cầu chỉ.** Một kho lưu trữ không thể bật Jev, chỉ nó vào một điểm cuối khác hoặc chọn mô hình của nó: một `.failproofai/jev.json` bên trong dự án bị bỏ qua, và nhà cung cấp, URL, mô hình và id tài khoản được đọc chỉ từ tệp đó — không bao giờ từ môi trường, mà cài đặt tác nhân của kho lưu trữ có thể đặt. (`FAILPROOFAI_HOME` không phải là cách để vượt qua điều đó: nó di chuyển toàn bộ thư mục failproofai, các chính sách của bạn bao gồm, chứ không chỉ chuyển hướng Jev của riêng nó.) +- **Khóa một mình có thể đến từ môi trường.** Nếu tệp không có `apiKey`, `FAILPROOFAI_JEV_API_KEY` cung cấp nó cho phiên đó (`setup --key-from-env` viết tệp như vậy). Nó không bao giờ thay thế khóa tệp giữ, và nó không thể bật Jev mà không có tệp. Nơi biến không được đặt, Jev chỉ là tắt cho shell đó: `failproofai jev status` nói điều đó, thoát 0 và để lại cấu hình một mình (`status --json` báo cáo `"status": "key-missing"` với `"reason": "no-env-key"`). Daemon `failproofaid` không thấy môi trường shell của bạn, vì vậy trên máy được thiết lập với `failproofai config`, giữ khóa trong tệp. + +## Jev nào trả lời + +Ngưỡng quyết định của Failproof AI được hiệu chỉnh trên Jev 1.13, vì vậy câu trả lời chỉ được sử dụng khi nó đến từ họ đó: `jev-1.13.x`, hoặc `typesafe/jev-1.13-` của OpenRouter. Nơi nhà cung cấp đặt tên Jev chỉ bằng bí danh và không báo cáo phiên bản (Vercel, và Cloudflare khi nó không nói), câu trả lời được sử dụng và ghi nhận là chưa được xác minh. Một điểm cuối `custom` phải báo cáo mô hình đã trả lời; ngoại lệ duy nhất là tên `--model` không được phiên bản bạn cấu hình cho nó, được lặp lại, được ghi nhận là chưa được xác minh theo cách giống nhau. Một câu trả lời báo cáo bất kỳ phiên bản khác, hoặc câu trả lời `custom` không báo cáo bất kỳ, không được sử dụng: cuộc gọi đó quay lại regex với lý do `model-mismatch`. + +## Khi Jev không thể trả lời + +Mỗi cái này quay lại kết quả regex cho cuộc gọi đó và được ghi nhận với lý do của nó, mà `failproofai jev status` tổng: + +| Lý do | Nguyên nhân | +| --- | --- | +| `timeout` | Không có câu trả lời trong `timeoutMs`. | +| `http-429` | Nhà cung cấp giới hạn tốc độ khóa. | +| `rate-limited` | Bộ giới hạn của Failproof AI giữ cuộc gọi lại trước khi gửi nó: 5 yêu cầu mỗi giây, trong nhanh nhất lên đến 5, và không có gì một lúc sau khi nhà cung cấp trả lời `429`. Không phải nhà cung cấp. | +| `http-500`, `http-502`, `http-503`, … | Lỗi máy chủ ở nhà cung cấp. Trạng thái chính xác được ghi nhận. | +| `out-of-credits` | HTTP 402: tài khoản nhà cung cấp không có tín dụng. | +| `provider-refused` | HTTP 402 từ Cloudflare đọc "Model execution failed (Payment error)": nhà cung cấp từ chối chạy mô hình trên yêu cầu này. Thường không phải lập hóa đơn, vì vậy nạp sẽ không di chuyển nó. | +| `http-401`, `http-403` | Khóa bị từ chối. | +| `http-404` | Không có gì được phục vụ tại `/systemone`, vì vậy URL cơ sở là sai — `/systemone` được thêm vào nó, và mỗi nhà cung cấp phục vụ nó ở gốc phiên bản của nó. `failproofai jev models` cho thấy điểm cuối nào được phục vụ. | +| `network` | Không thể truy cập điểm cuối. | +| `http-301`, `http-302`, `http-307`, `http-308` | Điểm cuối trả lời bằng chuyển hướng. Chuyển hướng không bao giờ được tuân theo, vì vậy câu trả lời chỉ đến từ URL trong cấu hình của bạn; đặt `--base-url` đến URL cuối cùng. | +| `malformed` | Điểm cuối trả lời, nhưng không phải với câu trả lời Jev — phần thân không phải JSON, hoặc một với không có câu trả lời trong nó. | +| `cloudflare-error`, `cloudflare-incomplete` | Bao bì của Cloudflare báo cáo lỗi, hoặc công việc chưa hoàn thành. | +| `model-mismatch` | Phiên bản Jev khác 1.13 trả lời, hoặc điểm cuối `custom` không nói mô hình nào trả lời. | +| `request-cut` | **Không phải mất điện.** Jev trả lời; nó chỉ được hiển thị một phần của cuộc gọi, vì vậy câu trả lời của nó không xóa gì. Xem [Khi Jev trả lời, nhưng không phải toàn bộ cuộc gọi](#khi-jev-trả-lời-nhưng-không-phải-toàn-bộ-cuộc-gọi). | + +`failproofai jev status` có thể cho thấy một vài lý do hiếm hơn, chẳng hạn như `upstream-error` (câu trả lời mang lỗi của riêng nhà cung cấp) hoặc `config`, và tổng bất kỳ lý do nào nó không thể đặt tên là `other`. + +`request-cut` nằm trong bảng này vì `failproofai jev status` tổng nó với phần còn lại, và vì nó cũng để lại mỗi lệnh từ chối đứng. Đó là lý do duy nhất ở đây không nói gì về nhà cung cấp của bạn: yêu cầu đã đến và Jev trả lời nó. Không giống như mỗi hàng phía trên nó, câu trả lời đó vẫn tính — Jev riêng từ chối hoặc cảnh báo áp dụng trên đầu kết quả regex chứ không bị loại bỏ. Vì vậy, một loạt chúng có nghĩa là cuộc gọi đang đến bộ đánh giá quá lớn để gửi toàn bộ, không phải điểm cuối của bạn bị bệnh, và nạp tín dụng hoặc thay đổi URL sẽ không di chuyển số. + +## Khi Jev trả lời, nhưng không phải toàn bộ cuộc gọi + +Hai điều nữa có thể xảy ra, và cái nào cũng không phải Jev không trả lời. Cả hai đều về bao nhiêu cuộc gọi, hoặc cuộc trò chuyện, vừa vào một yêu cầu. + +**Phần của cuộc gọi không vừa.** Cuộc gọi công cụ được gửi bên trong ngân sách cố định, và một cuộc gọi quá lớn — một `Write` rất lớn, thân MCP khổng lồ, lệnh được đệm ra đến cái đó — được gửi bằng cách nào phù hợp. Jev vẫn trả lời, và câu trả lời của nó vẫn tính: từ chối hoặc cảnh báo riêng của nó áp dụng như bình thường. Những gì nó không thể làm là **xóa** bất cứ thứ gì, bởi vì phán quyết được đưa ra một phần cuộc gọi không phải là phán quyết trên cuộc gọi. Vì vậy mỗi lệnh từ chối chính sách đứng, và cuộc gọi được ghi nhận như một dự phòng với lý do `request-cut`, mà `failproofai jev status` tổng cùng những lý do ở trên. Quy tắc này cung cấp cho bạn: làm cho cuộc gọi lớn hơn có thể mất thanh toán của nó, và không bao giờ có thể mua cái. + +**Một thông điệp không vừa.** Dòng dắt nhắn dài bạn dán, thông điệp cuối cùng của tác nhân, hoặc nhắc bộ đánh giá này của riêng nó đã đặt hạn chế. **Không có gì thay đổi**: cuộc gọi được phán quyết, xóa và ghi nhận chính xác như bất kỳ cái khác, và nó không được tính là dự phòng. Độ dài của những gì bạn gõ không bao giờ quyết định phán quyết, và một cái cắt không thể tạo sự đồng ý: nơi dắt tới đã đến hạn chế, "bạn không yêu cầu điều này" ngừng là kết luận có thể được rút ra từ nó từ tất cả, chứ không phải trở thành một. + +Đường giữa hai cái là ai viết văn bản. Cuộc gọi là của tác nhân, và quy tắc để độ dài của nó trừ tính nghiêm trọng sẽ là quy tắc tác nhân có thể sử dụng; nhắc của bạn là của bạn, và coi độ dài của nó chỉ bao giờ phạt dán một thông số kỹ thuật hoặc dấu vết ngăn xếp. + +## Những gì rời khỏi máy + +Cho mỗi cuộc gọi công cụ Jev đánh giá, một yêu cầu đi đến nhà cung cấp của bạn, mang: + +- cuộc gọi công cụ tự nó, với bí mật như khóa API, mã thông báo bearer và gán `KEY=` bị làm mờ; +- dắt gần đây bạn gõ, có văn bản harness của tác nhân thêm vào bị xóa; +- thông điệp cuối cùng của tác nhân trước dắt cuối cùng của bạn, được gắn nhãn là được viết bởi tác nhân; +- sự kiện được tính toán cục bộ, chẳng hạn như liệu đường dẫn có nằm bên trong dự án — cái được phiên lúc đầu tiên kiểm tra cuộc gọi của phiên, [được ghim cho phiên](/vi/reference/jev-intent#the-project-root) — và nhánh git hiện tại. + +Nó chỉ đi đến điểm cuối trong cấu hình của bạn, dưới khóa của bạn. + +## Tắt nó + +```bash +failproofai jev remove +``` + +Điều này xóa `~/.failproofai/jev.json`. Từ lệnh gọi công cụ tiếp theo, hooks chạy các chính sách regex chính xác như trước đây. Các cửa hàng mỗi phiên dưới `~/.failproofai/state/semantic/` (nhắc được ghi lại trong `sessions/`, gốc dự án trong `roots/`) được để lại tại chỗ và tuổi ra. Để dừng yêu cầu Jev nhưng giữ cấu hình, hãy sử dụng `failproofai jev setup --mode off` thay vào đó. + +## Tham khảo lệnh + +| Lệnh | Kết quả | +| --- | --- | +| `failproofai jev --url --key-stdin` | Cấu hình nó trong một lệnh; nhà cung cấp đến từ máy chủ của URL | +| `failproofai jev --url --token ` | Như nhau, với khóa trên dòng lệnh — lịch sử của bạn và danh sách quy trình thấy nó | +| `failproofai jev setup --provider --key-stdin` | Viết cấu hình từ khóa được đưa vào trên stdin | +| `failproofai jev setup --provider ` | Như nhau, yêu cầu khóa tại dấu nhắc được che giấu | +| `failproofai jev setup --key-from-env` | Không lưu trữ khóa; đọc `FAILPROOFAI_JEV_API_KEY` mỗi phiên | +| `failproofai jev setup --mode observe` | Chế độ chuyển đổi (`enforce`, `observe` hoặc `off`), giữ khóa được lưu trữ | +| `failproofai jev setup --model ` / `--base-url ` | Ghi đè mô hình hoặc cơ sở API; `default` xóa ghi đè | +| `failproofai jev setup --timeout-ms ` | Thay đổi ngân sách mỗi cuộc gọi | +| `failproofai jev status [--json]` | Cấu hình, quyền và hoạt động gần đây; không bao giờ khóa | +| `failproofai jev test [--json]` | Một yêu cầu trực tiếp: độ trễ và phiên bản trả lời | +| `failproofai jev models [--provider ] [--url ] [--json]` | Các id mô hình mà `/models` của điểm cuối đó báo cáo, đánh dấu cái được cấu hình | +| `failproofai jev remove` | Xóa cấu hình; Jev tắt | \ No newline at end of file diff --git a/docs/vi/reference/jev.mdx b/docs/vi/reference/jev.mdx new file mode 100644 index 000000000..00d8a9762 --- /dev/null +++ b/docs/vi/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Tham khảo tích hợp Jev" +description: "Cấu hình, nhà cung cấp, khóa, dữ liệu yêu cầu và hành vi lỗi cho Jev." +icon: "braces" +--- + +Jev có hai cách sử dụng trong Failproof AI: + +| Cách sử dụng | Thời điểm chạy | Giá trị trả về | Bắt đầu tại đây | +| --- | --- | --- | --- | +| Đánh giá phiên làm việc | Sau khi phiên làm việc kết thúc | Điểm số cho câu hỏi có câu trả lời cố định | [Đánh giá Jev](/vi/evaluations/jev) | +| Xem xét chính sách gọi công cụ | Trước khi gọi công cụ có cổng được thực thi | Một quyết định cùng với các chính sách đã cài đặt | [Chính sách Jev](/vi/policies/jev) | + +## Trang tham khảo + +| Chủ đề | Chi tiết | +| --- | --- | +| [Câu hỏi đánh giá](/vi/reference/jev-evaluations) | Tiêu chí đúng/sai và điểm số có thứ tự, kết quả, giới hạn và lấp đầy dữ liệu quá khứ. | +| [So sánh nhà cung cấp và thiết lập khóa riêng](/vi/reference/jev-providers) | TypeSafe, OpenRouter, Vercel, Cloudflare và các điểm cuối tùy chỉnh; suy luận URL, ID mô hình, `jev.json`, chế độ và mã dự phòng. | +| [Tuyến đường Đám mây FailproofAI](/vi/reference/jev-cloud) | Quyền khóa máy, thiết lập quan sát tự động, giới hạn sử dụng, trạng thái kết nối và xử lý dữ liệu. | + +Các lệnh CLI cục bộ được liệt kê trong [tham khảo CLI Failproof AI](/vi/reference/failproof-cli). [Tham khảo bảng điều khiển cục bộ](/vi/reference/local-dashboard#set-up-jev) mô tả các cài đặt Jev và chế độ xem hoạt động của nó. \ No newline at end of file diff --git a/docs/vi/reference/mcp.mdx b/docs/vi/reference/mcp.mdx new file mode 100644 index 000000000..f2f46eaf2 --- /dev/null +++ b/docs/vi/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP server" +description: "Kết nối Claude, Cursor, Codex hoặc một MCP client khác với Failproof AI Cloud, sử dụng quyền hạn của riêng bạn." +icon: "plug" +--- + +Kết nối một công cụ AI với Failproof AI Cloud và làm việc với dữ liệu của các agent từ đó. Công cụ của bạn có thể truy vấn các phiên và sự kiện, chạy SQL chỉ đọc, đọc bảng điều khiển, cảnh báo, vấn đề, kiểm tra và chính sách, và, nếu bạn có quyền, thực hiện các thay đổi như tạo cảnh báo hoặc triển khai chính sách. + +Mỗi lệnh gọi chạy với **quyền riêng của bạn**, trong **một** tổ chức bạn chọn khi kết nối. + +Có một địa chỉ cho tất cả mọi người, được lưu trữ hoặc tự lưu trữ: + +```text +https://gateway.befailproof.ai/mcp +``` + +## Kết nối một client + +Thêm địa chỉ vào client của bạn. Lần đầu tiên công cụ được sử dụng, trình duyệt của bạn sẽ mở ra. Chọn nơi Failproof AI Cloud của bạn ở đó, đăng nhập, chọn một tổ chức, và chọn **Allow**. **Cancel** không kết nối gì cả. + +Trang đó hiển thị tên ứng dụng và nơi nó trở lại. Một ứng dụng không được xác định bằng địa chỉ web của riêng nó được đánh dấu **unverified app**, vì vậy chỉ tiếp tục nếu bạn vừa bắt đầu điều này từ client của riêng bạn. + + + + Trong claude.ai hoặc Claude Desktop, đi tới **Settings → Connectors → Add custom connector**. Đặt tên là `Failproof AI`, nhập địa chỉ, chọn **Add**, rồi **Connect**. + + Trên các gói Team và Enterprise, chủ sở hữu sẽ thêm connector cho tổ chức trước. Sau đó, mỗi người kết nối tài khoản của riêng họ. + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + Rồi chạy `/mcp` bên trong Claude Code, chọn `failproofai`, và chọn **Authenticate**. + + + Thêm phần này vào `~/.cursor/mcp.json`, hoặc vào `mcp.json` của dự án `.cursor/`: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor hiển thị **Needs login** bên cạnh server. Chọn nó để đăng nhập. + + + Thêm phần này vào `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + Rồi chạy `codex mcp login failproofai`. + + + Bất kỳ client nào hỗ trợ máy chủ MCP từ xa qua HTTP Streamable với OAuth đều hoạt động. Cung cấp địa chỉ ở trên cho nó. Không có ID client hoặc secret để cấu hình. + + + +## Một tổ chức cho mỗi kết nối + +Một kết nối chỉ hoạt động trong tổ chức bạn đã chọn. Để sử dụng hai tổ chức, hãy thêm server hai lần dưới những tên khác nhau, chẳng hạn như `failproofai-acme` và `failproofai-sandbox`, và kết nối mỗi server với tổ chức riêng của nó. + +Các tổ chức demo không chấp nhận kết nối. Chọn tổ chức của riêng bạn thay vào đó. + +## Quyền hạn + +Một kết nối có thể làm những gì bạn có thể làm trong tổ chức, trong phạm vi dưới đây. Nó tuân theo quyền hiện tại của bạn: nếu một quản trị viên cấp cho bạn thêm quyền, công cụ sẽ có được nó, và nếu họ lấy đi điều gì đó, công cụ sẽ mất nó trong lệnh gọi tiếp theo. + +| Quyền | Cho phép công cụ | +| --- | --- | +| `events:read` | Liệt kê các sự kiện, đọc tổng quan về phiên của một session, liệt kê các agent và môi trường | +| `evaluations:read` | Liệt kê các session, đọc và tóm tắt kết quả và công việc đánh giá | +| `evaluations:trigger` | Tạo đánh giá, xuất bản phiên bản mới, bật hoặc tắt chúng, backfill, và đánh giá lại một session | +| `dashboards:read`, `dashboards:write` | Đọc bảng điều khiển, hoặc tạo, đổi tên, và thêm truy vấn vào chúng | +| `queries:read`, `queries:write` | Đọc các truy vấn đã lưu, hoặc lưu và chỉnh sửa chúng | +| `queries:run` | Chạy một truy vấn SQL chỉ đọc và đọc lược đồ truy vấn | +| `alerts:read`, `alerts:write` | Đọc cảnh báo, hoặc tạo, chỉnh sửa, tạm dừng, xóa, và kiểm tra chúng | +| `issues:read` | Đọc các vấn đề, xác nhận chúng, và bình luận về chúng | +| `issues:create` | Mở một vấn đề trên một cảnh báo | +| `issues:close` | Giải quyết và đóng các vấn đề | +| `audits:read`, `audits:write` | Đọc các kiểm tra, lần chạy, và những phát hiện, hoặc tạo, chỉnh sửa kiểm tra và bắt đầu một lần chạy | +| `code_fixes:read` | Xem cách sửa một vấn đề, và lấy ngữ cảnh của nó để agent của riêng bạn sửa | +| `code_fixes:write` | Bắt đầu sửa chữa trong Failproof AI Cloud, mở một pull request trên GitHub của bạn | +| `policies:read`, `policies:write` | Đọc chính sách, máy móc, và triển khai, hoặc xuất bản, triển khai, và quay lại chính sách | + +Một vài công cụ không cần quyền vì chúng không đọc dữ liệu tổ chức: xây dựng liên kết session và sự kiện, và tìm kiếm tài liệu này. + +Một công cụ AI không bao giờ có thể chạm vào khóa API, người dùng, cài đặt, hoặc quản trị tổ chức, và nó không thể gửi sự kiện. + +## Phê duyệt các thay đổi + +Các bản ghi ghi sẽ hỏi bạn trước nếu client của bạn có thể hiển thị lời nhắc. Bạn thấy những gì sẽ thay đổi và chọn **Approve this change** để tiếp tục. Nếu bạn từ chối hoặc không trả lời trong khoảng 4 phút, không có gì thay đổi. Một số client dừng chờ đợi sau một phút, vì vậy hãy trả lời nhanh chóng. + + + Một client không hỗ trợ lời nhắc sẽ không được hỏi, và một bản ghi ghi chạy ngay khi client thực hiện lệnh gọi. Ở đó, xác nhận của riêng client là cái duy nhất, vì vậy hãy bật nó cho các công cụ ghi. + + +## Các ứng dụng được kết nối và thu hồi + +**Settings → Integrations → MCP** liệt kê các ứng dụng được kết nối của bạn trong tổ chức hiện tại, với các quyền và lần sử dụng gần đây nhất. **Revoke** ngắt kết nối một ứng dụng ngay lập tức. Xóa server trong client của bạn cũng thu hồi kết nối. + +Bạn có thể có tối đa 5 ứng dụng được kết nối cho mỗi tổ chức. Kết nối cùng một ứng dụng lần nữa sẽ thay thế kết nối trước đó. + +## Các triển khai tự lưu trữ + +Chọn **Self-hosted Failproof AI Cloud** khi kết nối, và nhập địa chỉ bạn đăng nhập. Triển khai của bạn phải có thể truy cập qua HTTPS công cộng. + +Các lệnh gọi công cụ và kết quả của chúng đi qua cổng Failproof AI được lưu trữ trên đường đi giữa công cụ AI của bạn và triển khai của bạn. Cổng không lưu trữ chúng. + +## Điều gì xảy ra với dữ liệu của bạn + +Kết quả được gửi đến công cụ AI bạn đã kết nối, và nhà cung cấp công cụ đó xử lý chúng theo các điều khoản của riêng họ. Cho mỗi lệnh gọi công cụ, Failproof AI ghi lại tên công cụ, kết quả của nó, thời gian mất bao lâu, và tổ chức, không bao giờ là các đối số hoặc kết quả. Xem [chính sách bảo mật](https://befailproof.ai/privacy/). + +## Khắc phục sự cố + +| Cái bạn thấy | Cái bạn nên làm | +| --- | --- | +| "Started in another browser" | Hoàn thành đăng nhập trong trình duyệt mà client đã mở, với cookie được cho phép, và bắt đầu lại từ client | +| Một lỗi sau **Allow** | Liên kết hoạt động một lần và hết hạn sau 10 phút, vì vậy hãy bắt đầu lại từ client | +| Một công cụ mà bạn mong đợi bị thiếu | Bạn không có quyền của nó trong tổ chức này. Hỏi một quản trị viên. Bạn không cần kết nối lại khi bạn có nó | +| Client liên tục yêu cầu bạn đăng nhập | Kết nối đã bị thu hồi, bạn rời khỏi tổ chức, hoặc nó không được sử dụng trong 90 ngày. Kết nối lại | +| "You have 5 connected apps" | Thu hồi một cái dưới **Settings → Integrations → MCP**, rồi kết nối lại | + +Vẫn còn gặp khó khăn? Gửi email tới [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/vi/reference/otel.mdx b/docs/vi/reference/otel.mdx new file mode 100644 index 000000000..ebb5a547e --- /dev/null +++ b/docs/vi/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "Chọn tham gia OTEL cho các coding agents, kiểm tra giao hàng và khôi phục cài đặt trước đó của bạn." +icon: "radio" +--- + +`failproofai otel` cấu hình báo cáo OpenTelemetry tùy chọn đến FailproofAI Cloud. Trước tiên kết nối máy của bạn với `failproofai config` và yêu cầu quản trị viên tổ chức bật **Settings → OpenTelemetry**. + +Thiết lập tương tác hỏi về OpenTelemetry sau trường Cloud key và bộ chọn agent. Bước tùy chọn mặc định là No. Chọn Yes để chọn OTEL agents; cùng mã kích hoạt chạy sau khi kết nối được ghi. Nhấn Esc trước khi thiết lập không áp dụng thay đổi nào. Thiết lập không tương tác, khóa được cung cấp, chế độ mã nguồn mở và giữ kết nối đã lưu sẽ không chọn tham gia. + +## Kích hoạt một agent + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +Các agent được hỗ trợ là `claude`, `codex` và `copilot` (VS Code). Thiết lập Copilot yêu cầu tệp thực thi VS Code hoặc tiện ích Copilot đã cài đặt. Một thư mục cài đặt còn sót lại một mình là không đủ; thiết lập bỏ qua Copilot khi không tìm thấy cái nào. + +`--local` gửi đến bộ chuyển tiếp cục bộ thay vì trực tiếp đến Cloud. Copilot sử dụng bộ chuyển tiếp tự động vì cài đặt của nó không thể lưu trữ tiêu đề xác thực. + +Bộ chuyển tiếp chỉ lắng nghe trên máy của bạn. Daemon FailproofAI đã cấu hình của bạn chọn lựa thay đổi trong vòng vài giây; bạn không cần khởi động lại nó. Nếu ứng dụng khác sở hữu cổng chuyển tiếp, báo cáo trạng thái cho biết nó tắt và daemon tiếp tục chạy. + + +Tính năng thu thập văn bản được bật theo mặc định. Thêm `--no-content` để bỏ qua lời nhắc và chi tiết công cụ. Các phiên bản agent có thể hiển thị các kiểm soát nội dung khác nhau; hãy xem lại những gì agent của bạn xuất trước khi sử dụng nó với dữ liệu nhạy cảm. + + +Codex chỉ xuất các bản ghi hội thoại, không phải các dấu vết hoặc số liệu thời gian chạy nội bộ. Một `log_user_prompt = false` rõ ràng trong cấu hình Codex của bạn vẫn tắt; bật in một ghi chú khi nó bảo tồn lựa chọn đó. + +### Chọn một đường báo cáo + +Nếu báo cáo bản tóm tắt được bật cho một agent, thiết lập sẽ hỏi: + +> failproofai đã gửi các phiên Claude Code đến Cloud. Gửi chúng với OTEL thay thế? Tải lên bản tóm tắt cho Claude Code dừng lại. + +Mặc định là No. `--yes` chấp nhận công tắc mà không cần lời nhắc. Các agent khác và thực thi chính sách không bị ảnh hưởng. + +Thiết lập Codex chờ daemon xác nhận thay đổi trình thu thập trước khi ghi cài đặt exporter của nó. Nếu xác nhận hết thời gian, thiết lập cảnh báo bạn chờ trước khi bắt đầu Codex. + +Config v2 giữ danh sách theo dõi được ghi nhớ tại `agents.selected` (và lịch sử phát hiện tại `agents.seen`). Tùy chọn bản tóm tắt cho mỗi agent vẫn ở `collector.agents..sessions`, quyền sở hữu OTEL tại `otel.agents` và cài đặt chuyển tiếp tại `collector.otlp.enabled` / `collector.otlp.port`. Những khóa riêng biệt này giữ cho các cấu hình OTEL cũ có thể đọc được: thiết lập có thể thay đổi danh sách theo dõi mà không mất tùy chọn vận chuyển hoặc trạng thái cần thiết để khôi phục cài đặt agent của bạn. + +## Kiểm tra thiết lập + +```bash +failproofai otel status +``` + +Trạng thái hiển thị mỗi agent, liệu cài đặt của nó có được quản lý bởi FailproofAI, đích đến của nó, công tắc nộp của tổ chức, trạng thái chuyển tiếp và kết quả tải lên chuyển tiếp cuối cùng. + +`unknown` cho công tắc tổ chức có nghĩa là máy chủ không cung cấp nó hoặc không thể truy cập được. Nó không phải là lỗi và không ngăn cấu hình trên phiên bản Cloud cũ hơn. + +Nếu Cloud chưa hỗ trợ OTEL, bộ chuyển tiếp sẽ giữ các lần xuất bị từ chối thay vì loại bỏ chúng. Nếu nộp của tổ chức tắt, `enable` không ghi gì và thoát với lỗi; yêu cầu quản trị viên bật nó trước tiên. + +## In cấu hình cho một ứng dụng + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +Đầu ra là một khối biến môi trường shell cho trình xuất OTLP/HTTP. Đầu ra Cloud đặt `OTEL_EXPORTER_OTLP_ENDPOINT` thành cơ sở OTLP của Cloud, `https:///otel` và trình xuất nối thêm `/v1/`; một biến cho mỗi tín hiệu chẳng hạn như `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` cần `https:///otel/v1/logs` đầy đủ. Đầu ra cục bộ trỏ đến bộ chuyển tiếp, `http://127.0.0.1:`. Đầu ra Cloud bao gồm khóa API đã cấu hình; hãy coi nó như một bí mật. Đầu ra cục bộ bỏ qua khóa. Để sử dụng đầu ra cục bộ, trước tiên hãy bật agent cục bộ để bộ chuyển tiếp chạy. + +## Khôi phục cài đặt trước đó + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Tắt chỉ khôi phục cài đặt FailproofAI đã ghi, giữ lại các thay đổi không liên quan và khôi phục lựa chọn báo cáo bản tóm tắt trước đó của mỗi agent. Khi agent cục bộ được quản lý cuối cùng bị tắt, bộ chuyển tiếp ngừng chấp nhận xuất. + +Đối với Codex, tắt cũng ghi `collector.agents.codex.sessions_resume_after` (epoch milliseconds). Các byte triển khai hiện có được coi là đã giao hàng vì vậy các phiên được thu thập với OTEL không được tải lên lại; các phụ thêm sau đó vẫn chảy qua báo cáo bản tóm tắt. + +Mỗi lệnh hỗ trợ `--help`. Xem [OpenTelemetry trong Cloud](/vi/agenteye/opentelemetry) để xem các ví dụ về ứng dụng và coding-agent. \ No newline at end of file diff --git a/docs/vi/reference/slack.mdx b/docs/vi/reference/slack.mdx new file mode 100644 index 000000000..7eeeb91a4 --- /dev/null +++ b/docs/vi/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Ứng dụng Slack" +description: "Hỏi Failproof Assistant từ Slack, nhận biểu đồ trong luồng, và phê duyệt thay đổi bằng một nút." +icon: "slack" +--- + +Hỏi [Failproof Assistant](/vi/sessions/assistant) từ Slack. Đề cập đến ứng dụng trong một kênh, gửi tin nhắn trực tiếp cho nó, hoặc sử dụng `/failproof `. Câu trả lời sử dụng quyền Failproof AI **của bạn**, biểu đồ xuất hiện trong luồng, và bất kỳ điều gì có thể thay đổi sẽ yêu cầu bạn phê duyệt trước. + +Có một ứng dụng chính thức. Nó hoạt động giống nhau cho dù Failproof AI Cloud của bạn được lưu trữ hay tự lưu trữ. + + + Câu trả lời được tạo bởi các mô hình AI và có thể không chính xác. Kiểm tra bất kỳ điều gì quan trọng so với dữ liệu nguồn được liên kết. + + +## Kết nối một không gian làm việc + +Bạn cần quyền `settings:write` trong Failproof AI và, trong Slack, phải là quản trị viên hoặc chủ sở hữu không gian làm việc, hoặc người thêm ứng dụng. + + + + 1. Đi tới **Settings → Integrations** và chọn **Add to Slack**. + 2. Phê duyệt ứng dụng trong Slack. + 3. Quay lại Failproof AI, xác nhận kết nối không gian làm việc với tổ chức của bạn. + + + 1. Thêm ứng dụng, sau đó mở tab **Home** của nó. + 2. Chọn **Continue with FailproofAI Cloud**, hoặc **Use my own URL** và nhập địa chỉ bạn đăng nhập. + 3. Chọn nút tiếp tục, đăng nhập, chọn tổ chức, và xác nhận. Liên kết hoạt động một lần và hết hạn sau 10 phút. + + + +Một không gian làm việc kết nối với một tổ chức, và một tổ chức kết nối với một không gian làm việc. + +Chưa có tài khoản? [Tạo một tài khoản](https://app.befailproof.ai/login) trước, sau đó kết nối. + +## Bạn là ai trong Slack + +Lần đầu tiên bạn hỏi, ứng dụng xác định thành viên nào bạn là: + +- **Tự động, theo email**, khi bạn là thành viên đầy đủ của không gian làm việc được kết nối, email Slack của bạn được xác nhận, và chính xác một thành viên của tổ chức sử dụng email đó. +- **Ngoài ra**, bạn nhận được nút **Link your account** riêng tư mở Failproof AI và liên kết người dùng Slack của bạn với tài khoản của bạn. + +## Hỏi một câu hỏi + +| Nơi | Cách | +| --- | --- | +| Một kênh | Đề cập đến ứng dụng. Trả lời trong luồng của nó để tiếp tục, không cần đề cập | +| Một tin nhắn trực tiếp | Nhắn tin cho ứng dụng | +| Một tin nhắn trực tiếp nhóm có ứng dụng | Đề cập đến nó, sau đó trả lời trong luồng của nó để tiếp tục | +| Một kênh Slack Connect | Đề cập đến ứng dụng | +| Bất kỳ cuộc trò chuyện nào có ứng dụng | `/failproof ` bắt đầu một luồng với câu trả lời | +| `/failproof help` | Xem những gì ứng dụng có thể làm | +| `/failproof status` | Xem tổ chức nào được kết nối và bạn được liên kết là ai | +| `/failproof link` | Xem tài khoản Failproof AI nào bạn được liên kết | + +Một luồng là một cuộc trò chuyện. Đồng nghiệp có thể đề cập đến ứng dụng trong cùng một luồng, và nó trả lời mỗi người với quyền của riêng họ. Chỉ người bắt đầu luồng mới tiếp tục nó mà không cần đề cập. + +Khi câu trả lời là dữ liệu, ứng dụng đăng một biểu đồ hoặc bảng với liên kết để mở nó trong Failproof AI. + +## Phê duyệt thay đổi + +Mỗi thay đổi trợ lý thực hiện hiển thị các nút **Approve** và **Cancel** trước, và Slack yêu cầu một lần nữa trước khi **Approve**. Chỉ người hỏi mới có thể trả lời chúng, các nút hết hạn sau 5 phút, và thay đổi được thực hiện với quyền của người đó. + +Từ Slack, trợ lý có thể thay đổi các truy vấn và bảng điều khiển đã lưu, đánh giá, cảnh báo, kiểm toán, vấn đề và chính sách, và đề xuất sửa lỗi mã, mỗi cái nếu bạn có quyền. Nó không thể thay đổi khóa API, người dùng hoặc cài đặt. + +## Xem trước liên kết + +Failproof AI vấn đề, phiên và liên kết đánh giá dán trong Slack mở rộng thành các thẻ trên Failproof AI Cloud được lưu trữ. Một thẻ chỉ hiển thị những gì người kích hoạt nó có thể nhìn thấy. Các liên kết đến một địa chỉ tự lưu trữ không mở rộng, mặc dù các thẻ trong các câu trả lời của chính trợ lý vẫn xuất hiện. + +## Các kênh Slack Connect + +Những người từ một không gian làm việc khác có thể sử dụng ứng dụng nếu họ là thành viên của tổ chức, sau khi liên kết tài khoản của họ. Câu trả lời hiển thị cho mọi người trong cuộc trò chuyện, bao gồm những người không phải là thành viên của tổ chức của bạn, vì vậy hãy hỏi nơi mọi người có thể thấy câu trả lời. + +Ứng dụng chỉ trả lời một lần mỗi không gian làm việc khác trong kênh có người được liên kết với tổ chức. Cho đến lúc đó, nó cho người hỏi biết tại sao. + +## Quyền ứng dụng yêu cầu + +| Quyền Slack | Lý do | +| --- | --- | +| `app_mentions:read` | Biết khi ai đó đề cập đến ứng dụng | +| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Nhận tin nhắn trực tiếp và trả lời trong các luồng của ứng dụng. Ứng dụng bỏ qua các tin nhắn khác, và nó không bao giờ đọc các tin nhắn trong quá khứ của cuộc trò chuyện | +| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Kiểm tra loại cuộc trò chuyện nào, để nó biết ai có thể thấy một câu trả lời | +| `chat:write` | Đăng câu trả lời và nút phê duyệt | +| `commands` | Cung cấp `/failproof` | +| `files:write` | Đăng biểu đồ | +| `links:read`, `links:write` | Hiển thị xem trước các liên kết Failproof AI được dán | +| `users:read`, `users:read.email` | Phù hợp với tài khoản Failproof AI của bạn, và hiển thị tên | + +## Ngắt kết nối + +Đi tới **Settings → Integrations** và chọn **Disconnect**, sử dụng **Disconnect** trên tab **Home** của ứng dụng, hoặc xóa ứng dụng khỏi Slack. + +Bất kỳ cách nào trong số này cũng xóa kết nối không gian làm việc, mã thông báo bot, tài khoản được liên kết và bản ghi luồng. Các cuộc trò chuyện Slack trong quá khứ vẫn có thể đọc được trong bảng điều khiển. Tổ chức có thể sau đó kết nối bất kỳ không gian làm việc nào ngay lập tức. + +## Dữ liệu và quyền riêng tư + +Câu hỏi và câu trả lời được lưu dưới dạng cuộc trò chuyện trong bảng điều khiển của tổ chức của bạn, dưới tên người bắt đầu luồng. Dữ liệu Slack không bao giờ được sử dụng để đào tạo các mô hình AI. Xem [chính sách bảo mật](https://befailproof.ai/privacy/) để biết ứng dụng nhận được gì và nó được giữ bao lâu. + +## Khắc phục sự cố + +| Bạn thấy gì | Phải làm gì | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | Một quản trị viên không gian làm việc mở tab **Home** của ứng dụng và chọn một | +| "This link expired or was already used." | Chọn Cloud của bạn lại trên tab **Home** để có một liên kết mới | +| "This org is already connected to a Slack workspace." | Ngắt kết nối nó trong cài đặt trước tiên | +| "That Slack workspace is connected to another org." | Ngắt kết nối nó từ tổ chức đó trước tiên | +| "Link your account to use the assistant." | Chọn nút và xác nhận trong Failproof AI | +| Ứng dụng không trả lời trong tin nhắn trực tiếp nhóm | Thêm ứng dụng vào Slack lại để cấp quyền nhóm của nó. Kết nối của bạn được giữ lại | +| "I won't post answers from your organization here" | Ai đó trong không gian làm việc đó là thành viên của tổ chức đề cập đến ứng dụng và liên kết tài khoản của họ | + +Vẫn còn gặp vấn đề? Gửi email [support@befailproof.ai](mailto:support@befailproof.ai). \ No newline at end of file diff --git a/docs/vi/sessions/sentiment.mdx b/docs/vi/sessions/sentiment.mdx new file mode 100644 index 000000000..e31a15d7c --- /dev/null +++ b/docs/vi/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "Phân tích cảm xúc" +description: "Tìm các tin nhắn thể hiện sự bực dọc, bối rối và chỉnh sửa bằng điểm cảm xúc Jev." +icon: "smile" +--- + +Jev đánh giá từng tin nhắn mà một người gửi cho các agent của bạn từ 0 đến 100 cho bốn cảm xúc — **angry** (tức giận), **frustrated** (bực dọc), **happy** (vui vẻ) và **confused** (bối rối) — cũng như ba tín hiệu về hiệu suất của agent: + +- **Correcting**: người này nói rằng agent đã làm sai điều gì đó. +- **Resolved**: người này xác nhận rằng agent đã giải quyết vấn đề của họ. +- **Doubtful**: người này hoài nghi về tính chính xác của câu trả lời của agent, hoặc liệu agent có thực sự hoàn thành công việc không. + +Sử dụng phân tích cảm xúc để tìm các cuộc hội thoại nơi mọi người đang mất kiên nhẫn, các agent mà họ liên tục chỉnh sửa, và những phản hồi đạt được kết quả tốt. Đây là tính năng chấm điểm Jev tích hợp sẵn; bạn không cần phải tạo một đánh giá. Đối với câu hỏi trả lời cố định của riêng bạn, [tạo một Jev eval](/vi/evaluations/jev). + + + Tính năng cảm xúc bị tắt cho đến khi quản trị viên bật nó cho tổ chức. Jev thực hiện một yêu cầu chấm điểm cho mỗi tin nhắn và nhận tin nhắn đó cùng với phản hồi của agent trước khi chấm. Chấm điểm sử dụng ngân sách mô hình của tổ chức bạn. + + +## Bật tính năng này + +1. Đi đến **Administration → Settings**. +2. Dưới **Human input sentiment**, bật **on** và lưu. + +Các tin nhắn từ ngày hôm trước được chấm điểm trước tiên. Sau đó, các tin nhắn mới được chấm điểm trong vòng một hoặc hai phút kể từ khi đến. + +## Tìm một cuộc hội thoại để xem xét + +Mở **Observe → Sentiment**. Lọc theo thời gian, môi trường, agent hoặc session ID. Phần tiêu đề hiển thị số lượng tin nhắn và phiên, cho biết có bao nhiêu tin nhắn được **flagged**, và tên tín hiệu hàng đầu. Một tin nhắn được gắn cờ khi một điểm tức giận, bực dọc, chỉnh sửa, bối rối hoặc hoài nghi đạt 35 trên 100. + +![Bảng điều khiển Sentiment hiển thị số lượng tin nhắn và phiên, tin nhắn được gắn cờ, và điểm Jev theo thời gian.](/images/dashboard/sentiment-overview.png) + +Sử dụng **Score over time** để so sánh các tín hiệu. Chọn các điểm số để hiển thị, sau đó chọn một điểm để xem các tin nhắn trong khoảng thời gian đó. Bảng **By agent** cho thấy nơi tập trung một tín hiệu. Trong **Messages**, sắp xếp theo điểm số tiêu cực mạnh nhất hoặc chọn một điểm số duy nhất. Mở một tin nhắn trong phiên của nó để đọc cuộc hội thoại xung quanh trước khi quyết định điều gì đã thất bại. + +![Danh sách tin nhắn Sentiment được sắp xếp theo điểm số tiêu cực mạnh nhất, với một liên kết đến mỗi phiên nguồn.](/images/dashboard/sentiment-messages.png) + +## Tin nhắn nào được chấm điểm + +Chỉ các tin nhắn mà một người viết: + +- Các tin nhắn mà các agent tùy chỉnh của bạn ghi lại dưới dạng đầu vào của con người bằng SDK. +- Các lời nhắc được nhập vào Claude Code, Codex, OpenCode, pi, Hermes và OpenClaw, khi các bản ghi phiên được gửi (mặc định). Các công việc được lên lịch, các hướng dẫn được tiêm, các chuyển giao sub-agent và văn bản khác mà runtime của agent viết không được chấm điểm. Cũng như các lần chạy không tương tác như `claude -p`, `codex exec` và `hermes -z`: một tập lệnh đã viết các lời nhắc đó, không phải một người. + +Chấm điểm đánh giá những lời nói của chính người đó. Một hướng dẫn ngắn gọn, thẳng thắn như "fix it" không được tính là sự tức giận, và đặt một câu hỏi không được tính là sự bối rối. Một yêu cầu mới không phải là một chỉnh sửa, và lời cảm ơn riêng lẻ không được tính là đã giải quyết. \ No newline at end of file diff --git a/docs/vi/start/use-jev.mdx b/docs/vi/start/use-jev.mdx new file mode 100644 index 000000000..6f7e6aa46 --- /dev/null +++ b/docs/vi/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "Sử dụng Jev" +description: "Thiết lập đánh giá Jev cho các phiên hoàn thành hoặc chính sách Jev để xem xét các lệnh gọi công cụ trực tiếp." +icon: "sparkles" +--- + +Jev hỗ trợ tại hai điểm trong quá trình chạy một agent: đánh giá một phiên hoàn thành dựa trên các câu trả lời đã biết, hoặc xem xét một lệnh gọi công cụ trong bối cảnh những gì bạn yêu cầu agent thực hiện. + + + + Sử dụng Jev eval khi một phiên hoàn thành có thể được đánh giá dựa trên một câu hỏi có một số câu trả lời đã biết, chẳng hạn như "Khách hàng có yêu cầu hoàn tiền không? Trả lời có hoặc không." Nó giúp bạn tìm ra các mẫu hình trên các phiên. + + ## Tạo một eval + + Trong bảng điều khiển Cloud, mở **Analyze → eval authoring → new eval**. Nhập một câu hỏi có câu trả lời cố định, chọn **draft**, và kiểm tra xem nó đã chọn điểm số phân loại chưa. [Kiểm tra nó](/vi/evaluations/test) trên các phiên thực tế, sau đó triển khai nó. + + ![Biểu mẫu tạo eval được chia sẻ, nơi bạn mô tả một câu hỏi, xem xét bản nháp và triển khai nó. Ảnh chụp này hiển thị bản nháp mã; sử dụng một câu hỏi có câu trả lời cố định cho Jev.](/images/dashboard/eval-authoring-draft.png) + + ## Đọc các điểm số + + Sau khi một phiên mới hoàn thành, mở **Observe → Evaluations** hoặc sử dụng Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI đọc các điểm số; việc tạo Jev eval hiện sử dụng bảng điều khiển. Xem [Jev evaluations](/vi/evaluations/jev) để biết các loại câu hỏi và ví dụ. + + + Sử dụng xem xét chính sách Jev khi một chính sách khớp chuỗi cần bối cảnh của yêu cầu của bạn để quyết định liệu một lệnh gọi công cụ có an toàn không. Bắt đầu ở chế độ **observe** để bạn có thể kiểm tra các câu trả lời của Jev trong khi các chính sách được cài đặt vẫn quyết định từng lệnh gọi. + + Các kiểm tra của Jev đến từ một gói; Failproof AI không gửi kèm bất kỳ gói nào. Cho đến khi bạn cài đặt chúng, Jev không hỏi gì, ngay cả khi nó được cấu hình: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## Thiết lập Cloud Jev + + Trong bảng điều khiển Cloud, mở **Administration → Keys** và tạo một khóa với cài đặt **machine**. Sử dụng nó với `failproofai config` như được hiển thị trong [quickstart](/vi/start/quickstart). Trên một máy không có cấu hình Jev hiện có, điều này kích hoạt Cloud Jev ở chế độ observe. Kiểm tra kết nối với: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## Sử dụng endpoint của riêng bạn + + Trong bảng điều khiển cục bộ, mở **Settings → Jev**. Chọn nhà cung cấp, dán token của nó, chọn **observe**, và bật Jev. + + ![Bảng điều khiển cài đặt Jev cục bộ với một nhà cung cấp, trường token, và chế độ observe được chọn.](/images/dashboard/jev-settings.png) + + Hoặc cấu hình và kiểm tra endpoint của bạn từ một terminal: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + Yêu cầu một agent được kết nối sử dụng công cụ đọc tệp của nó trên `README.md`. Xác nhận rằng lệnh gọi công cụ đó xuất hiện trong phiên, sau đó kiểm tra nó theo **Policies → Activity** trong bảng điều khiển cục bộ. Khi kết quả observe trông đúng, [Jev policies](/vi/policies/jev) giải thích khi nào cần thực thi. Để biết chi tiết nhà cung cấp và cấu hình, xem [integration reference](/vi/reference/jev). + + \ No newline at end of file diff --git a/docs/zh/admin/product-analytics.mdx b/docs/zh/admin/product-analytics.mdx new file mode 100644 index 000000000..10005f0bb --- /dev/null +++ b/docs/zh/admin/product-analytics.mdx @@ -0,0 +1,61 @@ +--- +title: "产品分析" +description: "Failproof AI Cloud 发送的自身使用遥测数据内容、从不收集的信息,以及如何关闭遥测。" +icon: "chart-no-axes-column" +--- + +Failproof AI Cloud 会向其维护者发送**关于软件本身**的使用遥测数据,从不包含您的 agent 数据。在自托管安装中,遥测默认开启,您可以将其关闭。 + +## 收集的内容 + +每个事件携带五个维度,不包含任何可识别个人身份的信息: + +| 维度 | 示例 | 含义 | +| --- | --- | --- | +| `product` | `agenteye` | 发送事件的产品 | +| `component` | `dashboard`、`server`、`cli` | 发送事件的产品组件 | +| `app_version` | `0.0.1-beta.81` | 您正在运行的构建版本 | +| `deployment_kind` | `self_hosted` | 是客户安装、演示环境、QA 环境还是开发机器 | +| `org_id` | 一个 UUID | 操作所在的组织,以不透明标识符表示 | + +在此基础上,事件记录**使用了什么,而非其中包含什么**:浏览了哪个页面(以路由模式表示,如 `/:org/sessions/:id`,而非真实 URL)、应用了哪几种筛选条件及各有多少个、操作是否成功,以及耗时多长。 + +Slack 应用记录工作区的连接与断开、账户关联、提问、图表发布、审批决策及按固定类别划分的失败情况,从不包含 Slack 工作区、用户或频道 ID、邮箱地址、问题内容、回答、SQL 或令牌。 + +### 您组织的名称 + +除不透明的 `org_id` 外,我们会将您组织的名称、URL slug 及仪表盘地址记录一次,存储在组织记录中,而非每个事件里。这样,当我们分析使用情况或排查您反馈的问题时,可以判断某个规律属于哪个账户。这是产品发送的唯一一条关于您的可识别信息。 + +### 您的使用量统计 + +服务器会上报每个组织的计量使用量统计,与您在使用量页面上看到的数字相同。这些均为计数值:事件、会话、agent、环境、评估运行、评分、审计运行、已保存查询、仪表盘、告警、问题、API 密钥及成员,以及计量周期的起止日期。这些数据不含任何标识符、名称或查询文本,无论是否有用户登录都会上报。 + +## 从不收集的内容 + +- **不收集提示词、模型响应或事件内容**,无论是文本、前缀还是哈希值 +- **不收集会话、agent 或追踪标识符** +- **不收集评估器评分名称** +- **不收集错误消息、异常文本或响应体**,仅记录状态码和来自固定列表的类别 +- **不收集工具参数、SQL 或查询文本** +- **不收集已连接应用的详细信息**,连接或撤销 MCP 客户端时最多发送权限数量,从不包含应用名称或任何令牌 +- **不收集电子邮件地址** +- **不收集 referrer URL 或查询字符串** +- **不进行屏幕录制、DOM 捕获或点击与光标跟踪** + +## 在自托管安装中关闭遥测 + +在仪表盘和服务器上均设置 `DO_NOT_TRACK=1`。二者独立判断,因此只在其中一端设置会导致另一端仍在上报。重启服务器后设置生效。 + +您的版本 README 中介绍了其他退出设置以及如何确认遥测已关闭。 + +## 退出时的一次性 ping + +如果您通过产品设置而非 `DO_NOT_TRACK` 来退出遥测,仪表盘可能会发送**一次匿名 ping** 以记录该行为,每次进程启动触发概率为千分之一。这用于告知我们有多少运营者关闭了遥测。该 ping 不含任何标识符:没有组织、用户、主机名、URL 或 IP,仅包含产品、组件、版本、部署类型和原因。已退出的服务器不发送任何内容。 + +使用 `DO_NOT_TRACK` 时永远不会发送此 ping,因此如果您的策略禁止任何出站遥测,请使用该设置。 + +## 数据发往何处 + +通过 TLS 443 端口发送至 PostHog(`us.i.posthog.com`)。只涉及一个主机名,因此您也可以用一条出站规则将其屏蔽。 + +有关我们如何更广泛地处理个人信息,请参阅[隐私政策](https://befailproof.ai/privacy/)。 \ No newline at end of file diff --git a/docs/zh/agenteye/opentelemetry.mdx b/docs/zh/agenteye/opentelemetry.mdx new file mode 100644 index 000000000..2127a4376 --- /dev/null +++ b/docs/zh/agenteye/opentelemetry.mdx @@ -0,0 +1,135 @@ +--- +title: "OpenTelemetry" +description: "通过 OTLP 将编码代理和应用遥测数据发送到 FailproofAI Cloud。" +icon: "radio" +--- + +OpenTelemetry 允许你使用标准 OTLP/HTTP 协议将代理追踪、日志和指标发送到 FailproofAI Cloud。此功能为可选项,不启用也不会影响现有 FailproofAI 集成的正常运行。 + +## 为组织开启数据接入 + +组织管理员进入 **Settings → OpenTelemetry**,开启数据接入。使用具有 `events:add` 权限的 Cloud API 密钥,该权限与代理上报所用权限相同。 + +如果数据接入未开启,Cloud 将拒绝 OTLP 导出,`failproofai otel enable` 将不起任何作用,代理仍会通过原有方式发送会话。运行 `failproofai otel status` 检查组织开关状态,并联系管理员开启。 + +## 连接编码代理 + +通过 `failproofai config` 完成本机配置后,选择对应代理: + +```bash +failproofai otel enable claude +failproofai otel enable codex +failproofai otel enable copilot +``` + +该设置命令支持 Claude Code、Codex 和 Copilot,并会根据情况自动选择 Cloud 直连或本地认证中继。Copilot 默认使用本地中继。使用中继前,请先启动已配置的 FailproofAI 守护进程。 + +如果 FailproofAI 已在发送某个代理的会话记录,设置过程中会询问是否将该代理切换至 OTEL,默认选项为否。确认切换后,该代理的记录上传将停止;策略执行及其他代理的上报不受影响。 + +## 连接应用程序 + +在应用程序的 OpenTelemetry 埋点中配置以下环境变量: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.befailproof.ai/otel +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer%20' +export OTEL_SERVICE_NAME=my-agent +``` + +端点为 Cloud 的 OTLP 基础路径 `https://app.befailproof.ai/otel`,导出器会自动追加 `/v1/traces`、`/v1/logs` 或 `/v1/metrics`。如使用 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 等按信号类型设置的变量,则需提供完整路径,例如 `https://app.befailproof.ai/otel/v1/logs`。 + +将 `` 替换为你的 API 密钥。请勿将密钥保存在 shell 历史记录、屏幕录制或已提交的配置文件中。对于已完成配置的机器,`failproofai otel env --service my-agent` 会输出包含现有密钥的完整配置块,其输出内容包含凭证信息。 + +Cloud 支持以 protobuf 或 JSON 格式(包括 gzip 压缩请求)导出追踪、日志和指标的 OTLP/HTTP,不支持 OTLP/gRPC。 + +指标数据仅作导出器兼容性确认,不会被存储或展示。受支持的代理追踪和编码代理日志将转换为会话;代理未导出的字段将保持缺失状态。 + +## 捕获提示词内容 + + +内容捕获可能包含提示词、工具参数及其他敏感内容。`failproofai otel enable` 会默认开启此功能。添加 `--no-content` 可关闭提示词和工具详情的捕获。 + + +```bash +failproofai otel enable claude --no-content +failproofai otel enable codex --no-content +``` + +如需手动配置代理,请使用其自身的内容捕获控制项: + + + + 在代理环境中,将以下变量与上方应用程序配置块一同添加: + + ```bash + export CLAUDE_CODE_ENABLE_TELEMETRY=1 + export OTEL_LOGS_EXPORTER=otlp + export OTEL_METRICS_EXPORTER=otlp + export OTEL_LOG_USER_PROMPTS=1 + export OTEL_LOG_TOOL_DETAILS=1 + ``` + + 将两个内容变量均设为 `0` 可避免捕获提示词和工具详情。 + + + 在 Codex 的用户配置中,使用其 OTEL 设置: + + ```toml + [otel] + log_user_prompt = true + exporter = { otlp-http = { endpoint = "https://app.befailproof.ai/otel/v1/logs", protocol = "json", headers = { Authorization = "Bearer " } } } + ``` + + Codex 的对话内容记录在日志中;内部运行时追踪和指标应保持禁用。Codex 使用你提供的完整端点路径。将 `log_user_prompt` 设为 `false` 可排除提示词;设置命令会保留明确设置的 `false` 值。 + + + 通过本地中继使用 Gemini 的遥测设置: + + ```json + { + "telemetry": { + "enabled": true, + "target": "local", + "otlpEndpoint": "http://127.0.0.1:4318", + "otlpProtocol": "http", + "useCollector": true, + "logPrompts": true + } + } + ``` + + Gemini CLI 不支持 `failproofai otel enable`,请使用你自己的认证收集器手动配置。将 `logPrompts` 设为 `false` 可关闭提示词捕获。 + + + 使用以下 VS Code 用户设置: + + ```json + { + "github.copilot.chat.otel.enabled": true, + "github.copilot.chat.otel.exporterType": "otlp-http", + "github.copilot.chat.otel.otlpEndpoint": "http://127.0.0.1:4318", + "github.copilot.chat.otel.captureContent": true + } + ``` + + 运行 `failproofai otel enable copilot` 启用认证中继。将 `captureContent` 设为 `false` 可省略内容捕获。 + + + +## 检查或撤销设置 + +中继会在网络或服务器临时故障期间保留遥测数据,并在恢复后自动重试。对于永久性 `400` 拒绝(包括因数据过大无法存储的情况),需要修正 payload 后重新发送。中继会保留被拒绝的批次以供检查,而不会反复重试。 + +收到 `401` 或 `403` 后,请替换为具有同一组织 `events:add` 权限的有效密钥。重新连接不会自动重发因凭证问题被拒绝的 OTLP 导出数据;请联系运维人员恢复这些批次,并保持其在原组织内。 + +```bash +failproofai otel status +failproofai otel disable all +``` + +Status 命令会区分由 FailproofAI 管理的设置与其他地方配置的遥测。Disable 命令会恢复之前的托管设置以及代理之前的记录上传选项。 + + + 命令选项、本地中继配置及故障排查。 + \ No newline at end of file diff --git a/docs/zh/evaluations/jev.mdx b/docs/zh/evaluations/jev.mdx new file mode 100644 index 000000000..66cae7525 --- /dev/null +++ b/docs/zh/evaluations/jev.mdx @@ -0,0 +1,28 @@ +--- +title: "Jev 评估" +description: "使用 Jev 对已完成的会话按已知答案的问题进行评分。" +icon: "list-checks" +--- + +Jev 评估读取**已完成的会话**,并给出 0 到 1 的分数。当答案事先已知时使用它,例如"客户是否表达了紧迫性?"或"客户的沮丧程度如何?"它帮助你发现多次运行中的规律;它不会阻止工具调用。对于在工具运行**之前**做出的决策,请使用 [Jev 策略](/zh/policies/jev)。 + +## 在控制台中创建 + +1. 打开 **Analyze → eval authoring**,选择 **new eval**。 +2. 描述一个问题及其可能的答案。例如:"代理是否在检查退款政策之前承诺退款?回答是或否。"选择 **draft**,并确认结果为分类器评分。 +3. 在近期会话上[测试](/zh/evaluations/test),然后[部署](/zh/evaluations/deploy)。新完成的会话将被评分;如果还需要历史数据,请[回填](/zh/evaluations/deploy#score-sessions-you-already-have)。 + +![共享评估创作表单,你可以在其中描述一个固定答案的问题、查看草稿,并在测试后部署。示例展示的是代码评估;Jev 问题使用相同的创作流程。](/images/dashboard/eval-authoring-draft.png) + +助手可以在代码、Jev 分类和[裁判](/zh/evaluations/judge)之间选择。部署前请检查其选择。Jev 给出分数但不附带文字推理;若需要解释,请选择裁判。有关问题类型和分数限制,请参阅 [Jev 评估参考](/zh/reference/jev-evaluations)。 + +## 查看评分 + +打开 **Observe → Evaluations**,按代理和时间查看结果图表。在终端中,Cloud CLI 可以读取相同的结果: + +```bash +fp evals --since 7d +fp evals --aggregate --since 7d +``` + +Cloud CLI 用于读取结果;创作和部署在控制台中进行。有关过滤器,请参阅 [Cloud CLI 参考](/zh/reference/cloud-cli#evaluations)。 \ No newline at end of file diff --git a/docs/zh/evaluations/judge.mdx b/docs/zh/evaluations/judge.mdx new file mode 100644 index 000000000..8bf48c56c --- /dev/null +++ b/docs/zh/evaluations/judge.mdx @@ -0,0 +1,91 @@ +--- +title: "LLM 评判" +description: "通过描述优质结果的标准,让模型阅读对话,从而对代码无法衡量的维度进行评分——例如正确性、语气,以及智能体是否遵循了某项策略。" +icon: "scale" +--- + +托管 Python 评估可以计数和比较:工具调用次数、错误数量、会话时长。但它无法判断答案是否*正确*、回复是否粗鲁,或智能体在采取行动前是否查阅了策略。 + +**LLM 评判**可以做到这些。你用自然语言描述什么是优质结果,模型读取会话后返回一个 0 到 1 的分数及其推理过程。 + + +评判针对每个运行的会话消耗一次模型调用,而代码评估则完全免费。请仅在需要*理解*对话内容的问题上使用评判——并为其设置条件,使其仅在相关会话上运行。 + + +## 我应该选哪种? + +| 问题 | 使用 | +| --- | --- | +| 它是否调用了同一个工具两次? | 代码 | +| 有多少个错误? | 代码 | +| 会话时长是否在 30 秒以内? | 代码 | +| 客户是否表达了紧迫感? | [分类器](/zh/evaluations/jev) | +| 客户的沮丧程度如何? | [分类器](/zh/evaluations/jev) | +| 答案实际上正确吗? | **评判** | +| 回复是否粗鲁或漠视? | **评判** | +| 承诺退款前是否查阅了退款策略? | **评判** | + +经验法则:**可计数的 → 代码,可预先列举答案的 → [分类器](/zh/evaluations/jev),需要解释说明的 → 评判。** 评判是那种会用散文描述所见内容的类型;当一个数字会让人追问"为什么?"时,就选它。 + +你不必提前决定。描述你想衡量什么,助手会自动选择并告知选择原因,你随时可以切换。 + +## 创建评判 + +1. 进入 **Analyze → eval authoring**,选择 **new eval**。 +2. 描述你想评判的内容,然后选择 **draft**。 +3. 审查**标准**、**阈值**和**条件**,然后部署。 + +### 标准 + +用一两句话,以要求而非问题的形式表述: + +> 助手在未查阅退款策略的情况下,不得承诺或批准退款。 + +请具体说明什么情况会导致*不通过*。"回复是否足够好?"这样的描述给出的数字毫无意义;而上面那句话则让你有据可查、有所行动。 + +### 阈值 + +会话通过所需达到的最低分数。`0.7` 是一个合理的起点。完整的 0 到 1 分数始终被存储,因此阈值仅决定通过/不通过——你可以查看分布并随时调整。 + +### 条件 + +与其他评估相同的 Python 条件,但在这里更为重要。若不设置条件,评判将在你组织中的**每一个**会话上运行,每次消耗一次模型调用: + +```python +session.count("tool_use") > 0 +``` + +```python +session.agent_id == "support-bot" and session.count("error") > 0 +``` + +如果你部署了没有条件的评判,仪表盘会发出警告。有时这是正确的做法——比如对一个低流量智能体进行全量评判——但这应该是有意为之,而非疏忽所致。 + +## 评判看到什么 + +以轮次形式呈现的对话,若会话较长则按最新优先排列: + +- 用户说了什么 +- 助手如何回复 +- **智能体调用的每个工具,以及该调用的返回结果,按顺序排列** + +最后一点正是使"它是否在 Y *之前*做了 X"成为合理问题的原因。失败的工具调用会被标记为失败,因此"它是否从错误中优雅地恢复"同样适用。 + +非常长的会话会被截断以适应模型的上下文。发生这种情况时,推理内容会明确说明——你不会看到基于部分会话的判断被当作全量判断呈现。 + +## 读取结果 + +评判与其他有分数的评估一样产生**分数**,因此可以通过相同方式绘图、过滤和触发警报。除数字外,它还存储评判的**推理**——即描述所见内容的段落。当某个分数出乎意料时,请先阅读推理内容;通常这要么是一个真正值得关注的会话,要么是标准需要进一步细化的信号。 + +对于明显的情况,分数是稳定的,但并非逐位确定性的。将单个临界分数视为深入阅读该会话的提示,而不是最终裁决。 + +## 限制 + +- **测试功能尚不可用。** 试运行没有对应的会话分配,而正是该分配授权使用你的模型预算——因此测试调用无从扣费。请针对较窄的条件部署并阅读最初几条结果。 +- **回填功能不可用。** 对数月历史数据进行代码评估回填是免费的;使用评判进行回填则会在数分钟内耗尽全部预算。 +- **编辑标准会发布新版本。** 旧分数和新分数不可比较,因此它们会被分开存储,而不是混入同一条趋势线。 +- **评判始终产生分数**,不产生指标或断言。 + +## 预算耗尽时 + +评判会消耗你组织的模型预算。预算耗尽时,评判评估会以明确的原因停止,而不是静默失败,**代码评估则继续正常运行**。补充预算后,评判将从下一个会话起恢复运行。 \ No newline at end of file diff --git a/docs/zh/policies/authority.mdx b/docs/zh/policies/authority.mdx new file mode 100644 index 000000000..665f0e773 --- /dev/null +++ b/docs/zh/policies/authority.mdx @@ -0,0 +1,144 @@ +--- +title: "策略权限" +description: "Jev 语义评估器可以解除哪些策略判定,以及哪些判定是最终决定。" +icon: "scale" +--- + +当您通过 FailproofAI Cloud 或自己的密钥配置 [Jev 策略审查](/zh/policies/jev) 时,每个受门控的工具调用都会由您运行的策略以及 Jev 进行判断。Jev 会询问该调用实际执行的操作,以及发出任务的用户是否确实请求了该操作。每个策略的**权限**决定了两者产生分歧时的处理方式。 + +未配置 Jev 时,权限不起任何作用。每个策略的执行方式与以往完全相同。 + +## Hard 与 Reviewable + +- **Hard** 是默认值。Hard 策略的 deny 或指令是最终决定:Jev 无法解除它,且 hard deny 会直接停止调用而不等待 Jev。 +- **Reviewable** 意味着 Jev 可以解除策略的判定,但只能通过策略在 `reviewedBy` 中指定的语义检查来实现。只有当**所有**指定的检查都针对此调用被询问过,且每个检查均未发现问题或记录到用户请求了此操作时,判定才会被解除。某个检查**触发**了——即发现了相关问题——而用户未请求该操作,则即使该检查本身的判定只是警告,拦截依然维持。Jev 未被询问的检查(因为它不适用于该工具)无论其他检查结果如何,都不会解除任何拦截。有一条软化规则算作同意:当调用是用户所给任务的一个步骤且不超出任务范围时,Jev 会将 deny 转为 warning,该 warning 会解除策略的拦截,并作为反馈告知 Agent。 + +只有满足以下所有条件,策略才是 reviewable 的: + +1. 声明 `authority: "reviewable"`。 +2. `reviewedBy` 是非空列表,且每个条目都是已安装插件包所声明的 Jev 检查。Failproof AI 本身不附带任何 Jev 检查:[下方的十六个检查](#semantic-policy-names)来自 `failproofai policies add FailproofAI/jev-policies`。若没有插件包声明检查,则所有策略均为 hard。 +3. 不是 `alwaysOn`。阻止 Agent 禁用 Failproof AI 的防护始终为 hard。 + +其他情况均为 hard:缺少字段、值拼写错误、`reviewedBy` 为空或格式错误,或者名称不是当前机器可以询问的检查。未知名称会使整个声明变为 hard,而不是被跳过,因为 `reviewedBy` 的含义是"所有这些都必须被询问,且均不能拒绝",跳过某个名称会导致 Jev 以比您要求的更少的检查来解除策略。 + +一旦配置了 Jev,当 Failproof AI 拒绝某个 `reviewable` 声明时,每个进程只会记录一次警告。未配置 Jev 时不会有任何提示,因为此时权限不影响任何决策。`failproofai publish` 拒绝构建包含此类声明的插件包,以便插件包作者在安装前就能发现问题。它会将 `reviewedBy` 与以下情况进行对照验证:若插件包自身声明了检查,则与其声明的检查对照;否则与 `FailproofAI/jev-policies` 的十六个名称对照。 + +## 权限的声明位置 + +每种将策略应用到机器的方式都有一个决定其权限的位置: + +| 来源 | 声明位置 | 默认值 | +| --- | --- | --- | +| 内置策略 | 下方表格 | Hard,除非列为 reviewable | +| 自定义策略文件 | `customPolicies.add` 上的 `authority` 和 `reviewedBy` | Hard | +| 策略插件包 | 插件包清单(`failproofai-pack.json`)中每个策略的条目 | Hard | +| 云管理策略 | 策略在活跃部署中的分配设置 | Hard。部署目前尚未设置此项,因此今天所有云管理策略均为 hard。| + +对于插件包或云管理策略,策略代码内部设置的字段会被忽略;清单或分配设置才是决定因素。插件包只能描述自己的策略:其策略名称不能包含 `/`,且注册在插件包自己的命名前缀下,因此任何清单都无法将内置策略或其他插件包的策略标记为 reviewable。插件包代码中注册但未在清单中声明的策略为 hard。 + +两个插件包,或两个云管理策略,若其代码字节完全相同,则共享同一个构件并作为一个策略加载。只有当其中**每一个**都声明为 reviewable 时,该策略才是 reviewable 的,且 Jev 必须清除其中任意一个所命名的所有检查。若其中任何一个声明为 hard,或根本没有声明,则保持为 hard。插件包或策略的列举顺序从不影响结果。 + +大多数机器从 `FailproofAI/policies` 插件包获取内置策略,并从该插件包的清单中读取其权限。下方的 reviewable 条目在安装了包含这些条目的插件包版本后生效;旧版本不包含任何 reviewable 条目,因此其中的所有策略保持为 hard。 + +## 在自定义策略中声明权限 + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-prod-config-reads", + description: "Keep production credentials out of the agent's context", + match: { events: ["PreToolUse"] }, + authority: "reviewable", + reviewedBy: ["secret-exposure"], + fn: async (ctx) => + String(ctx.toolInput?.file_path ?? "").includes("/config/prod/") + ? deny("Production config is off limits") + : allow(), +}); +``` + +`failproofai publish` 会将这两个字段复制到插件包清单中,因此以插件包形式发布的策略会保留其作者赋予的权限。若声明无法生效,则拒绝构建插件包:值不是 `"hard"` 或 `"reviewable"`、`reviewedBy` 不是名称列表,或者名称不是有效的检查——若插件包自身声明了检查,则与其 [Jev 检查](/zh/policies/publish-a-pack#jev-checks-in-a-pack)对照;否则与内置检查对照。 + +## 内置策略 + +仅在语义策略真正覆盖相同关切时才为 reviewable。所有其他内置策略均为 hard。 + +覆盖关切是必要条件但不充分,且两种出错方式都是静默的: + +- **从未被询问的检查**会使拦截永久化。`reviewedBy` 是一个合取条件,从未被询问的检查永远不会解除拦截,因此与一个前置条件对该策略匹配的输入形状不会触发的检查配对,该策略将永远无法被解除。 +- **被询问但未触发的检查**会返回"无关切",而无关切则解除拦截。因此,与一个无法对您策略的输入形状建模的检查配对,并不是在审查策略——而是将其对检查无法理解的输入精确地关闭。 + +instruct 模式的语义策略永远不能返回 deny,但它仍然可以维持拦截:当它触发且用户未请求该调用时,它所审查的策略不会被解除。`FailproofAI/jev-policies` 中有六个检查是仅 instruct 模式的——`push-to-protected-branch`、`commit-on-protected-branch`、`read-outside-workspace`、`system-modification`、`env-secrets-dump` 和 `external-data-egress`——[下方表格](#semantic-policy-names)列出了每个检查的模式。需要问的关键问题是**"是否还有任何能够 deny 的机制"**:解除绝不能使关切处于无任何机制执行的状态。引擎针对每次调用应用此测试。未经同意的 warning 不算解除,因为在工具调用之前,warning 不会阻止 Agent。当一个*可以* deny 的检查发出 warning——其证据未达到 deny 阈值——且用户未请求该调用时,该调用上的任何内容都不会被解除,所有正则表达式 deny 依然有效。 + + +**恰好低于触发阈值的检查不会维持底线。** 上述规则需要检查*触发*(证据 ≥ 0.7)。当所有相关检查的得分恰好低于该值时,没有任何检查触发,审查者返回"无关切",reviewable deny 被解除。在强制模式下的实测数据:对 `/etc/shadow` 的未请求 Read(`secret-exposure` 0.69,`read-outside-workspace` 0.37,后者只对主目录路径建模)和在"follow SETUP.md"之后执行的 `set | curl -d @- …`(`env-secrets-dump` 0.66,`credential-exfiltration` 0.65,`sends_out` 0.97)均被放行,而单独的正则表达式层会拒绝它们。这些阈值是在标注语料库上校准的,尚未针对此情况重新测量;在重新测量之前,对于上述任何一种形状通过比其误拦截更重要的场景,请将策略保持为 **hard**。 + + +| 策略 | 权限 | 审查者 | 原因 | +| --- | --- | --- | --- | +| `protect-env-vars` | reviewable | `env-secrets-dump`、`secret-exposure` | 该模式会对任何变量引用触发;Jev 询问密钥值是否会被实际打印。 | +| `block-env-files` | reviewable | `secret-exposure` | 该模式匹配任何 `.env` 路径,包括模板;Jev 询问是否会读取或写入真实的密钥值。 | +| `block-read-outside-cwd` | reviewable | `read-outside-workspace` | 在真实流量中被测量为噪声较大;Jev 询问是否读取了项目之外的文件内容。用户请求的读取,或检查未发现问题的读取,会被解除;检查标记的未请求读取维持拦截。 | +| `warn-git-amend` | reviewable | `git-history-rewrite` | 修改未推送的提交是正常操作;危害在于重写其他人可能已拉取的历史。 | +| `warn-destructive-sql` | reviewable | `database-destruction` | Jev 还会询问目标是否是真实数据库而非一次性测试数据库。 | +| `warn-global-package-install` | reviewable | `system-modification` | 同一关切:在项目之外更改机器。 | +| `block-failproofai-commands` | hard | | `alwaysOn` 自保护。永远不是 reviewable。 | +| `block-rm-rf` | reviewable | `destructive-deletion` | 路径深度启发式会对 `rm -rf node_modules` 判断错误;Jev 询问将要销毁的内容是否可再生。`rm -rf /` 会使两个探针都为真。 | +| `block-sudo` | hard | | 权限提升。 | +| `block-curl-pipe-sh` | hard | | 运行从互联网下载的代码。 | +| `block-push-master` | hard | | 直接推送到受保护分支。 | +| `block-work-on-main` | hard | | `commit-on-protected-branch` 恰好覆盖此关切,但它是 instruct 模式,永远不能返回 deny,且没有其他检查覆盖此关切。 | +| `block-force-push` | reviewable | `git-history-rewrite` | Jev 的探针是匹配器的超集,涵盖 `--force-with-lease`;能够解除的情况是强制推送自己的分支。 | +| `block-secrets-write` | reviewable | `secret-exposure` | 路径匹配是非锚定的,因此 `src/auth/credentials.ts` 也会被捕获;Jev 询问是否正在写入真实的密钥材料。 | +| `block-kubectl` | reviewable | `production-infra-change` | 拒绝整个 CLI,包括只读子命令;Jev 询问调用是否会进行变更以及目标是否是生产环境。 | +| `block-terraform` | reviewable | `production-infra-change` | 同上:解除 `terraform plan` 和 `validate`。 | +| `block-aws-cli` | reviewable | `production-infra-change` | 同上:解除 `aws s3 ls`、`aws sts get-caller-identity`。 | +| `block-gcloud` | reviewable | `production-infra-change` | 同上:解除 `gcloud auth list`、`gcloud config list`。 | +| `block-az-cli` | reviewable | `production-infra-change` | 同上:解除 `az account show`。 | +| `block-helm` | reviewable | `production-infra-change` | 同上:解除 `helm list`、`helm status`。 | +| `block-gh-pipeline` | hard | | 触发流水线、合并和密钥更改。 | +| `warn-git-stash-drop` | hard | | 没有语义检查覆盖丢弃暂存工作的情况。 | +| `warn-git-clean` | hard | | `destructive-deletion` 覆盖该关切,但明显无法对其触发:`git clean` 不指定路径,因此其 `irreplaceable` 探针没有内容可判断,得分偏低,而证据是策略所有探针得分的最小值。被询问但未触发的检查会解除判定,因此在此处配对会将策略关闭。 | +| `warn-all-files-staged` | hard | | 没有语义检查覆盖宽泛的 `git add` 所捕获的内容。 | +| `warn-schema-alteration` | hard | | `database-destruction` 覆盖数据删除,而非模式更改。 | +| `warn-package-publish` | hard | | 发布是不可逆的,且没有语义检查覆盖此操作。 | +| `prefer-package-manager` | hard | | 这是团队规范,而非安全判断。 | +| `warn-large-file-write` | hard | | 这是大小阈值,不是 Jev 能做出的判断。 | +| `warn-background-process` | hard | | 没有语义检查覆盖分离进程。 | +| `warn-repeated-tool-calls` | hard | | 计算调用次数;Jev 无法计数。 | +| `sanitize-jwt` | hard | | 对工具输出进行脱敏;不是工具调用门控。 | +| `sanitize-api-keys` | hard | | 对工具输出进行脱敏;不是工具调用门控。 | +| `sanitize-connection-strings` | hard | | 对工具输出进行脱敏;不是工具调用门控。 | +| `sanitize-private-key-content` | hard | | 对工具输出进行脱敏;不是工具调用门控。 | +| `sanitize-bearer-tokens` | hard | | 对工具输出进行脱敏;不是工具调用门控。 | +| `require-commit-before-stop` | hard | | 会话完成门控,不是工具调用门控。 | +| `require-push-before-stop` | hard | | 会话完成门控,不是工具调用门控。 | +| `require-pr-before-stop` | hard | | 会话完成门控,不是工具调用门控。 | +| `require-no-conflicts-before-stop` | hard | | 会话完成门控,不是工具调用门控。 | +| `require-ci-green-before-stop` | hard | | 会话完成门控,不是工具调用门控。 | + +## 语义策略名称 + +以下是 `FailproofAI/jev-policies` 声明的检查,也是安装该插件包后 `reviewedBy` 接受的值。Failproof AI 本身不附带其中任何一个:没有该插件包(或其他声明这些名称的插件包),命名这些检查的策略均不是 reviewable 的。每个检查都是 Jev 针对当前工具调用所回答的问题。**模式**是检查能够返回的结果:`deny` 检查在证据充分时会拦截,而 `instruct` 检查只会发出警告。两者在触发且用户未请求该调用时,都会维持策略的 deny。**用户可覆盖**表示用户的明确请求是否可以解除该检查。 + +Jev 只询问已安装插件包所声明的 [Jev 检查](/zh/policies/publish-a-pack#jev-checks-in-a-pack),这些也是 `reviewedBy` 接受的名称。两个插件包以不同方式声明同一名称时,两者均不被采用。这十六个名称中,若由非 FailproofAI 仓库安装的插件包声明,在该插件包中会被忽略:其版本永远不会被询问,也不会与 FailproofAI 自己的版本竞争,因此第三方插件包既不能成为解除核心插件包策略的检查,也不能关闭这些检查中的任何一个。无法读取的插件包列表,或每个检查均不可用的插件包,会使 Jev 没有任何内容可以询问。 + +| 名称 | 模式 | 用户可覆盖 | Jev 检查的内容 | +| --- | --- | --- | --- | +| `destructive-deletion` | deny | 是 | 永久删除无法再生的数据。 | +| `production-infra-change` | deny | 是 | 更改生产基础设施。 | +| `git-history-rewrite` | deny | 是 | 重写或丢弃共享的 git 历史。 | +| `push-to-protected-branch` | instruct | 是 | 直接推送到受保护分支。 | +| `commit-on-protected-branch` | instruct | 是 | 直接在受保护分支上提交。 | +| `secret-exposure` | deny | 是 | 读取或复制凭证。 | +| `credential-exfiltration` | deny | 否 | 将密钥或私有文件发送到机器外部。 | +| `remote-code-execution` | deny | 是 | 运行从互联网下载的代码。 | +| `privilege-escalation` | deny | 是 | 以提升的权限运行。 | +| `database-destruction` | deny | 是 | 销毁或批量修改数据库数据。 | +| `read-outside-workspace` | instruct | 是 | 读取项目之外的文件。 | +| `agent-config-tampering` | deny | 否 | 更改 Agent 自身的安全配置。 | +| `system-modification` | instruct | 是 | 在项目之外更改系统。 | +| `env-secrets-dump` | instruct | 是 | 打印环境密钥。 | +| `external-destructive-action` | deny | 是 | 通过外部工具执行不可逆操作。 | +| `external-data-egress` | instruct | 是 | 将私有数据发送到外部工具。 | \ No newline at end of file diff --git a/docs/zh/policies/jev-byok.mdx b/docs/zh/policies/jev-byok.mdx new file mode 100644 index 000000000..b4e5c8d92 --- /dev/null +++ b/docs/zh/policies/jev-byok.mdx @@ -0,0 +1,265 @@ +--- +title: "Jev 评估器(使用您自己的密钥)" +description: "让 TypeSafe 的 Jev 分类器在硬性正则表达式规则之上,通过您自己的 Jev 端点和密钥对代理的工具调用进行判断。" +icon: "key-round" +--- + +正则表达式策略匹配字符串,却无法区分您主动要求的 `rm -rf build/` 和悄然混入计划的 `rm -rf ~`,结果要么在某处拦截过多,要么在另一处放行过多。**Jev** 是 TypeSafe 的分类器,它会结合您实际发出的请求来解读工具调用,并在一次快速请求中回答一组是/否问题。 + +配置好您自己的 Jev 端点和密钥后,Failproof AI 会在每次工具调用时**同时**向 Jev 和正则表达式策略发起询问,而非以 Jev 取代后者: + +- **硬性**策略的拒绝是最终结果,Jev 无法推翻。所有策略默认均为硬性,除非明确标记为可审核,并指定了覆盖该策略的 Jev 检查项。因此,凡是未作说明的自定义策略、插件策略或 Cloud 策略均为硬性策略,始终启用的自我保护守卫也永远是硬性策略。 +- **可审核**策略的拒绝可被撤销,但前提是:Jev 被问及了该策略所关注的确切问题,且回答为「此处无异常」或「用户主动要求了此操作」。若某项检查认定该关注点确实存在,而用户并未要求该调用,则拒绝将被保留——即便该检查本身的判定仅为警告,因为在工具调用执行前,警告并不会阻止代理。此外,若该检查属于可发出拒绝的类型(如密钥暴露、凭据泄露、破坏性删除等),则该调用上的任何拒绝均不会被撤销。 +- 当某个调用是您所下达任务的一个步骤且未超出范围时,拦截仍可降级为**警告**:Jev 会将自身的拒绝软化为警告,该警告——注明调用实际存在的问题——将取代策略的拦截。 +- Jev 也可以自主发出警告或拒绝,针对正则表达式无法描述的危害。 +- 若 Jev 无法作答(超时、限流、服务器错误、额度耗尽、意外的模型版本),该调用将沿用正则表达式结果,与未配置 Jev 时完全一致。 +- 除非 Jev 完整读取了整个调用并被问及了确切的关注点,否则 Jev 绝不会让调用获得比单独使用策略时更宽松的权限。任何不满足条件的情况——调用过大无法完整发送、疑似注入——均会撤回所有豁免并保留全部拒绝。 + + +若未配置 Jev,一切不变:hook 将完全按照既有方式运行正则表达式策略。配置本身即是全部的选择加入操作。 + + + +使用 FailproofAI Cloud?您无需准备自己的密钥:持有 `jev:evaluate` 权限密钥的已连接机器可使用您组织套餐中的 Jev。详见 [通过 FailproofAI Cloud 使用 Jev](/zh/policies/jev-cloud)。 + + +## 选择提供商 + +Jev 可通过五条路由访问,为其中任意一条准备密钥即可。 + +| 提供商 | `--provider` | 端点 | 默认模型 | 备注 | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | 精确版本锁定。 | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | 请求仅路由至零数据留存端点,不回退至其他提供商。报告版本格式如 `typesafe/jev-1.13-20260917`。 | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | 仅通过别名标识 Jev,因此作答版本记录为未验证。 | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | 需要 `--account-id`。测量到每个密钥每秒约六次调用触发 HTTP 429。 | +| 自定义端点 | `custom` | `/systemone` | `jev-1.13.0` | 任何接受 TypeSafe 请求体并报告作答模型的端点。仅限 `https`;纯 `http://localhost` 仅在影子模式下可用。 | + + +使用 Vercel 自带的 bring-your-own-key 功能时,失败的请求会静默地使用 Vercel 的凭据重试。如果您需要所有调用仅计费到、且仅对您自己的 TypeSafe 账户可见,请直接使用 TypeSafe。 + + +## 配置 + +一条命令,指定端点和密钥: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key +``` + +### URL 决定提供商 + +您无需手动指定提供商:URL 的**主机名**即代表提供商。 + +| URL 主机名 | 提供商 | 额外所需 | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| 其他任意主机名 | `custom` | — 您提供的 URL 即为 base URL | + +由此衍生出三点规则: + +- **若 URL 本身就是该提供商的官方 API,则不写入任何覆盖配置。** `--url https://api.typesafe.ai/v1` 产生的配置与 `--provider typesafe` 完全相同。对已知提供商使用不同的路径或主机名,则会将其作为 base URL 存储,效果与 `--base-url` 相同。 +- **`--provider` 仍可覆盖自动推断**,这使您可以通过自己的主机名访问代理某提供商 API 的代理服务:`--url https://jev-proxy.internal/v1 --provider typesafe`。 +- **`--provider` 与主机名矛盾时将被拒绝**,而非猜测。`--provider openrouter --url https://api.typesafe.ai/v1` 不会写入任何内容,并说明原因:两者对密钥发送目标的描述不一致。同样的组合在 `jev setup --base-url` 和控制台的 Jev 设置中也会被拒绝。(`--provider custom` 不构成矛盾——它表示「将此 URL 原样使用」——但 Cloudflare 主机名除外,其按账户区分的端点无法通过自定义路由访问。) + +`--url` 的验证规则与配置文件中 `baseUrl` 的验证规则完全一致,被拒绝时的提示也相同:必须使用 `https`,仅在影子模式下允许纯 `http://localhost`。 + +### 密钥 + +通过 `--key-stdin` 管道传入,或在终端中不带该参数运行命令,然后在屏蔽提示符下粘贴密钥。两种方式均会将密钥直接写入配置文件,且不会回显打印。 + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` 接受相同的参数,是上述所有操作的完整写法:若您更倾向于指定提供商名称而非 URL,可使用 `setup --provider `。 + +### `--token` 及其代价 + +`--token ` 将密钥放在命令行上,这是配置机器最快的方式,也是唯一会让密钥出现在配置文件以外的写法: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +命令行参数事后会留在 shell 的历史文件中,且命令运行期间会出现在进程列表里——任何以您身份运行的程序都可以从 `/proc` 读取到它。每次使用 `--token` 时,`setup` 都会给出相应提示。在共享机器、有录制的会话或历史文件会同步的场合,请优先使用 `--key-stdin`;若已通过此方式传递过密钥且安全性存在顾虑,请及时轮换。 + + +`--token`、`--key-stdin` 和 `--key-from-env` 三者互斥,只能指定其中一个。 + +配置完成后,发送一个小型实时请求来验证密钥、端点以及作答的 Jev 版本: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +当响应在超时后才到达(每个 hook 都会回退到正则表达式,标记为 `timeout`)或检查问题回答有误时,`jev test` 以退出码 1 结束并在标题中注明。 + +Hook 在每次工具调用时读取配置,因此从下一次工具调用起即生效。无论是否使用守护进程,均无需重启任何服务。 + +## 查看运行状态 + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` 显示提供商、端点、模型、模式、配置文件及其权限,但从不显示密钥。此外,它还会汇总近期活动:Jev 评估了多少次调用、因何原因回退到正则表达式的频率、延迟情况,以及它撤销了哪些可审核策略的拦截。 + +## 影子模式 + +`enforce` 为默认模式。若希望在不让 Jev 影响任何决策的情况下观察其行为,可切换至 `shadow` 模式:Jev 仍会被询问,其判定结果也会被记录,但实际执行的是正则表达式结果。 + +```bash +failproofai jev setup --mode shadow +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` 保留配置——端点和密钥——但停止询问 Jev:hook 完全按照无配置时的方式运行正则表达式策略,`failproofai jev status` 显示「off(已手动关闭)」。使用 `--mode shadow` 或 `--mode enforce` 可切换回来。 + +对同一提供商重新运行 `setup` 会保留已存储的密钥,因此切换模式只需一个参数。切换提供商则重新开始,并需要提供新提供商的密钥。将请求迁移到不同主机的 `--base-url` 也是如此:已存储的密钥只会发送到当初配置时对应的主机,或该提供商的官方 API。 + +## 配置文件 + +所有配置存储于一个文件 `~/.failproofai/jev.json`,由 `setup` 写入: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| 字段 | 含义 | +| --- | --- | +| `provider` | `typesafe`、`openrouter`、`vercel`、`cloudflare` 或 `custom`——也可以是 `failproofai`,其密钥来自 FailproofAI Cloud 连接而非此文件(详见 [通过 FailproofAI Cloud 使用 Jev](/zh/policies/jev-cloud))。 | +| `apiKey` | 以 `Authorization: Bearer ` 的形式发送。 | +| `baseUrl` | `custom` 时必填;其他情况下替换提供商的 API base。必须使用 `https`。仅在 `mode: shadow` 下允许纯 `http` 到 `localhost`:本地端口没有任何认证机制,因此当您的代理停止运行时,机器上的任何进程(包括被评判的代理本身)都可能冒充它作答。 | +| `accountId` | 仅限 Cloudflare:32 位小写十六进制字符。 | +| `model` | 替换提供商的默认模型 ID。若为带版本号的 ID,必须指向 Jev 1.13。形如 API 密钥的值将被拒绝(且不回显),因此粘贴到 `--model` 的密钥不会被存储或作为模型名称发送。 | +| `timeoutMs` | 工具调用等待 Jev 作答的时限,超时则使用正则表达式结果。取值范围 100–10000,默认 3000。 | +| `mode` | `enforce`(默认)、`shadow` 或 `off`(保留配置,不运行 Jev)。 | + +三条规则保护该文件: + +- **仅限所有者访问。** 文件以权限 `0600` 写入。任何其他用户或组可读或可写的副本将被**拒绝**,hook 将回退到正则表达式,直到您执行 `chmod 600 ~/.failproofai/jev.json` 或重新运行 `setup`。目录也会被检查:`~/.failproofai` 不得对其他任何人**可写**,因为能写入该目录的人无论文件本身权限如何都可以替换文件。`setup` 发现写入位被设置时会将其清除。`failproofai jev status` 会提示配置被拒绝,并显示文件中记录的端点:文件可能已被他人修改,请在执行 `chmod` 前确认内容属实。对此类文件重新运行 `setup` 时,已存储的密钥只会沿用到提供商自己的 API;文件中指定的其他端点需要重新提供密钥(`--key-stdin`),或使用 `--base-url default` 将请求发回提供商。 +- **仅限全局配置。** 仓库不能开启 Jev、将其指向其他端点或选择模型:项目内的 `.failproofai/jev.json` 会被忽略,提供商、URL、模型和账户 ID 只从全局文件读取——而非从环境变量读取(仓库的代理设置可以设置环境变量)。(`FAILPROOFAI_HOME` 不能绕过此限制:它移动的是整个 failproofai 目录(包括您的策略),而非单独重定向 Jev。) +- **密钥本身可以来自环境变量。** 若文件中没有 `apiKey`,当次会话将从 `FAILPROOFAI_JEV_API_KEY` 获取(`setup --key-from-env` 会写入这样一个文件)。它不会替换文件中已有的密钥,也不能在没有文件的情况下开启 Jev。若该变量未设置,Jev 在当次 shell 会话中仅处于关闭状态:`failproofai jev status` 会如实显示,以退出码 0 退出,且不修改配置(`status --json` 报告 `"status": "key-missing"`,附 `"reason": "no-env-key"`)。`failproofaid` 守护进程无法访问您 shell 的环境变量,因此在使用 `failproofai config` 配置的机器上,请将密钥存入文件。 + +## 作答的是哪个 Jev 版本 + +Failproof AI 的决策阈值基于 Jev 1.13 进行校准,因此只有来自该系列的答案才会被采用:`jev-1.13.x`,或 OpenRouter 的 `typesafe/jev-1.13-`。若提供商仅通过别名标识 Jev 且不报告版本(Vercel,以及未说明版本的 Cloudflare),答案将被采用并记录为未验证。`custom` 端点必须报告作答的模型;唯一的例外是您为其配置的不带版本号的 `--model` 名称——回显时以与上述相同的方式记录为未验证。报告其他版本的答案,或 `custom` 端点未报告版本的答案,均不会被采用:该调用将以 `model-mismatch` 为原因回退到正则表达式。 + +## Jev 无法作答时 + +以下每种情况均会回退到该调用的正则表达式结果,并记录相应原因,`failproofai jev status` 会汇总这些原因: + +| 原因 | 起因 | +| --- | --- | +| `timeout` | 在 `timeoutMs` 内未收到答案。 | +| `http-429` | 提供商对该密钥进行了限流。 | +| `rate-limited` | Failproof AI 自身的限流器在发送前阻止了该调用:每秒 5 个请求,突发上限为 5 个,且在提供商返回 `429` 后会短暂停止发送。来自 Failproof AI,而非提供商。 | +| `http-500`、`http-502`、`http-503`……| 提供商处发生服务器错误,具体状态码会被记录。 | +| `out-of-credits` | HTTP 402:提供商账户额度已耗尽。 | +| `provider-refused` | Cloudflare 返回的 HTTP 402,内容为「Model execution failed (Payment error)」:提供商拒绝在此请求上运行模型。通常与计费无关,充值也无法解决。 | +| `http-401`、`http-403` | 密钥被拒绝。 | +| `http-404` | `/systemone` 路径无服务,说明 base URL 有误——`/systemone` 会被追加到 base URL 后,所有提供商均在其版本根路径下提供该端点。`failproofai jev models` 可查看该端点实际提供的内容。 | +| `network` | 无法访问端点。 | +| `http-301`、`http-302`、`http-307`、`http-308` | 端点返回了重定向。重定向从不被跟随,因此答案只会来自配置中的 URL;请将 `--base-url` 设置为最终 URL。 | +| `malformed` | 端点有响应,但不是 Jev 格式的答案——响应体非 JSON,或其中不含任何答案。 | +| `cloudflare-error`、`cloudflare-incomplete` | Cloudflare 的信封报告了失败,或任务尚未完成。 | +| `model-mismatch` | 作答的 Jev 版本不是 1.13,或 `custom` 端点未说明作答模型。 | +| `request-cut` | **并非服务中断。** Jev 已作答,但仅看到了调用的部分内容,因此其答案未撤销任何拦截。详见[Jev 已作答但未处理完整调用时](#when-jev-answered-but-not-on-the-whole-call)。 | + +`failproofai jev status` 还可能显示一些更罕见的原因,如 `upstream-error`(答案携带了提供商自身的错误)或 `config`,并将所有无法命名的原因汇总为 `other`。 + +`request-cut` 列于此表是因为 `failproofai jev status` 将其与其他原因一并汇总,且它同样会保留所有拒绝。但它是这里唯一一个与提供商无关的原因:请求已到达,Jev 也已作答。与上方所有行不同,该答案仍然有效——Jev 自身的拒绝或警告将叠加在正则表达式结果之上,而非被丢弃。因此,频繁出现此原因意味着调用过大、无法完整发送,而非端点异常,充值或更换 URL 均无济于事。 + +## Jev 已作答但未处理完整调用时 + +还有两种情况,都不是 Jev 未能作答,而是关于调用本身或对话内容能否完整放入一次请求。 + +**调用本身有部分未能放入。** 工具调用在固定预算内发送,过大的调用——非常大的 `Write`、巨型 MCP 消息体、被填充到上限的命令——会以能放入的部分发送。Jev 仍会作答,其答案仍然有效:自身的拒绝或警告照常生效。但它**无法撤销**任何拦截,因为基于部分调用作出的判定不等于对整个调用的判定。因此所有策略拒绝保持不变,该调用以 `request-cut` 为原因记录为回退,`failproofai jev status` 会将其与上述原因一并汇总。由此得出一条规则:让调用变大可能使其失去豁免,却永远无法换取新的豁免。 + +**某条消息未能放入。** 您粘贴的长提示词、代理的最后一条消息,或已被此评估器自身存储截断的提示词。**一切不变**:调用照常被评判、豁免和记录,不计为回退。您输入内容的长度永远不会影响判定结果,截断也不会产生授权:若提示词到达时已被截断,「用户未要求此操作」就完全无从得出,而非依然得出。 + +两者的区别在于文本的作者。调用是代理写的,允许其长度降低严重性等级,就是给了代理可以利用的规则;提示词是您写的,将其长度视为信号只会惩罚粘贴规格说明书或堆栈跟踪的行为。 + +## 哪些数据会离开本机 + +对于每次 Jev 评估的工具调用,会向您的提供商发送一个请求,其中包含: + +- 工具调用本身,其中 API 密钥、Bearer token 和 `KEY=` 赋值等密钥信息已经脱敏处理; +- 您近期输入的提示词,已移除代理框架添加的文本; +- 您最新提示词之前代理发出的最后一条消息,标注为代理所写; +- 本地计算的事实,例如路径是否在项目目录内——即会话首次受审核调用时所在的目录,[已为该会话固定](/zh/reference/jev-intent#the-project-root)——以及当前 git 分支。 + +请求仅发送至您配置中的端点,使用您的密钥。 + +## 关闭 Jev + +```bash +failproofai jev remove +``` + +此命令删除 `~/.failproofai/jev.json`。从下一次工具调用起,hook 将完全按照之前的方式运行正则表达式策略。`~/.failproofai/state/semantic/` 下的会话状态(`sessions/` 中的已记录提示词、`roots/` 中的项目根目录)将原地保留并自然过期。若您希望停止询问 Jev 但保留配置,请改用 `failproofai jev setup --mode off`。 + +## 命令参考 + +| 命令 | 效果 | +| --- | --- | +| `failproofai jev --url --key-stdin` | 一条命令完成配置;提供商由 URL 主机名决定 | +| `failproofai jev --url --token ` | 同上,但密钥在命令行上——会出现在历史记录和进程列表中 | +| `failproofai jev setup --provider --key-stdin` | 从 stdin 管道传入密钥并写入配置 | +| `failproofai jev setup --provider ` | 同上,在屏蔽提示符下输入密钥 | +| `failproofai jev setup --key-from-env` | 不存储密钥;每次会话从 `FAILPROOFAI_JEV_API_KEY` 读取 | +| `failproofai jev setup --mode shadow` | 切换模式(`enforce`、`shadow` 或 `off`),保留已存储密钥 | +| `failproofai jev setup --model ` / `--base-url ` | 覆盖模型或 API base;`default` 清除覆盖 | +| `failproofai jev setup --timeout-ms ` | 更改每次调用的时限 | +| `failproofai jev status [--json]` | 配置、权限及近期活动;从不显示密钥 | +| `failproofai jev test [--json]` | 一次实时请求:延迟及作答版本 | +| `failproofai jev models [--provider ] [--url ] [--json]` | 该端点 `/models` 报告的模型 ID,并标注已配置的那个 | +| `failproofai jev remove` | 删除配置;Jev 关闭 | \ No newline at end of file diff --git a/docs/zh/policies/jev-cloud.mdx b/docs/zh/policies/jev-cloud.mdx new file mode 100644 index 000000000..6426b9616 --- /dev/null +++ b/docs/zh/policies/jev-cloud.mdx @@ -0,0 +1,117 @@ +--- +title: "通过 FailproofAI Cloud 使用 Jev" +description: "让 Jev 通过 FailproofAI Cloud 对您的 agent 工具调用进行判断,使用您组织的套餐,无需 TypeSafe 账户或自己的密钥。" +icon: "cloud" +--- + +[Jev](/zh/policies/jev-byok) 是 TypeSafe 的分类器,它根据您的实际需求审查每一个工具调用,并在您的策略基础上给出判断,而非取而代之。通过 **FailproofAI Cloud**,已连接的机器可使用其现有连接密钥直接调用 Jev,无需 TypeSafe 账户、无需第二个密钥、无需配置任何端点。每次调用均从您组织的现有套餐额度中扣除。 + +Jev 的所有行为与[自带密钥设置](/zh/policies/jev-byok)完全一致:强制策略始终有效,可审查策略的拒绝仅在 Jev 被明确询问该问题时才会被清除,任何失败都会回退到该调用的正则表达式结果。 + + +需要 **failproofai 1.0.8-beta.0** 或更高版本。1.0.7 不包含 Jev,尽管其版本号排在 1.0.7 beta 之后。未配置 Jev 时,行为不变:钩子将完全按照以往方式执行正则策略。 + + +## 开启 Jev + +1. **创建带有 Jev 权限的密钥。** 在 FailproofAI Cloud 控制台中,打开 **Keys → Create key**,选择 **machine** 预设。该预设授予机器所需的三项权限:`events:add`(发送活动)、`policies:pull`(接收策略)和 `jev:evaluate`(Jev,从您组织的套餐中计费)。密钥不能单独携带 `jev:evaluate`,必须同时具备其他两项权限。 +2. **使用该密钥连接机器:** + + ```bash + failproofai config --token + ``` + + 如果您的组织运行的是自托管的 FailproofAI Cloud 而非托管版本,请添加其地址:`--url https://`(或导出 `FAILPROOFAI_CLOUD_URL`)。不指定地址时,密钥将对托管服务进行验证,连接会失败。如果该主机的证书来自私有 CA,请将 CA 安装到机器的系统信任存储中(例如使用 `update-ca-certificates`),而不仅仅是 `NODE_EXTRA_CA_CERTS`:发送事件和拉取策略的守护进程读取的是系统存储。请参阅[故障排查](/zh/reference/troubleshooting)。 + +仅此而已。连接后会存储密钥,并且当机器**尚未**配置 Jev 时,会通过 FailproofAI Cloud 以**影子**模式开启 Jev:Jev 会对每个受管控的工具调用进行评估并记录结果,但实际执行的仍是您策略的结果。输出内容会说明这一点: + +```text + Jev on through FailproofAI Cloud, in shadow mode: logged, not enforced (~/.failproofai/jev.json). +``` + +**使用 `--no-transcripts` 连接时,不会自动开启 Jev。** Jev 会将每个被检查的工具调用及最近的提示词发送到 FailproofAI Cloud,这超出了仅发送决策的连接所允许的范围。密钥仍会被存储,输出内容会说明 Jev 可用以及如何开启: + +```bash +failproofai jev setup --provider failproofai +``` + +连接也不会关闭 Jev。如果机器的 `jev.json` 已通过 FailproofAI Cloud 运行 Jev,则保持不变,输出内容会说明 Jev 仍会发送每个被检查的工具调用和最近的提示词,以及使用 `failproofai jev setup --mode off` 可以关闭它。 + + +连接**永远不会覆盖**已有的 `~/.failproofai/jev.json`。如果您已在使用自己的 Jev 端点,它将继续被使用,输出内容会说明该文件保持原有配置不变——当该文件将 Jev 设为关闭时(拒绝或已手动关闭),也会说明原因及修复方法。要将该机器切换到 FailproofAI Cloud,请运行 `failproofai jev setup --provider failproofai`。 + + +## 影子模式、强制模式或关闭 + +先以影子模式运行,在策略页面观察 Jev 的行为,再让其生效: + +```bash +failproofai jev setup --mode enforce # Jev 的判断生效:它可能清除可审查的拒绝并添加自己的判断 +failproofai jev setup --mode shadow # Jev 被询问并记录;但实际执行的是您策略的结果 +failproofai jev setup --mode off # 保留配置,停止询问 Jev +``` + +同样的开关也在本地控制台中:**Settings → Jev** 有开/关切换和影子/强制选项。它只会重写模式,其他不变。钩子在每次工具调用时都会读取配置,因此更改会从下一次调用起生效,无需重启。 + +## 查看运行状态 + +```bash +failproofai jev status +failproofai jev test +``` + +`status` 会显示提供者为 **FailproofAI Cloud**、机器连接的 Cloud 主机、当前模式,以及密钥来源为 **FailproofAI Cloud connection**,不会显示密钥本身。当 FailproofAI Cloud 的 `jev.json` 已配置但 Jev 无法运行时,会说明原因: + +| `status` 显示 | `status --json` | 含义 | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | 机器已连接,但未为其存储 Jev 密钥:密钥缺少 `jev:evaluate` 权限,或连接时无法确认该权限。请使用相同密钥重新运行 `failproofai config --token `;如果密钥缺少该权限,请使用 **machine** 密钥。 | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | 此机器没有 FailproofAI Cloud 连接,Jev 密钥无处归属。 | + +执行 `failproofai config --disconnect` 后,FailproofAI Cloud 的 `jev.json` 将不复存在(除非已被切换为关闭状态,该状态会被保留),因此 `status` 将直接报告 Jev 为关闭。`status --json` 携带相同信息(`provider: "failproofai"`、`keySource: "cloud"`、`cloudConnected`、`keyCarriesJev`),即使配置缺失或被拒绝也一样。`permissions` 始终来自 `jev.json`;关于 `credentials.json` 的拒绝会额外添加 `credentialsPermissions`,以及 `fix`(当一条命令即可修复时)。`test` 发送一个实时请求,并报告其延迟和响应的 Jev 版本。当答案在钩子超时后才到达(钩子会记录 `timeout`)或对检查问题的回答有误时,命令会以退出码 1 结束,并在标题中说明原因。 + +控制台的 **Settings → Jev** 面板也会显示 **FailproofAI Cloud connection**:机器所属的组织以及其密钥是否携带 Jev 权限。这些信息从机器自身的文件读取,无需网络请求。 + +## 哪些内容会出现在策略页面 + +机器已将钩子活动发送到 FailproofAI Cloud(`events:add`)。开启 Jev 后,每个受管控调用的记录还会包含:运行的评估器、Jev 的判断、清除了哪些策略、回退原因(如有)、延迟以及响应的模型——均为决策、代码和名称,不含命令或提示词内容。在您组织的**策略**页面上: + +- 由 Jev 自身判断决定的调用(强制模式)会归因于 **Jev**,如果决定性检查来自某个策略包,记录还会注明该包的名称和版本; +- 在影子模式下,Jev 的拒绝或警告会以**假设情况**的形式显示,与您正在观察的推出情况并排展示; +- Jev 已清除或在影子模式下本会清除的策略,会按策略分别计数。 + +## Jev 无法响应时 + +以下所有情况都会回退到该调用的策略结果,并记录原因: + +| 原因 | 起因 | +| --- | --- | +| `out-of-credits` | 您的组织已用完套餐额度。 | +| `http-401`、`http-403` | 密钥已被撤销,或不携带 `jev:evaluate` 权限。请使用具有该权限的密钥重新连接。 | +| `http-429` | FailproofAI Cloud 正在对您的组织进行 Jev 限速。在其要求的等待时间(`Retry-After`,最长 60 秒)结束之前,机器不会发送任何请求,每次调用都会立即回退。以此方式被阻止的调用会被记录为 `http-429`,或在机器自身限速先触发时记录为 `rate-limited`。 | +| `http-429`(每日限额) | 您的组织已用完当日 Jev 调用次数:**每 UTC 日 10,000 次**,除非您的 FailproofAI Cloud 运营方设置了其他限额。每次调用都会回退,直到计数在 00:00 UTC 重置;机器最多每分钟询问一次,因此会在一分钟内感知到重置。`failproofai jev test` 会显示「Daily Jev limit for this org reached; resets at 00:00 UTC.」 | +| `http-422` | Jev 拒绝了此次调用请求,通常是因为工具调用包含的密集文本(base64、十六进制、压缩代码)超过了 Jev 的 token 预算。该调用每次都会回退;这不是服务中断。 | +| `http-502` | Jev 当前不可用。 | +| `http-503` | 此 Cloud 无法为您的组织提供 Jev 服务:没有模型网关、组织尚未配置,或网关已宕机。请联系管理员;钩子最多每分钟重试一次。 | +| `http-404` | 此 FailproofAI Cloud 尚不支持 Jev。 | +| `timeout` | 在 `timeoutMs`(默认 3000)内未收到响应。 | +| `model-mismatch` | 响应的 Jev 版本不是 1.13。 | + +## 密钥的存储位置及传输方式 + +- 密钥存储在 `~/.failproofai/credentials.json`(权限 `0600`,位于仅限所有者访问的目录中),与其他 FailproofAI Cloud 凭据并列存放。此路由的 `jev.json` 不存储密钥;如果在其中写入密钥,配置将失效。 +- 如果 `credentials.json` 对除您以外的任何人(组或其他用户,读或写)具有**任何**权限,或其所在目录可被除您以外的任何人**写入**,则该文件将被**拒绝**而非读取,Jev 将保持关闭,直到您修复:对文件执行 `chmod 600`,对目录执行 `chmod 700`(或重新连接,这会以 `0600` 权限重写文件并将目录设为仅限所有者访问)。其他用户只能读取目录是允许的;可以写入则意味着他们可以替换文件。 +- 密钥仅在其所附带的连接存在于机器上时才有效:即同一文件中存在同一 FailproofAI Cloud 的策略或报告凭据,且使用**相同密钥**。没有对应连接的 Jev 密钥会被忽略,Jev 保持关闭。当旧版 failproofai 的 `config --disconnect` 将 Jev 密钥保留在原处时(旧版不知道需要删除它),或旧版 failproofai 的 `config --token` 使用了另一个密钥连接(在 FailproofAI Cloud 上该密钥可能属于另一个组织)时,就会出现这种情况。要重新开启 Jev,请使用 **machine** 密钥重新连接。 +- 密钥仅发送至验证它的 Cloud 来源。指向其他位置的 `jev.json` 会被拒绝。 +- **机器上的 agent 可以读取该密钥。** `credentials.json` 仅限所有者访问,而 agent 以该所有者身份运行。出于设计目的,读取 failproofai 自身文件是被允许的(仅修改操作被 `block-failproofai-commands` 阻止),因此 agent 与该文件之间唯一的障碍是 `block-read-outside-cwd`——一个*可审查*的策略——而从您的主目录启动的会话中,没有任何障碍。携带 `jev:evaluate` 权限的密钥会消耗您组织的 Jev 额度(直至每日上限),无论从何处使用,因此请将机器密钥像其他消费凭据一样对待:如果 agent 可能已读取该密钥,请在 Keys 页面禁用它,并使用新密钥重新连接。 +- 仅您的全局文件决定此行为。仓库无法开启 Cloud Jev、将其指向其他位置或提供密钥,`FAILPROOFAI_JEV_API_KEY` 对此路由无效。 +- 对于 Jev 评估的每次调用,都会向 FailproofAI Cloud 发送一个请求,携带[自带密钥页面](/zh/policies/jev-byok#what-leaves-the-machine)所列的内容(密钥已脱敏)。FailproofAI Cloud 将其转发给 TypeSafe,不会记录或保留。 + +## 关闭 Jev + +| 命令 | 结果 | +| --- | --- | +| `failproofai jev setup --mode off` | 保留配置;不再询问 Jev。**这是持久有效的开关:** 再次连接永远不会覆盖已有的 `jev.json`,因此 Jev 保持关闭,直到您使用 `--mode shadow` 重新开启。 | +| `failproofai jev remove` | 删除 `~/.failproofai/jev.json`;Jev 关闭——直到下次使用携带 `jev:evaluate` 权限密钥执行 `failproofai config --token`,届时找不到 `jev.json` 会再次以影子模式开启 Jev(除非使用 `--no-transcripts` 运行)。要保持关闭状态,请使用 `--mode off`。 | +| `failproofai config --disconnect` | 断开机器连接:密钥被删除,当 `jev.json` 指向 FailproofAI Cloud 且未被切换为关闭时,`jev.json` 也会被删除。指向您自己端点的 `jev.json` 以及已切换为关闭的 `jev.json` 会被保留,因此再次连接时 Jev 仍保持关闭。 | + +从下一次工具调用起,钩子将完全按照以往方式执行正则策略。 \ No newline at end of file diff --git a/docs/zh/policies/jev.mdx b/docs/zh/policies/jev.mdx new file mode 100644 index 000000000..3dae28408 --- /dev/null +++ b/docs/zh/policies/jev.mdx @@ -0,0 +1,45 @@ +--- +title: "Jev policies" +description: "为受控工具调用添加 Jev 的实时审查,并在执行决策前进行检查。" +icon: "shield-check" +--- + +Jev 会根据用户向 Agent 下达的指令来审查工具调用。当字符串匹配策略阻止了合法操作,或遗漏了需要结合上下文判断的风险操作时,可使用 Jev。它在 `PreToolUse` 或 `PermissionRequest` 门控处与您的策略一同给出答复。如需在会话结束**后**获取评分,请使用 [Jev evaluations](/zh/evaluations/jev)。 + +## 以观察模式启动 + +安装 Failproof AI 并将 hooks 挂载到[支持的运行框架](/zh/reference/harnesses)。请使用 failproofai 1.0.8-beta.0 或更高版本。 + +Failproof AI 默认不包含任何 Jev 检查项。请以包的形式安装,否则 Jev 将无检查项可执行,也不会被调用: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +然后选择请求发送至 Jev 的方式: + +| 路由 | 第一步 | +| --- | --- | +| FailproofAI Cloud | 使用携带 `jev:evaluate` 权限的**机器**密钥进行连接。在未配置 Jev 的机器上,`failproofai config` 会以观察模式开启 Jev。 | +| 自定义提供商 | 在本地仪表盘中,打开 **Settings → Jev**,选择提供商,粘贴其令牌,并选择 **observe**。或运行 `failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key`。 | + +![本地仪表盘的 Jev 设置页面:提供商、端点、令牌以及开启 Jev 前的观察模式。](/images/dashboard/jev-settings.png) + +```bash +failproofai jev status +failproofai jev test +``` + +`test` 用于检查端点连通性。如需检查 hook 路径,可让已挂载 hook 的 Agent 使用其文件读取工具读取 `README.md`。确认该工具调用出现在会话中,然后在[本地仪表盘](/zh/reference/local-dashboard#review-policy-activity)中查看 **Policies → Activity**。`status` 中的 Jev 计数应有所增加。观察模式会记录 Jev 本应做出的决策,而实际生效的结果仍由您现有的策略决定。 + +## 决定何时执行 + +**硬性**策略始终拥有最终决定权。Jev 只能撤销明确标记为**可审查**的策略所产生的拒绝,且仅限于它检查过该策略所指定关注点的情况。在依赖 Jev 的放行结果之前,请参阅[策略权限](/zh/policies/authority)。Jev 也可以自主发出警告或拒绝操作。若 Jev 无法给出答复,则由策略结果决定该次调用。 + +一旦观察结果符合预期,可在 **Settings → Jev** 中切换至执行模式,或运行: + +```bash +failproofai jev setup --mode enforce +``` + +关于提供商 URL、Cloud 密钥、配置、回退机制以及每次请求所发送的数据,请参阅 [Jev 集成参考文档](/zh/reference/jev)。 \ No newline at end of file diff --git a/docs/zh/reference/custom-agents-typescript.mdx b/docs/zh/reference/custom-agents-typescript.mdx new file mode 100644 index 000000000..8cacadd91 --- /dev/null +++ b/docs/zh/reference/custom-agents-typescript.mdx @@ -0,0 +1,425 @@ +--- +title: "自定义 Agent(TypeScript)" +description: "适用于 @failproofai/sdk 的配置说明、事件目录、作用域及框架适配器。" +icon: "square-js" +--- + +本文介绍 TypeScript SDK 中每项配置、方法和字段的用途。如果您是首次接入,请先阅读指南——本页面供查阅参考。 + + + + 安装、接入方式、事件方法、完整示例及常见问题。 + + + 相同的事件、相同的线格式、相同的 spool——用 Python 实现。 + + + +需要 Node 20.9 或更高版本。支持 ESM 和 CommonJS,无运行时依赖。 + + + 本 SDK 与 Python SDK **写入相同的事件到相同的 spool**。由 Node agent 和 Python agent 组成的集群只会生成一组会话,而非两组,仪表板中也不会对它们加以区分。请按服务选择,而非按公司统一选择。 + + +## 安装 + +```bash +npm install @failproofai/sdk +``` + +```ts +import * as failproofai from "@failproofai/sdk"; + +await failproofai.agent("planner", { goal: question }, async () => { + const hits = await failproofai.toolCall("web_search", { input: { q } }, () => search(q)); +}); +``` + +框架适配器已内置于包中。这些框架是**可选的 peer 依赖**——声明它们是为了让支持的版本范围可见,不会自动为您安装,只有在调用 `instrument()` 时才会导入。 + +## 连接 Failproof 守护进程 + +与 Python SDK 相同:在 **Admin → Keys** 下创建 `events:add` 密钥,然后在 agent 机器上[连接守护进程](/zh/start/setup#connect-a-machine-to-cloud)。SDK 负责写入磁盘,守护进程负责传输。 + +## 配置 + +### OpenTelemetry spans(按需启用) + +通过 `npm install @opentelemetry/api @opentelemetry/sdk-trace-base` 单独安装 OpenTelemetry。 +然后将 FailproofAI 添加到您的 provider 处理器中: + +```ts +import * as failproofai from "@failproofai/sdk"; +import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"; +import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"; + +const spanProcessors: SpanProcessor[] = []; +await failproofai.instrument("otel", { spanProcessors }); +const provider = new BasicTracerProvider({ spanProcessors }); +const span = provider.getTracer("my-agent").startSpan("agent", { + attributes: { "gen_ai.operation.name": "invoke_agent" }, +}); +span.end(); +await provider.forceFlush(); +``` + +如果已有 provider,只需将其他处理器保留在同一列表中即可。暴露了 `addSpanProcessor` 方法的 provider 也可以通过 `{ provider }` 的形式传入。如果不传入任何选项,仅当尚未注册 provider 时才会注册新 provider。`OtelSpanExporter` 也可直接与您自己的处理器配合使用。 + +导出通过已连接的 FailproofAI 守护进程进行,SDK 不发起任何网络请求,也不需要密钥或本地监听器。请联系管理员启用 [OpenTelemetry 数据摄入](/zh/agenteye/opentelemetry)。不带参数的 `instrument()` 不会启用此导出器。`uninstrument("otel")` 仅禁用其自身的处理器。内容捕获由您的 span 属性控制;退出前请刷新您的 provider。OpenTelemetry 仍为可选的应用依赖,而非 SDK 的强依赖。 + +```ts +failproofai.configure({ + environment: "production", + flushInterval: 0.5, + baseDir: undefined, +}); +``` + +| 选项 | 说明 | +| --- | --- | +| `environment` | 每个事件上的标签——如 `production`、`staging`、`prod-eu`,默认为 `dev`。 | +| `flushInterval` | 定时器写入磁盘的间隔,单位为秒,默认为 `0.5`。 | +| `baseDir` | 写入位置,默认为守护进程的 spool 目录,通常无需修改。 | + +只有全部配置项通过验证时才会应用,因此一次失败的调用不会导致 SDK 处于新 `baseDir` 旧间隔的混合状态。 + +也可通过环境变量进行设置: + +| 变量 | 说明 | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | 无需修改代码即可设置 `environment`,`configure()` 中的选项优先级更高。 | +| `FAILPROOFAI_HOME` | 移动存放 spool 的 Failproof AI 根目录。 | +| `FAILPROOFAI_SDK_LOG_LEVEL` | `debug`、`info`、`warn`(默认)、`error`、`silent`。 | +| `FAILPROOFAI_SDK_STRICT` | 设为 `1` 时,接入错误将抛出异常而非仅记录日志。 | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | 设为 `1` 时,框架兼容性问题将抛出异常而非警告后继续运行。 | + + + **`environment` 中不能包含逗号。** 数据摄入会按逗号分割该字段以构建过滤器,标签中含逗号的事件将被静默丢弃——整个运行记录就此消失。请写 `prod-eu`,而非 `prod,eu`。 + + `configure({ environment: "prod,eu" })` 会立即抛出异常,让您及时发现问题。`AGENTEYE_ENVIRONMENT` 无法抛出异常——没有调用方可以接收——因此它会警告一次并回退到 `dev`。 + + +通过 `failproofai.setLogger({ debug, info, warn, error })` 可将 SDK 自身的日志输出路由到您的日志系统。 + +## 关闭 + +缓冲的事件会在 `process.on("exit")` 时刷新。 + +被信号终止的进程永远不会到达那里,而 Node 对 `SIGTERM` 的默认行为是不运行退出处理器直接终止——因此容器化的 agent 会丢失最后一个间隔尚未写入的数据。 + + + **本 SDK 不会为您安装信号处理器。** 注册信号处理器会改变进程的行为:监听器会抑制 Node 的默认终止行为,因此一个添加了信号处理器的库会悄无声息地让 Ctrl-C 失效。请自行添加: + + ```ts + for (const signal of ["SIGINT", "SIGTERM"] as const) { + process.once(signal, () => { + failproofai.flushSync(); + process.exit(0); + }); + } + ``` + + +短生命周期脚本或 serverless 处理器在返回前应执行 `await failproofai.flush()`——仅靠定时器无法保证数据一定送达。 + +## 身份标识 + +每个事件都属于某个会话和某个 agent。**作用域会自动填充两者**,因此您通常无需手动传入: + +```ts +await failproofai.session(async () => { + await failproofai.agent("planner", async () => { + failproofai.event.toolUse({ toolName: "search", toolCallId: "c1" }); + }); +}); +``` + +显式传入 `sessionId` 或 `agentId` 同样有效,且优先级更高。若两者均未绑定也未传入,调用将抛出异常,而不是发出一个 Cloud 会静默丢弃的事件。 + + + 身份标识基于 `AsyncLocalStorage` 传递,能跟随 `await`、`.then()`、定时器以及在作用域内创建的任何回调。**不能**跟随在一次运行中存储、在另一次运行中调用的回调,也无法跨越 `worker_threads` 边界——请在这些场景中使用 `failproofai.propagate()` 进行包装,否则相关事件将无法关联到正确的会话。 + + +### 作用域 + +| 作用域 | 发出事件 | 返回值 | +| --- | --- | --- | +| `session(body)` | 无——仅设置身份标识 | `body` 的返回值 | +| `agent(id, options?, body)` | `agent_start`,然后 `agent_end` | `body` 的返回值 | +| `toolCall(name, options?, body)` | `tool_use`,然后 `tool_result` | `body` 的返回值 | + +同步的 body 保持同步:`agent("x", () => 1)` 返回 `1`,而非 Promise。 + +`toolCall` 会将 body 的 resolved 值作为工具的 `output` 记录,除非您自行赋值给 `call.output`。 + + + +| 情况 | 事件 | `outcome` | +| --- | --- | --- | +| 代码块正常返回 | `agent_end` | `"success"` 或您指定的 `outcome` | +| 代码块抛出异常 | `error`,然后 `agent_end` | `"failed"` | +| `AbortError` | 仅 `agent_end` | `"cancelled"` | + +错误始终会重新抛出。 + +工具失败记录在叶节点上——`tool_result` 中包含 `error` 字符串——**不会**产生运行级别的 `error` 事件。被 agent 循环捕获的错误不属于运行失败;向上传播的错误由外层 `agent()` 恰好报告一次。 + + + + + +当工作不是单一函数时——例如在构造函数中打开作用域、在销毁函数中关闭,或跨越现有控制流: + +```ts +{ + using span = failproofai.agent.open("planner", { goal }); + using call = failproofai.toolCall.open("search", { input: { q } }); + call.call.output = await search(q); +} // tool_result, then agent_end +``` + +两种形式发出的事件字节完全相同。建议优先使用回调形式:它在 `AsyncLocalStorage.run()` 内部运行,无需手动展开,从根本上避免了"在此处打开、在彼处关闭"这类错误。 + +`using` 块如需报告自身的失败,应调用 `span.fail(error)`——disposer 本身没有异常传递通道。 + + + +## 事件目录 + +与 Python SDK 相同的十五个方法,采用驼峰命名。大多数方法**成对出现**——调用开启方法,再调用关闭方法,SDK 会计算两者之间的时间差。 + +| | 开启 | 关闭 | +| --- | --- | --- | +| **Agents** | `agentStart` | `agentEnd` | +| | `agentPause` | `agentResume` | +| **模型** | `modelRequest` | `modelResponse` | +| **工具** | `toolUse` | `toolResult` | +| **Hooks** | `hookTriggered` | `hookCompleted` | +| **人工** | `humanWait` | `humanInput` | + +三个独立方法:`error`、`humanPause`、`humanInterrupt`。 + + + +每个方法还接受 `sessionId` 和 `agentId`,作用域会自动填充这两个字段。省略的字段会被丢弃,而不是以 JSON `null` 的形式发送。 + +| 方法 | 必填 | 可选 | +| --- | --- | --- | +| `agentStart` | — | `goal`、`parentId` | +| `agentEnd` | — | `outcome`、`summary` | +| `agentPause` | `pauseId` | `reason`、`userId` | +| `agentResume` | `pauseId` | `reason`、`userId` | +| `modelRequest` | — | `model`、`messages`、`system`、`tools`、`requestId` | +| `modelResponse` | — | `model`、`stopReason`、`inputTokens`、`outputTokens`、`content`、`role`、`requestId` | +| `toolUse` | `toolName`、`toolCallId` | `input` | +| `toolResult` | `toolName`、`toolCallId` | `output`、`error` | +| `hookTriggered` | `hookName`、`hookId` | `triggerEvent`、`input` | +| `hookCompleted` | `hookName`、`hookId` | `outcome`、`output`、`error` | +| `error` | `errorType`、`message` | `traceback` | +| `humanWait` | `inputId` | `prompt`、`options`、`reason` | +| `humanInput` | `inputId` | `response` | +| `humanPause` | — | `reason`、`userId` | +| `humanInterrupt` | — | `reason`、`userId`、`atStep` | + +您添加的任何其他键都会成为自定义 payload 字段。框架特定的字段请以 `fw_*` 命名;与已声明字段冲突的名称会被拒绝,而不是静默覆盖已提升的列。 + + + + + **`duration_ms` 由系统计算,不接受外部传入。** 四个关闭方法会自动计算与开启方法之间的时间差,并拒绝调用者传入的 `duration_ms`——上报的时长必须是不可伪造的。 + + 配对匹配基于**会话**和 id,而非 agent。在 `planner` 下开启、在 `worker` 下关闭的工具调用仍能正确配对,这正是嵌套多 agent 运行的实际工作方式。 + + +## 框架适配器 + +```ts +await failproofai.instrument(); // 自动检测所有可用框架 +await failproofai.instrument("langchain"); // 仅指定一个 +failproofai.uninstrument(); // 恢复所有原始状态 +``` + +| 框架 | 支持版本 | 接入方式 | +| --- | --- | --- | +| **LangChain.js / LangGraph.js** | `@langchain/core` 0.3 – 1.x,LangGraph.js 0.4 – 1.x | `CallbackManager.configure`,因此每次 `invoke`/`stream`/`batch` 调用均自动覆盖,无需在任何地方传入 `callbacks:`——或自行传入 `langchainHandler()` 而不进行任何 patch。 | +| **Vercel AI SDK** | `ai` 4 – 7 | 在调用处使用 `telemetry()`,或对 `ai` 7 使用 `instrument("ai")` 覆盖整个进程(对 `ai` 4–6 此方式为按需启用——见下文)。 | +| **Mastra** | `@mastra/core` 0.20 – 1.x | `Agent.generate`/`.stream`、agent 的模型和工具解析,以及工作流运行/步骤引擎。 | +| **LlamaIndex.TS** | `llamaindex` 0.11.4 – 0.x | `Settings.callbackManager`(已订阅)加上 `AgentWorkflow.runStream`,覆盖工作流运行及其步骤。 | + +每个版本范围均针对真实框架发布版进行测试,涵盖两端版本、ES 模块和 CommonJS,在每次 CI 运行时执行。 + +映射关系与 Python SDK 一致,因此同一程序在两种语言中绘制出相同的调用树。只有拥有 LLM 决策循环的构造才是 **agent**——包括图或链的运行、AI SDK 的 `generateText`/`streamText` 调用、Mastra agent、LlamaIndex agent 运行。LangGraph 节点或工作流步骤是 **hook**(`hook_triggered`/`hook_completed`),而非嵌套 agent。模型调用以 `model_request`/`model_response` 配对形式记录,包含 token 数量;工具调用携带模型自身的工具调用 id。失败只记录一次,记录在发生失败的事件上。 + +适配器安装失败时会记录日志并跳过;其他适配器仍会继续安装——一个损坏的 LlamaIndex 不应影响 LangGraph 的正常使用。 + + + 不带参数的 `instrument()` 通过**能否解析**来检测框架,而非检查其是否已被导入——Node 对 ES 模块没有类似 Python `sys.modules` 的等价机制。已安装但未使用的框架将被导入并 patch。如果这一点对您有影响,请明确指定所需框架。 + + + + 这些框架大多同时提供 ES 模块构建和 CommonJS 构建,Node 会将它们作为两个独立副本加载。适配器会 patch 您应用加载的那个副本(如果已有代码 `require` 过,也会 patch CommonJS 副本),因此两种模块系统均可正常工作。如果框架已被 esbuild 或 webpack **打包进您的输出**,则无法通过 patch 覆盖——请在此场景下使用调用处的辅助方法:`langchainHandler()`、`telemetry()`、`wrapTool()`。 + + +### 不 patch 的 LangChain 使用方式 + +```ts +import { langchainHandler } from "@failproofai/sdk/langchain"; +await graph.invoke(input, { callbacks: [langchainHandler()] }); +``` + +该处理器无论是否调用 `instrument()` 均可工作,且不会重复记录。`instrument("langchain")` 接受 `sessionId`、`captureContent`、`includeChains`、`graphCallbacks` 和 `captureLimit` 参数,与 Python 适配器一致;在调用时传入 `metadata: { failproofai_sdk_session_id }` 可为该次调用指定会话。 + +### Vercel AI SDK + +AI SDK 从 ES 模块中导出纯函数,ES 模块命名空间按规范是不可变的——没有地方可以 patch。SDK 使用其自身文档化的扩展点: + +```ts +import { telemetry } from "@failproofai/sdk/ai"; + +const { text } = await generateText({ + model, + prompt, + experimental_telemetry: telemetry({ functionId: "answer-question" }), + // 对于 ai 7,使用 `telemetry: telemetry({ … })` ——同一对象,新的属性名 +}); +``` + +这就是完整的集成:一个 agent span、每步一对包含 token 数量的模型请求/响应,以及所有工具调用。同一个调用处代码兼容所有主要版本——`ai` 4–6 读取其携带的 tracer,`ai` 7 读取 telemetry 集成。 + +**对于 `ai` 7**,`instrument("ai")` 会通过 AI SDK 的全局 telemetry 集成列表实现相同的进程级覆盖,该列表是累加式的,不会影响其他人的配置。 + +**对于 `ai` 4–6,`instrument("ai")` 本身不记录任何内容,并会输出一条相关警告。** 这些主要版本唯一的进程级钩子是全局 OpenTelemetry tracer provider——这是一个单一插槽,一旦被占用 OpenTelemetry 就会拒绝再次注册。注册我们的 provider 会静默拒绝您后续在启动流程中调用的 `NodeSDK.start()`,并将您的 http/数据库 span 发送到一个不导出任何内容的 tracer。请在调用处使用 `telemetry()` 或 `wrapModel`。如果该进程自身没有运行任何 OpenTelemetry,可以通过 `instrument("ai", { registerGlobalTracer: true })` 按需启用:这样它会记录所有传入 `experimental_telemetry: { isEnabled: true }` 的调用,且只在插槽仍为空时才会占用它。`registerGlobalTracer: false` 保持默认行为并静默该警告。 + +如果您更倾向于只包装一次模型,`wrapModel` 只能看到模型调用,因为工具调用发生在模型层之上。一个被包装的模型在没有外部包装的情况下调用,会作为独立运行记录。流式调用在流结束时关闭——消费者取消时 `stop_reason` 为 `"cancelled"`,中途失败时为 `"error"` 并附带错误信息: + +```ts +import { wrapModel } from "@failproofai/sdk/ai"; +const model = await wrapModel(openai("gpt-4o")); +``` + +同时使用两者没有问题:中间件会检测到该调用已被记录并自动延让,确保每次调用只被记录一次。 + +`functionId` 是 agent span 的名称,请保持低基数——它对应到 `agent_id`,即仪表板中的主要分面维度。 + +### Next.js + +`next build` 默认会打包服务端依赖,被打包进构建的框架是 `instrument()` 无法覆盖的副本。请一次性包装配置,并从 Next 的启动钩子调用 `instrument()`: + +```ts +// next.config.ts +import { withFailproofai } from "@failproofai/sdk/next"; +export default withFailproofai({ /* your config */ }); +``` + +```ts +// instrumentation.ts +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") return; + const failproofai = await import("@failproofai/sdk"); + await failproofai.instrument(); +} +``` + +`withFailproofai` 会将 LangChain、Mastra、LlamaIndex 和 SDK 本身添加到 `serverExternalPackages`,同时保留您现有的列表。如果不使用它,`instrument()` 对每个无法覆盖的框架会警告一次而非静默失败;如果您已自行列出这些包,请设置 `FAILPROOFAI_NEXT_EXTERNALS=1`。Vercel AI SDK 和调用处辅助方法在两种情况下均可正常工作。Edge 路由会获得一个无操作的构建:导入 SDK 是安全的,不会记录任何内容。 + +### 流式调用的 token 计数 + +兼容 OpenAI 的 API 只有在客户端明确请求时才会在流中报告用量。LangChain 和 Vercel AI SDK 会自动请求;对于 LlamaIndex,请向其 `OpenAI` LLM 传入 `additionalChatOptions: { stream_options: { include_usage: true } }`;对于 Mastra,请在构建模型时启用用量报告(例如 `createOpenAICompatible({ includeUsage: true })`)。否则流式模型调用将不包含 token 计数。 + +### 运行时 + +Node ≥ 20.9、Bun 和 Deno——每个框架,以 ES 模块和 CommonJS 两种形式,均在各运行时上针对 Node 的 trace 进行测试。SDK 与 `failproofaid` 守护进程协同运行,由守护进程负责传输写入的数据。 + +## 自建 agent——不使用框架 + +适用于您自己编写的 agent 循环,或没有适配器的框架。您使用与适配器底层相同的 API 发出事件,因此 trace 具有相同的结构和质量。 + +您无需了解 agent 的内部组织方式。无论函数名称是什么,每个手工构建的 agent 都有三个关键位置,这三个位置就是完整的接入点: + +| 位置 | 需要添加的内容 | 发出事件 | +| --- | --- | --- | +| **一次运行**的开始和结束处 | `failproofai.agent("name", { goal }, async () => …)` | `agent_start` / `agent_end` | +| **调用模型的函数** | 调用前 `event.modelRequest`,调用后 `event.modelResponse`——包括失败情况的两端 | 每次模型调用一对 | +| **执行工具的函数** | `failproofai.toolCall(name, { toolCallId, input }, () => run())` | `tool_use` / `tool_result` | + +```ts +async function callModel(messages) { + const requestId = randomUUID(); + const started = Date.now(); + failproofai.event.modelRequest({ model: MODEL, requestId, messages }); + try { + const reply = await client.chat.completions.create({ model: MODEL, messages, tools }); + failproofai.event.modelResponse({ + model: reply.model, requestId, stopReason: reply.choices[0].finish_reason, + inputTokens: reply.usage?.prompt_tokens, outputTokens: reply.usage?.completion_tokens, + duration_ms: Date.now() - started, + }); + return reply.choices[0].message; + } catch (error) { + failproofai.event.modelResponse({ model: MODEL, requestId, stopReason: "error", + error: String(error), duration_ms: Date.now() - started }); + throw error; + } +} + +async function dispatch(call) { + const input = JSON.parse(call.function.arguments); + return failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, + () => runTool(call.function.name, input)); +} + +await failproofai.agent("inventory", { goal: question }, async () => { + for (;;) { + const message = await callModel(messages); + if (!message.tool_calls?.length) return message.content; + for (const call of message.tool_calls) await dispatch(call); + } +}); +``` + +身份标识是环境感知的:`agent()` 内部的所有内容都会关联到该运行的会话,无需传入 id,程序中的其他部分也不会受到影响——包括 agent 已写入其自身数据库的任何内容。 + +- **服务或 worker:** 将您自己的请求或任务 id 作为 `sessionId` 传入,这样仪表板上的会话与您自己日志或数据库中的记录使用相同的字符串标识。 +- **子 agent:** 嵌套调用 `agent()`,内层 agent 会以外层 agent 的 `parent_id` 加入同一会话。 +- **成对发送事件。** 没有对应 `modelResponse` 的 `modelRequest` 会在仪表板中显示为永久运行中的 span——这就是为什么需要 `catch`。 + +仓库中的 [`sdk/typescript/examples/research-agent.ts`](https://github.com/FailproofAI/failproofai/blob/main/sdk/typescript/examples/research-agent.ts) 是完整可运行的版本:一个真实的 OpenAI 工具循环,按照完全相同的方式接入,在每次变更时以 ES 模块和 CommonJS 两种形式在 CI 中运行。 + +## 评估 + +```ts +import { Evaluator, EvalResult, Score } from "@failproofai/sdk/evaluator"; + +export const app = new Evaluator({ name: "my-evals", version: "1" }); + +app.eval("tool_success_rate", { version: "1" }, (session) => { + const results = session.eventsOfType("tool_result"); + const failures = results.filter((event) => event.payload.error != null).length; + return new EvalResult({ + score: new Score(results.length === 0 ? 1 : 1 - failures / results.length), + reasoning: `${failures} of ${results.length} tool calls failed`, + }); +}); +``` + +```bash +FAILPROOFAI_EVALUATOR_URL=… FAILPROOFAI_EVALUATOR_TOKEN=… \ + npx failproofai-evaluator ./my-evals.js +``` + +有关协议、worker 配置和结果类型,请参阅 [Evaluator SDK 参考文档](/zh/reference/evaluator-sdk)。 + + + **评估函数必须让出控制权。** 永不返回的同步函数会阻塞 Node 唯一的线程,任何超时都无法在此期间触发。请编写 `async` 评估函数。 + + +## 对您的进程无副作用的保证 + +| | | +| --- | --- | +| **不阻塞 agent 循环** | 事件进入内存队列,由定时器写入磁盘。定时器已 `unref`,因此导入本包不会阻止脚本退出。 | +| **不无限增长** | 队列同时受计数和字节数限制。超出任一限制后,最旧的事件会被丢弃并输出警告——遥测服务中断不能演变成 OOM 崩溃。 | +| **不导致进程崩溃** | 一个无法编码的事件会被单独丢弃,不影响周围的批次。抛出异常的 getter、循环引用、`BigInt`、孤立的代理对:每种情况都会被妥善处理而非向上传播。 | +| **不留下写了一半的批次** | 内容在原子重命名前执行 `fsync`,目录在重命名后执行 `fsync`,失败的写入会清理其临时文件。 | +| **不让转录内容可被读取** | 批次文件权限为 `0600`,存储在 `0700` 目录中。它们包含目标、提示、工具参数和工具输出。 | +| **不泄露凭证** | API 密钥、token、JWT、Bearer 请求头及形如密钥的赋值语句在写入磁盘前会被脱敏处理。守护进程在上传前会再次脱敏。 | \ No newline at end of file diff --git a/docs/zh/reference/custom-agents.mdx b/docs/zh/reference/custom-agents.mdx index dfbf38c1f..5d73526fc 100644 --- a/docs/zh/reference/custom-agents.mdx +++ b/docs/zh/reference/custom-agents.mdx @@ -15,7 +15,7 @@ icon: "python" -需要 Python 3.10 或更高版本,无运行时依赖。 +需要 Python 3.11 或更高版本,无运行时依赖。 ## 安装 diff --git a/docs/zh/reference/jev-cloud.mdx b/docs/zh/reference/jev-cloud.mdx new file mode 100644 index 000000000..032c06e84 --- /dev/null +++ b/docs/zh/reference/jev-cloud.mdx @@ -0,0 +1,146 @@ +--- +title: "通过 FailproofAI Cloud 使用 Jev" +description: "Cloud 机器密钥、连接状态、限制以及实时 Jev 策略审查的故障行为。" +icon: "cloud" +--- + +本文是 [Jev 策略](/zh/policies/jev) 的 Cloud 路由参考。Jev 是 TypeSafe 的分类器,它根据你实际的请求内容审查每次工具调用,与你的策略并行工作,而不是取代策略。通过 **FailproofAI Cloud**,已连接的机器使用与连接时相同的密钥即可使用 Jev:无需 TypeSafe 账户、无需第二个密钥、无需配置端点。每次调用均从组织现有的套餐配额中扣除。 + +Jev 的所有行为与[自带密钥方式](/zh/reference/jev-providers)完全相同:硬策略始终具有最终效力,可审查策略的拒绝仅在 Jev 被明确针对该问题进行询问时才会被清除,任何失败都会回退到该次调用的正则表达式结果。 + + +需要 **failproofai 1.0.8-beta.0** 或更高版本。1.0.7 不含 Jev,尽管它在版本排序上高于 1.0.7 的各 beta 版本。若未配置 Jev,行为不会有任何变化:hooks 将完全按照既往方式运行正则表达式策略。 + + +## 开始之前 + +在运行 Agent 的机器上安装 Failproof AI,并将其 hooks 附加到[受支持的运行环境](/zh/reference/harnesses)。如果从零开始,请按照[快速入门](/zh/start/quickstart)完成 hook 安装。使用 `failproofai --version` 检查已安装的 CLI;若版本早于 Jev,请升级。你还需要访问组织的 **Administration → Keys** 页面以创建机器密钥。 + +Jev 在 `PreToolUse` 或 `PermissionRequest` 检查点审查具名工具调用,不会审查会话中的每个事件。要使 Jev 清除策略拒绝,你需要安装一个标记为[可审查](/zh/policies/authority)的策略;所有其他策略拒绝仍具有最终效力。 + +## 开启方式 + +1. **创建带有 Jev 权限的密钥。** 在 FailproofAI Cloud 控制台中,打开 **Administration → Keys → Create key**,选择 **machine** 预设。该预设授予机器所需的三项权限:`events:add`(发送活动)、`policies:pull`(接收策略)和 `jev:evaluate`(Jev,从组织套餐中扣费)。密钥若不携带另外两项权限,则无法携带 `jev:evaluate`。 +2. **使用该密钥连接机器。** 在提示时读取其一次性密钥,然后运行完整的设置命令: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + failproofai config + ``` + + `failproofai config` 会安装守护进程、为其找到的 Agent CLI 附加 hooks,并连接机器。使用环境变量可防止密钥出现在命令参数和 shell 历史记录中。如果运行环境是后来安装的,请[显式附加它](/zh/start/quickstart)。 + + 如果你的组织使用自部署的 FailproofAI Cloud 而非托管版,请添加其地址:`--url https://`(或导出 `FAILPROOFAI_CLOUD_URL`)。若未添加,密钥将与托管服务进行验证,连接会失败。如果该主机的证书来自私有 CA,请将 CA 安装到机器的系统信任存储区(例如使用 `update-ca-certificates`),而不仅仅是 `NODE_EXTRA_CA_CERTS`:发送事件和拉取策略的守护进程读取的是系统存储区。详见[故障排查](/zh/reference/troubleshooting)。 + +就这些。连接操作会存储密钥,当机器**尚未**有 Jev 配置时,会为 FailproofAI Cloud 写入一个配置。从机器首次部署起(约 30 秒内),FailproofAI Cloud 将设置模式:当 Jev 策略部署到该机器时为 `enforce`,没有策略时为 `off`(参见[谁设置模式](#who-sets-the-mode))。输出会显示相关信息: + +```text + Jev configured through FailproofAI Cloud; waiting for FailproofAI Cloud's Jev mode, which arrives with this machine's first deployment (within ~30 s) and decides. +``` + +FailproofAI Cloud 部署的检查在 Cloud 上运行。如需在机器上添加自定义检查,请安装策略包: + +```bash +failproofai policies add FailproofAI/jev-policies +``` + +**使用 `--no-transcripts` 连接时,不会开启 Jev。** Jev 会将每次被检查的工具调用及最近的提示词发送到 FailproofAI Cloud,这比仅发送决策的连接发送的内容更多。密钥仍会被存储,输出会说明 Jev 已可用以及如何开启: + +```bash +failproofai jev setup --provider failproofai +``` + +此命令同样会**关闭**通过 FailproofAI Cloud 使用的 Jev。按照 `config --disconnect` 相同的规则,通过 FailproofAI Cloud 运行 Jev 的 `jev.json`(由之前启用了转录的连接留下)将被删除,输出会说明该机器上的 FailproofAI Cloud Jev 保持关闭。若存在指向你自己 Jev 端点的 `jev.json`,则保持不变;已手动关闭的 FailproofAI Cloud 配置(使用 `--mode off`)同样保持不变。 + + +连接操作**绝不会覆盖**已存在的 `~/.failproofai/jev.json`。如果你已在使用自己的 Jev 端点,它将继续被使用,输出会说明该文件保持原有配置不变——如果该文件使 Jev 处于关闭状态(被拒绝或已手动关闭),也会说明原因及修复方法。如需将该机器切换到 FailproofAI Cloud,请运行 `failproofai jev setup --provider failproofai`。 + + +## 谁设置模式 + +在已连接 FailproofAI Cloud 的机器上,**Jev 模式由 FailproofAI Cloud 设置**,机器本身不参与设置: + +- `enforce`:当任何 Jev(或正则表达式 + Jev)策略部署到该机器时生效。来自该策略目标 Agent 的每次被检查工具调用都会发送到 FailproofAI Cloud,后者会与该处安装的策略包的检查一并进行询问。来自没有 Cloud Jev 策略针对的 Agent、且自身也没有策略包检查的调用,则完全不会被发送。在 `enforce` 模式下,Jev 自身的拒绝检查既可以拦截调用,也可以清除正则表达式的裁定。 +- `off`:当没有任何 Jev 策略部署时生效:完全不使用 Jev,无论 `jev.json` 如何配置。 + +如需在策略生效前进行试用,可将其以 **observe** 效果部署:检查仍会被执行,其结果会作为**假设操作**记录在策略页面上,但不会拦截或清除任何调用。`failproofai jev setup --mode` 和控制台的 **Settings → Jev** 开关会显示模式由 FailproofAI Cloud 管理,不会做任何更改。`jev.json` 不用于 Cloud 的检查,即使其中指定了其他提供商。`failproofai config --disconnect` 会将 Jev 控制权交还给机器自身的 `jev.json`。 + +`failproofai jev status` 随后会显示 `Jev checks run on FailproofAI Cloud (mode: enforce)`,同时列出审查每个 `both` 策略的检查项。Fleet 页面会显示某台机器无法发起询问的原因: + +- `transcripts_disabled`:该机器以 `--no-transcripts` 方式连接,永远不会开启 Jev。 +- `jev_unconfigured`:该机器的密钥不携带 `jev:evaluate`。 +- `jev_rate_limited`:FailproofAI Cloud 因组织的 Jev 速率限制而拒绝了该机器的部分调用,这些调用仅由正则表达式策略决定。 +- `jev_unavailable`:连续多次调用失败,机器将每次跳过 FailproofAI Cloud 的 Jev 一分钟,之后会自动重试。 + +如果 FailproofAI Cloud 在 5 秒内未响应,正则表达式策略将独立做出决定,与任何 Jev 中断情况相同。连续 3 次失败后,机器每次停止询问一分钟,以防 Cloud 中断拖慢每次工具调用。 + +会话暂停(`failproofai config --pause`)不会停止 FailproofAI Cloud 的 Jev 检查,就像它不会停止 Cloud 管理的策略一样。但它会暂停机器上已安装策略包的 Jev 检查。 + +## 检查运行状态 + +```bash +failproofai jev status +failproofai jev test +``` + +`status` 显示提供商为 **FailproofAI Cloud**、机器连接的 Cloud 主机、当前模式,以及密钥来源为 **FailproofAI Cloud connection**,不显示密钥本身。当 FailproofAI Cloud 的 `jev.json` 已存在但 Jev 无法运行时,会说明原因: + +| `status` 显示 | `status --json` | 含义 | +| --- | --- | --- | +| **off — no Jev key is stored for this machine's FailproofAI Cloud connection** | `key-lacks-jev` | 机器已连接,但未为其存储 Jev 密钥:密钥缺少 `jev:evaluate` 权限,或连接时无法确认。请在 `FAILPROOFAI_CLOUD_TOKEN` 中填入密钥后重新运行 `failproofai config`;如果密钥缺少该权限,请使用 **machine** 密钥。 | +| **off — this machine is not connected to FailproofAI Cloud** | `not-connected` | 该机器上没有 FailproofAI Cloud 连接,Jev 密钥无所归属。 | + +`failproofai config --disconnect` 之后,FailproofAI Cloud 的 `jev.json` 将不再存在(除非已手动关闭,该状态会被保留),因此 `status` 仅报告 Jev 为关闭。`status --json` 包含相同的信息(`provider: "failproofai"`、`keySource: "cloud"`、`cloudConnected`、`keyCarriesJev`),即使配置不存在或被拒绝时也是如此。`permissions` 始终对应 `jev.json` 的权限;关于 `credentials.json` 的拒绝会额外显示 `credentialsPermissions`,以及当单个命令可修复时的 `fix` 提示。`test` 发送一次真实请求,并报告其延迟和响应的 Jev 版本。当响应在 hook 超时后才到达(hooks 会记录 `timeout`)或检查问题的答案有误时,命令以退出码 1 结束,并在标题中注明。 + +控制台的 **Settings → Jev** 面板也会显示 **FailproofAI Cloud connection**:机器所属的组织以及其密钥是否携带 Jev 权限。这些信息直接从机器本地文件读取,无需网络调用。 + +## 验证真实调用 + +在已附加 hook 的 Agent 中启动新会话。请求它使用文件读取工具读取 `README.md` 并报告标题。确认会话包含该工具调用,然后再次运行 `failproofai jev status`:其最近的已评估调用计数应该增加。在[本地控制台](/zh/reference/local-dashboard#review-policy-activity)中打开 **Policies → Activity**,查看该调用的 Jev 裁定和模式。在 Cloud 中,组织的 **Policies** 页面会显示已送达活动的 Jev 结果。在 observe 模式下,裁定会被记录为**假设操作**,策略结果仍决定该调用的处理方式。只有当可审查策略匹配且 Jev 清除了其具名检查时,才会出现清除记录。 + +## 策略页面上显示的内容 + +机器已将其 hook 活动发送到 FailproofAI Cloud(`events:add`)。开启 Jev 后,每次被检查调用的记录还会包含:运行的评估器、Jev 的决定、它清除的策略、回退时的原因、延迟以及响应的模型——仅包含决策、代码和名称,不包含命令内容或提示词。在组织的 **Policies** 页面上: + +- 由 Jev 自身裁定的调用(enforce 模式)会归因于 **Jev**,若决定性检查来自某个策略包,记录中也会注明该包及其版本; +- 在 observe 模式下,Jev 的拒绝或警告会显示为**假设操作**,与正在观察的部署一同展示; +- Jev 已清除或在 observe 模式下本会清除的策略,会按策略进行计数统计。 +- Jev 参与的决定(拦截、警告、清除,或 observe 模式下的假设操作)会列出其询问的每项检查及其结论:裁定、原因(`not-detected`、`exempt`、`fired`、`op-requested` 等)、证据值 `p`、`exempt` 答案以及每次探测的答案。针对 observe 部署策略的检查也会被列出,并标记为已观察;它永远不会拦截调用。Jev 以概率而非文字形式作答,因此没有自由文本说明。纯允许操作汇总为计数,不携带此列表。 + +## Jev 无法响应时的处理 + +以下每种情况均会回退到该调用的策略结果,并记录其原因: + +| 原因 | 起因 | +| --- | --- | +| `out-of-credits` | 组织已用完套餐配额。 | +| `http-401`、`http-403` | 密钥已被吊销,或不携带 `jev:evaluate` 权限。请使用携带该权限的密钥重新连接。 | +| `http-429` | FailproofAI Cloud 因组织的 Jev 速率限制对请求进行了限速。在其要求的等待时间(`Retry-After`,最多 60 秒)结束前,机器不会发送任何请求,每次调用直接回退。以此方式被阻止的调用记录为 `http-429`,若机器自身的速率限制先触发,则记录为 `rate-limited`。 | +| `http-429`(每日限制) | 组织已用完每日 Jev 调用配额:**每 UTC 日 10,000 次**,除非 FailproofAI Cloud 的运营方设置了其他限制。每次调用都会回退,直到计数在 00:00 UTC 重置;机器每分钟最多重试一次,因此会在一分钟内感知到重置。`failproofai jev test` 会显示"Daily Jev limit for this org reached; resets at 00:00 UTC." | +| `http-422` | Jev 拒绝了该调用的请求,通常是因为工具调用包含超出 Jev token 预算的密集文本(base64、十六进制、压缩代码等)。该调用每次都会回退,这不是中断故障。 | +| `http-502` | Jev 当前不可用。 | +| `http-503` | 该 Cloud 无法为组织提供 Jev 服务:没有模型网关、组织尚未配置,或网关已停止运行。请联系管理员;hooks 每分钟最多重试一次。 | +| `http-404` | 该 FailproofAI Cloud 尚不提供 Jev 服务。 | +| `timeout` | 在 `timeoutMs`(默认 3000)毫秒内无响应。当 FailproofAI Cloud 设置机器的 Jev 模式时,等待时间为 5000 毫秒,`jev.json` 中的 `timeoutMs` 不生效。 | +| `model-mismatch` | 响应的 Jev 版本不是 1.13。 | + +## 密钥的存储位置及传输范围 + +- 密钥仅存储一次,位于 `~/.failproofai/credentials.json`(权限 `0600`,在仅限所有者访问的目录中),与其他 FailproofAI Cloud 凭证并列存放。此路由的 `jev.json` 中不存储密钥;若在其中写入密钥会导致配置无效。 +- 如果 `credentials.json` 对所有者之外的任何人(组或其他用户)具有**任何**权限(读或写),或其所在目录可被所有者之外的人**写入**,则该文件将被**拒绝**读取,Jev 将保持关闭,直到修复:对文件执行 `chmod 600`,对目录执行 `chmod 700`(或重新连接,连接操作会以 `0600` 权限重写文件并将目录设为仅限所有者访问)。目录对他人仅有读取权限是允许的;可写入则意味着他人可以替换文件。 +- 密钥仅在其所属连接存在于机器上时有效:即同一个 FailproofAI Cloud 存在**相同密钥**的策略或报告凭证,且位于同一文件中。没有对应连接的遗留 Jev 密钥将被忽略,Jev 保持关闭。这种情况发生在旧版 failproofai 的 `config --disconnect` 未删除 Jev 密钥时(旧版本不了解需要删除它),或旧版 failproofai 的 `config --token` 使用另一个密钥连接时(在 FailproofAI Cloud 上该密钥可能属于另一个组织)。如需重新开启 Jev,请使用 **machine** 密钥重新连接。 +- 密钥只会发送到其经过验证的 Cloud 源地址。指向其他地址的 `jev.json` 将被拒绝。 +- **机器上的 Agent 可以读取它。** `credentials.json` 是仅限所有者访问的,而 Agent 以该所有者身份运行。读取 failproofai 自身的文件是被允许的(只有修改操作被 `block-failproofai-commands` 拦截),因此 Agent 与该文件之间的唯一屏障是 `block-read-outside-cwd`——一个*可审查*策略——而从你的 home 目录启动的会话则没有任何屏障。携带 `jev:evaluate` 权限的密钥会从使用它的任何地方消耗组织的 Jev 配额(直至每日上限),因此请像对待任何其他支出凭证一样对待机器密钥:如果 Agent 可能已读取了它,请在 Keys 页面禁用该密钥,并使用新密钥重新连接。 +- 只有你的全局文件才能决定此事。仓库无法开启 Cloud Jev、将其指向其他地址或提供密钥,`FAILPROOFAI_JEV_API_KEY` 在此路由中被忽略。 +- 对于 Jev 评估的每次调用,会向 FailproofAI Cloud 发送一次请求,携带[自带密钥页面](/zh/reference/jev-providers#what-leaves-the-machine)所列的内容(密钥已脱敏)。FailproofAI Cloud 将其转发给 TypeSafe,不进行日志记录或留存。 + +## 关闭方式 + +在已连接的机器上,当 FailproofAI Cloud 未向其部署任何 Jev 策略时,Jev 处于关闭状态:在 Cloud 中移除或归档 Jev 策略即可。 + +| 命令 | 结果 | +| --- | --- | +| 在 FailproofAI Cloud 中移除该机器的 Jev 策略 | Cloud 的模式在下次轮询时(约 30 秒)变为 `off`:完全不使用 Jev,无论 `jev.json` 如何配置。 | +| `failproofai config --disconnect` | 断开机器连接:密钥被删除,若 `jev.json` 指向 FailproofAI Cloud 且未处于手动关闭状态,也会被删除。指向你自己端点的 `jev.json` 保持不变。 | + +从下一次工具调用起,hooks 将完全按照既往方式运行正则表达式策略。 \ No newline at end of file diff --git a/docs/zh/reference/jev-evaluations.mdx b/docs/zh/reference/jev-evaluations.mdx new file mode 100644 index 000000000..483ffe577 --- /dev/null +++ b/docs/zh/reference/jev-evaluations.mdx @@ -0,0 +1,88 @@ +--- +title: "Jev 评估参考" +description: "Jev 会话评估的问题类型、校准分数、限制与回填说明。" +icon: "list-checks" +--- + +本页介绍 [Jev 评估](/zh/evaluations/jev) 背后的问题形式与评分规则。有些问题需要模型*读取*对话,但不需要*撰写*相关内容。"客户是否表达了紧迫感?"只有两种答案。"他们有多沮丧?"有几个有序的答案。在提问之前,你就已知晓所有答案。 + +**分类器评估**正是为此而设。你编写问题及其可能的答案,一个专为分类构建的小型模型返回一个校准数值——永远不会是自由文本。 + + +与裁判评估一样,分类器评估每个会话都需要消耗一次模型调用。与裁判不同的是,它是一个小型的单一用途模型,而非通用模型,因此速度更快、成本更低——但它永远不会解释自身的判断。如果你需要推理过程,请使用[裁判评估](/zh/evaluations/judge)。 + + +## 我该用哪一种? + +| 问题 | 使用方式 | +| --- | --- | +| 总共发生了多少次工具调用? | 代码 | +| 会话时长是否不足 30 秒? | 代码 | +| 客户是否表达了紧迫感? | **分类器** | +| 应由哪个团队处理:账单、技术还是销售? | **分类器** | +| 客户有多沮丧? | **分类器** | +| 回答是否真正正确? | **裁判** | +| 是否遵循了我们的升级策略,你为何这么认为? | **裁判** | + +经验法则:**可计数 → 代码,可列举的答案 → 分类器,需要解释 → 裁判。** + +你不必提前做决定。描述你想衡量的内容,助手会自动选择,告诉你它的选择及原因,你随时可以切换。 + +## 两种问题类型 + +### `noul` — 这是否成立? + +两个答案,你对两者都加以描述。结果是"成立"描述符合的概率: + +```json +{ + "instructions": "助手是否在未核查退款政策的情况下承诺退款?", + "criteria": { + "true": "在未事先核查或审批政策的情况下承诺或执行了退款", + "false": "未承诺退款,或每次退款都经过了政策核查" + } +} +``` + +两侧都要描述。"未表达紧迫感"是一个真实的答案,明确说明它会让另一侧的描述更加清晰。 + +### `score` — 程度有多深? + +一个有序的评分标准,**从最差开始排列**。结果是会话在其中所处的位置,重新缩放至 0–1: + +```json +{ + "instructions": "客户有多沮丧?", + "criteria": ["平静", "沮丧", "非常愤怒"] +} +``` + +**评分标准需要三到五个等级,且所有等级必须各不相同。** 两个限制都是有实际依据的,并非风格上的考量: + +- **两个等级**会退化为 `noul` 已经能更好处理的情况;**超过五个等级**会让模型趋向中间值而非明确表态。同一个问题对同一会话评分,两个等级得到 0.00,三个等级得到 0.01,十个等级得到 0.55。 +- **重复等级**会在它们之间任意分配答案。一个明显愤怒的会话,对 `["平静", "沮丧", "非常愤怒"]` 评分为 1.00,而对 `["愤怒", "愤怒", "愤怒"]` 评分为 0.66——形式上合法,但毫无意义。 + +没有顺序的类别——如"账单、技术或销售"——不是评分标准。可以对每个类别分别提一个 `noul` 问题,或使用裁判评估。 + +## 解读结果 + +分类器生成一个 0 到 1 的**分数**,与裁判评估完全相同,因此它可以以同样的方式生成图表、应用过滤器并触发告警。有两点值得注意: + +- **没有推理过程。** 该字段有意留空。这个模型不会解释自身判断,而捏造一个解释只是伪造,而非功能。 +- **不确定性有标注。** `score` 问题会报告自身的置信度,模型不确定的结果会被标记为 `low_confidence`——因此"哪些结果需要人工审查"是一个过滤条件,而非猜测。`noul` 问题不报告置信度,因此永远不会被标记。 + +过长的会话会按摘录方式读取并合并。当会话过长无法完整读取时,结果会说明跳过了多少轮对话——你永远不会看到基于部分会话的判断被当作基于完整会话呈现出来。 + +## 限制 + +- **评分标准为三到五个等级,且各不相同。** 见上文;两个边界在创作时都会强制执行。 +- **每个评估只有一个问题。** 如果要问两件事,就创建两个评估,这也是你在图表上真正需要的。 +- **编辑问题会发布新版本。** 新旧分数不具可比性,因此它们会被分开存储,而非混入同一条趋势线。 +- **分类器始终生成分数**,不会生成指标或断言。 +- **没有推理过程**,如上所述。如果一个数字会让人追问"为什么?",请改用裁判评估。 + +## 测试与回填 + +与裁判评估不同,分类器评估**可以**在部署前进行测试——用与代码评估相同的方式,针对真实会话进行[测试](/zh/evaluations/test),在正式上线前查看分数。 + +它也可以对已有会话进行[回填](/zh/evaluations/deploy#score-sessions-you-already-have)。由于每个会话都需要消耗一次模型调用,请有意识地限定时间窗口,而不是重新处理所有历史数据。 \ No newline at end of file diff --git a/docs/zh/reference/jev-intent.mdx b/docs/zh/reference/jev-intent.mdx new file mode 100644 index 000000000..2ee44ea4e --- /dev/null +++ b/docs/zh/reference/jev-intent.mdx @@ -0,0 +1,114 @@ +--- +title: "Jev 意图捕获" +description: "哪些 harness 事件告知 Jev 评估器人类的请求内容、哪个字段承载文本、哪些内容永远不会被计入,以及信任 harness 传递的提示词所带来的风险。" +icon: "message-square-quote" +--- + +当你配置 [Jev 策略审查](/zh/policies/jev) 时,评估器会根据**人类实际请求的内容**来判断每次受门控的工具调用,而非 harness 呈现给 agent 的任何文本。像"是的,强制推送吧"这样的回复可以通过 **reviewable** 策略——这正是评估器的意义所在,因为无法读取请求的正则表达式会阻断三分之一的真实工作。 + +这段文本来自同一个地方:**harness 在 prompt-submit 事件时递交给 hook 的提示词本身**。Failproof AI 将其中由人类输入的部分——剥离 harness 包装、脱敏机密信息、截断至上限——记录到其自身状态目录下的 `0600` 文件中。系统不会读取磁盘上的任何内容:会话记录是一个 agent 可以用一条命令改写的文件,因此系统从不追问某条提示词是谁写的。 + +## 这一设计所接受的风险,直白地说 + +一个已经能运行命令的 agent,可以让 harness 提交一条提示词。`claude -p "…"`、`codex exec`、`copilot -p`、`cursor-agent -p`、`devin -p`、`droid -p`、`goose run -t` 和 `pi -p` 都会触发相同的 prompt-submit 事件,携带相同的 payload,就像在该 agent 控制的子会话中由人类输入一样。它还可以直接运行 Failproof AI 的 hook 二进制文件,并传入它自己构造的 payload。Failproof AI 内部无法区分两者——两者都是同一个程序从同一个 stdin 读取数据。 + +**因此,拥有 shell 的 agent 可以伪造自己的同意。** 这是一个经过深思熟虑的权衡,于 2026-09-23 确定,以下是权衡的两面: + +- **它换来了什么。** 我们构建并测量过另一种方案:要求 harness 在某个字段中声明一个人类为提示词作者,否则什么都不记录。但没有任何量产 harness 会发送这样的字段,因此那个版本在**所有 harness 上都什么也记不到**——Jev 对每次调用都没有已声明的意图,永远无法通过任何一条策略。一个永远不触发的捕获机制不是更安全的产品,而是根本不是产品。 +- **它做不到什么。** 被记录的提示词只能通过标记为 **reviewable** 的策略。**hard** 策略永远不会被 Jev 的任何判断清除,因此伪造的提示词永远无法将 hard deny 变为 allow——跳过 hook 对 agent 也没有任何好处:harness 会独立地为工具调用触发 Failproof AI。 +- **它在极端情况下能做到什么。** 最坏的情况是通过十五条 reviewable 内置策略中的某一条——而**其中十二条是阻断型策略**。`protect-env-vars`、`block-env-files`、`block-read-outside-cwd`、`block-rm-rf`、`block-force-push`、`block-secrets-write` 以及六条基础设施 CLI 阻断策略(`block-kubectl`、`block-terraform`、`block-aws-cli`、`block-gcloud`、`block-az-cli`、`block-helm`)均为 deny,因此伪造的同意可以将真实的 deny 变为 allow,涵盖打印环境变量机密、读取 `.env` 文件、读取项目外路径、`rm -rf`、强制推送、写入机密文件或修改线上基础设施。只有 `warn-git-amend`、`warn-destructive-sql` 和 `warn-global-package-install` 是提示型策略。默认安装会启用十二条中的两条:`protect-env-vars` 和 `block-env-files`;其余十条只有在某台机器上被人为启用后才会生效。任何提示词都触及不到的是所有 hard 策略——`block-sudo`、`block-curl-pipe-sh`、`block-push-master`、`block-work-on-main`、阻止 agent 禁用 Failproof AI 的防护,以及所有其他未标记为 reviewable 的内置策略。[策略权限](/zh/policies/authority) 列出了全部十五条策略及各自的审查方式。 + +以下情况仍会被拒绝——这些都是易于检查、且 agent 无法仅通过请求获得的内容:harness 自身 payload 标记为机器提交的轮次、payload 中命名了子 agent、会话 ID 不是普通名称、事件不是 prompt-submit 事件,以及文本内容仅为 harness 包装——包括 Failproof AI 自身的停止关键词,多个 harness 会将其作为下一个用户轮次回传。 + +## 各 harness 对照表 + +"文本字段"是 Failproof AI 对各 harness 进行归一化处理后的 stdin payload 字段。"已记录"表示该提示词是否被保存为人类请求。 + +| Harness | `--cli` | 提示词事件 → 规范化 | 文本字段 | 已记录 | Agent 最后一条消息来源 | +| --- | --- | --- | --- | --- | --- | +| Claude Code | `claude` | `UserPromptSubmit` | `prompt` | 是,除非 payload 的 `source` 标记了一个无人提交的轮次(`loop_wakeup`、`schedule_wakeup`、`poll_event`、`system`)。`user`、`sdk`、未知值以及未发送任何 `source` 的构建版本均会被记录 | 会话记录(`transcript_path`) | +| Codex | `codex` | `user_prompt_submit` → `UserPromptSubmit` | `prompt` | 是 | rollout JSONL(`agent_message`、`AgentMessage`) | +| GitHub Copilot CLI | `copilot` | `UserPromptSubmit` | `prompt` | 是 | `events.jsonl`(`assistant.message`) | +| Cursor | `cursor` | `beforeSubmitPrompt` → `UserPromptSubmit` | `prompt` | 是,当整个提示词就是 `` 包装时会剥除该包装 | agent 记录 JSONL | +| OpenCode | `opencode` | `message.updated`(user 角色)→ `UserPromptSubmit` | `prompt` | 是——但当前 OpenCode 在该事件中不携带文本,因此实际上什么也不会被记录;相同消息的重复提交只记录一次 | 无(会话存储于 SQLite) | +| Pi | `pi` | `input` → `UserPromptSubmit` | `prompt` | 是,除非 `input_source` 为 `extension`——即另一个扩展的 `sendUserMessage()`,其文本可能由模型生成或来源于代码仓库 | Pi 会话 JSONL | +| Hermes | `hermes` | 无 | — | 否——Hermes 完全没有 prompt-submit 事件 | — | +| OpenClaw | `openclaw` | `before_agent_run` → `UserPromptSubmit` | `prompt` | 是,除非运行元数据将该运行标记为机器发起:`trigger` 不是 `user`、`inputProvenance.kind` 不是 `external_user`,或 `senderIsOwner: false` | 无(`before_agent_run` 不携带记录路径) | +| Factory Droid | `factory` | `UserPromptSubmit` | `prompt` | 是 | droid 会话 JSONL | +| Devin CLI | `devin` | `UserPromptSubmit` | `prompt` | 是 | 无(会话存储于 SQLite) | +| Antigravity CLI | `antigravity` | `PreInvocation` → `UserPromptSubmit` | 无 | 否——`PreInvocation` 在一个轮次中*每次*模型调用前都会触发,且不携带任何提示词文本 | — | +| Goose | `goose` | `UserPromptSubmit` | `message` | 是 | 无(会话存储于 SQLite) | + +有两个 harness 什么都不记录,原因相同:它们的事件不携带任何人类文本。Hermes 没有 prompt-submit 事件——其原生插件自行处理 `pre_llm_call`,只转发工具、会话和子 agent 事件。Antigravity 的 `PreInvocation` 在每次模型调用前都会触发,无论是人类轮次还是随后的五次调用,且不携带任何提示词字段;hook 还可以向同一对话中注入 `userMessage` 步骤。两个事件中都没有任何可供记录的内容。 + +## 什么使提示词属于人类 + +1. **事件。** Failproof AI 因 harness 的 prompt-submit 事件被调用,处理程序将其规范化为 `UserPromptSubmit`。 +2. **Payload。** harness 通过 hook 的 stdin 写入,并在上述字段中携带文本。到达 Failproof AI 时不携带 payload 的调用不会记录任何内容。 +3. **Payload 中没有任何内容将该轮次排除在外。** 携带子 agent 标识(`agent_id`)的 payload 是 agent 在自我提示。将某个轮次标记为机器提交的 `source`、`input_source` 或 OpenClaw 运行标记会被拒绝。**缺少**标记不会排除任何内容——这正是与那个什么都不记录的版本的区别,因为这里的每个标记在所有量产构建版本中都是缺失的。 +4. **剥除包装后仍有内容**(见下文)。 + +**会话记录不是判断提示词作者的证据。** 本页面的早期版本描述了一种记录交叉校验机制:如果记录显示是模型安排了该提示词,则该提示词会被拒绝,且记录必须延续上一条提示词所见的那份记录。该检查已被移除。记录是一个 agent 已经能通过 shell 访问的文件——它可以被截断、替换、填充超过读取预算、在轮次开始时拍快照并在结束时恢复,或用 agent 自己写的条目重新伪造成合理的样子。每一轮加固之后都会出现同一种伪造的另一种写法,因此整个机制被彻底移除,而非修补。 + +记录仍会被读取,用于一件事:**agent 最后一条可见消息**。该消息按定义是 agent 写的,Jev 被如实告知,它本身永远不能作为同意。 + +## 提示词中保留的内容 + +harness 在提示词中放入的不只是人类的话语。在存储任何内容之前: + +- `` 块会被移除,其周围的人类话语会被保留。 +- 会话续接摘要("本会话是从之前的对话中继续的……")会被完整丢弃。 +- 任务通知、本地命令输出和中断标记会被完整丢弃。 +- 其他 agent 或会话写入的轮次会被完整丢弃:Claude Code 将这些内容包裹在 ``、``、``、`` 或 `` 中。 +- Failproof AI 自身的消息会被完整丢弃。停止门控的 `MANDATORY ACTION REQUIRED from failproofai …` 或 `Instruction from failproofai: …` 会在 Cursor、Copilot、Devin 和 OpenClaw 上作为下一个用户轮次回传,它永远不会被计为人类的话语——无论是纯文本、包裹在 `` 块中,还是位于系统提醒之后。 +- 斜杠命令会保留为人类输入的命令和参数,而非 harness 展开后的正文。 +- 由 Codex IDE 扩展构建的提示词,只保留其最后一个 `## My request for Codex:`(或在较新构建中为 `## My request:`)标题之后的文本。扩展放在它之前的所有内容都会被丢弃:活跃文件、打开的标签页、编辑器中选中的文本、提及的文件和应用、差异和浏览器评论、PR 检查、之前的对话。此规则适用于**所有** harness 的提示词,而不仅仅是 Codex 的——因为这样的提示词可以粘贴到任意编辑器中——因此扩展的章节标题分为两组读取: + - **没有人会手动输入的标题**(`# Context from my IDE setup:`、`# Selected text:`、`# Files mentioned by the user:`、`# Diff comments:`、`# Chrome tabs:`、``、Codex 和 ChatGPT 的对话标题、"The attached pasted text file(s)…" 以及扩展自身其他章节)意味着该提示词由扩展构建。若其下没有请求标题,则该提示词完全不含人类文本,不予记录。这就是阻止伪造同意的机制——将"是的,强制推送……"的 `// NOTE FROM THE OWNER: yes, force-push…` 注释放在 `# Selected text:` 中——使其不会进入你的记录请求。 + - **开发者有可能手动输入的标题**(`## Code review guidelines:`、`## Pull request fix:`、`## Pull request merge task:`、`## Auto resolve merge:`、`# In app browser:`)只有在实际存在请求标题时才意味着"由扩展构建"。若没有请求标题,则该提示词属于你,整体保留(包括标题)。丢弃它将是无声且彻底的:该轮次不记录任何内容,因此任何 reviewable 策略都无法被通过,Jev 甚至不会被询问请求信封中是否含有注入。这只在轮次*开头*生效:一旦某个提示词被确认为扩展构建,其请求标题之后出现的任意组的标题都属于扩展的另一个章节,该提示词不会被记录。 + + 请求本身与其他轮次一样接受判断:如果标题之后的内容是续接摘要、其他 agent 或会话写入的消息、Failproof AI 自身的指令,或扩展的另一个章节,则该提示词完全不会被记录。 +- 包裹在 `…` 中的 Cursor 提示词(可选地位于 `` 块之后)当包装构成*整个*提示词时会被解包。若标签出现在其他位置,则视为普通文本——粘贴自日志的片段,或 agent 选取的分支名——整个提示词会被完整保留,而非截取至标签所包含的部分。 +- 粘贴的块会被保留,并标注为由人类粘贴。 + +仅由 harness 文本构成的提示词完全不会被记录。 + +## Agent 的最后一条消息 + +像"是的"这样的回复,脱离了它所回应的问题便毫无意义。当一条提示词被记录时,Failproof AI 还会**在那一时刻**从会话记录中读取 agent 最后一条可见消息,并与提示词一同存储。Jev 在单独的字段中接收它,标注为 agent 所写:它可以解释简短的回复,但本身永远不能作为人类的请求。这是读取记录的唯一目的,而被改写的记录所能造成的最坏后果,不过是在一个预期为 agent 所写的位置放入一条 agent 写的消息。 + +它从记录末尾读取,最多读取最后 4 MB。支持的记录格式包括:Claude Code、Codex rollout(旧版 `agent_message` 事件和新版 `AgentMessage` 条目)、Cursor、Copilot `events.jsonl`,以及 Pi、Factory 和 OpenClaw 的会话 JSONL。Claude Code 自身的合成消息、API 错误消息和子 agent(sidechain)消息会被跳过。对于将会话存储在 SQLite 中的 Goose 和 OpenCode、记录为单个 JSON 文档的 Devin,以及 `before_agent_run` 事件不携带记录路径的 OpenClaw,均没有快照。 + +## 存储 + +| 属性 | 值 | +| --- | --- | +| 位置 | `~/.failproofai/state/semantic/sessions//.json`,其中 `` 是输入提示词的 agent 配置文件:FailproofAI 已知 agent 的 `.`(Cloud 策略所针对的身份),否则仅为 `` | +| 权限 | 文件 `0600`,目录 `0700`。其上方每一级目录(直至 `~/.failproofai`)均遵循与 `jev.json` 目录相同的规则:任何其他人可**写入**的目录都可以被重命名并替换,因此读取路径会尽量移除这些写入位,并在无法移除时**什么都不读取**。这样,被记录的提示词会缺失,而非被伪造,也不会有任何内容被通过 | +| 每个会话保留数量 | 最后 5 条提示词;与前一条完全相同的提示词会替换它,而不会占用新的槽位 | +| 时间窗口 | 超过 6 小时的提示词会被忽略 | +| 大小 | 每条提示词和 agent 消息上限为 6,000 个字符,保留开头和结尾 | +| 机密信息 | 在写入前使用与 `sanitize-*` 策略相同的模式进行脱敏。超过 48,000 个字符的文本会被截取为前 28,800 个字符和后 19,200 个字符进行脱敏,且截断处附近的文本(机密信息可能在此被分割)永远不会被存储 | + +包含字母、数字、`.`、`_` 和 `-` 以外字符的会话 ID,或长度超过 128 个字符的会话 ID,永远不会被用作文件名,因此不会为其记录任何内容。 + +会话文件只在首次记录提示词后才会创建。它只存储提示词,不含其他内容——没有来源状态,没有记录标记——一旦其沉默时间超过六小时窗口,就会在下一个新会话写入其第一条提示词时被删除。 + +提示词只会在与记录时相同的 agent 配置文件和会话 ID 下被读取。会话 ID 来自 agent,因此两个配置文件可以使用相同的 ID;按配置文件区分键值,确保一个配置文件的话语永远不会被计为另一个配置文件的请求。早于此布局的文件(`sessions/.json`)无法说明是哪个配置文件写入的,因此永远不会被读取,并会随六小时窗口过期。 + +除非配置了 Jev 端点,否则不会记录任何内容。在 FailproofAI Cloud Jev 模式下,对于没有分配 Cloud Jev 检查且没有已安装包的检查审查的 agent 配置文件,不会记录任何内容。 + +### 项目根目录 + +"项目内部"——`read-outside-workspace` 和其他路径检查的判断依据——指的是会话在**第一次受审查调用**时所在的项目内部。根目录在那时固定,之后的 `cd` 不会移动它;`cd` 仍然会改变相对路径的解析方式。如果允许根目录随 `cd` 移动,则在一次调用中执行 `cd ~/.ssh` 就会让 `~/.ssh` 成为下一次调用的项目根目录。 + +固定值存储在 `~/.failproofai/state/semantic/roots/.json`,内容为 `{root, at}`:文件 `0600`,目录 `0700`,会话 ID 规则与上述相同。超过 7 天的文件会在新会话固定其根目录时被删除。若 `roots` 目录可被其他用户写入,则会被忽略,转而使用活跃目录的根目录。如需重新固定某个会话,请删除其文件。 + +## 已知限制 + +- **提示词的可信度仅与 hook 调用本身一样高。** 此处的所有内容都读取 harness 写入 hook stdin 的 payload。能够运行命令的 agent 可以无头运行 harness(`claude -p` 以及上文列出的其他七个命令),或直接运行 Failproof AI 的 hook 二进制文件并传入自己构造的 payload,从而记录一条从未有人输入的提示词。这是本页开头所描述的已接受权衡:它只能通过 reviewable 策略,永远无法通过 hard 策略——但十五条 reviewable 内置策略中有十二条是 deny,因此伪造的提示词可以将那十二条策略上的真实阻断变为允许。 +- **子 agent 检测是针对 Claude 形状设计的。** 携带 `agent_id` 的 payload 在任何 harness 上都不会被记录。这是 Claude Code、Factory Droid 和 Devin 会使用的字段。Codex 在子 agent 线程内触发其提示词事件,Copilot 运行进程内附属程序,Goose 有 `delegate` 工具,OpenClaw 运行角色扮演——这些都不会以本系统能识别的方式标记 payload,因此这些 harness 上的子 agent 提示词会被记录为该会话自身的提示词。OpenClaw 的 `openclaw.agentId` **不是**该标记:量产插件在每次运行时都会设置它,包括所有者的运行。 +- **不携带任何标记的调度器。** Claude Code 的 `schedule_wakeup` 和 `loop_wakeup`,以及 OpenClaw 的 `cron` 和 `heartbeat` 触发器,会被拒绝,因为这些 harness 在 payload 中有所说明。Goose 自身的调度器(`goose schedule add`)和 Codex 的 `codex exec` 什么都不说,因此它们启动的运行会像其他运行一样被记录。 +- **Agent 的最后一条消息可以是 agent 自己选择的消息。** 记录未经过身份验证,因此能够写入自己记录的 agent 可以决定其"最后一条消息"的内容。它被标注为 agent 所写,本身不会通过任何策略——但需要注意,`decide.ts` 的 v1 路径允许它满足确定性的"用户是否命名了此目标"检查,因此控制自身记录的 agent 可以提供覆盖所需的目标名称。 +- **以扩展机器标题开头的提示词会被整体丢弃。** 以 `# Selected text:`、`# Diff comments:`、`# Chrome tabs:` 或上述第一组中的其他章节标题开头,且没有 `## My request:` 标题的提示词,该轮次不会被记录——因此也不会通过任何策略。这是故意为之:这些章节携带的是他人控制的文本(你选中的代码、审查者的差异评论、页面标题),将其记录为你的话语才是更严重的失误。开发者有可能手动输入的标题属于第二组,单独出现时永远不会丢弃提示词。 +- **OpenCode 在实际使用中什么都不记录。** 其 `message.updated` 事件在当前 OpenCode 版本中不携带文本,且它也会为其任务工具创建的子会话触发,而这些子会话的"用户"消息是由父 agent 写入的。 +- **`CODEX_HOME` 在 `lib/codex-sessions.ts` 的 rollout 发现中不受支持。** 这只影响 agent 消息快照的查找位置,从不影响提示词是否被记录。 \ No newline at end of file diff --git a/docs/zh/reference/jev-providers.mdx b/docs/zh/reference/jev-providers.mdx new file mode 100644 index 000000000..aed2abe22 --- /dev/null +++ b/docs/zh/reference/jev-providers.mdx @@ -0,0 +1,275 @@ +--- +title: "Jev providers 和自带密钥配置" +description: "使用自有密钥进行实时 Jev 策略审查的 provider 端点、模型 ID、配置方式及故障行为说明。" +icon: "key-round" +--- + +这是使用自有密钥配置 [Jev 策略](/zh/policies/jev) 的 provider 参考文档。正则策略匹配的是字符串——它无法区分你主动要求的 `rm -rf build/` 和偷偷混入计划里的 `rm -rf ~`,所以在某些地方拦得太多,在另一些地方又拦得太少。**Jev** 是 TypeSafe 的分类器,它会根据你实际的请求内容分析工具调用,并在一次快速请求中回答一系列是/否问题。 + +配置好自有 Jev 端点和密钥后,Failproof AI 会在每次工具调用时**同时**向 Jev 和正则策略进行咨询,而非以 Jev 取代正则策略: + +- **硬性**策略的拒绝是最终决定,Jev 无法撤销。除非策略显式标记为可审查并指定了覆盖该策略的 Jev 检查项,否则所有策略默认为硬性策略——因此,未做任何声明的自定义策略、扩展包策略或 Cloud 策略均为硬性策略,始终启用的自保护守卫也始终是硬性策略。 +- **可审查**策略的拒绝可以被撤销,但前提是:Jev 被专门询问了该策略所关注的确切问题,且回答为"此处无问题"或"用户主动请求了此操作"。若某项检查确认了问题属实,且用户并未主动要求该调用,则拒绝依然有效——即便该检查本身的结论仅为警告,因为在工具调用发出前,警告并不会阻止 agent。而当该检查属于可发出拒绝的类型(如密钥泄露、凭证外泄、破坏性删除等),该调用上的任何拒绝都不会被撤销。 +- 若某次拦截对应的是你交代的任务步骤且影响范围不超出该步骤,它仍可能降级为**警告**:Jev 会将自身的拒绝软化为警告,该警告——具体说明调用的实际问题——将取代策略的拦截。 +- Jev 也可以自主发出警告或拒绝,用于处理正则表达式无法描述的危险操作。 +- 若 Jev 无法给出答案(超时、速率限制、服务器错误、积分耗尽、模型版本异常),该调用将沿用正则策略结果,与未配置 Jev 时完全一致。 +- 除非 Jev 读取了完整的调用内容并被询问了确切的关注点,否则 Jev 绝不会让调用获得比单独使用策略更宽松的许可。若条件不满足——调用内容过大无法完整发送,或疑似注入攻击——所有清除授权将被撤回,每项拒绝均保持有效。 + + +未配置 Jev 时,一切不变:hooks 将完全按既有方式执行正则策略。配置文件本身就是唯一的启用开关。 + + + +使用 FailproofAI Cloud?你无需自备密钥:持有 `jev:evaluate` 权限密钥的已连接机器可以在你组织的套餐下使用 Jev。详见 [通过 FailproofAI Cloud 使用 Jev](/zh/reference/jev-cloud)。 + + +## 开始之前 + +在你的 agent 运行的机器上安装 **failproofai 1.0.8-beta.0 或更高版本**,并将其 hooks 附加到[受支持的 harness](/zh/reference/harnesses)。如果是新机器,请参考[快速开始](/zh/start/quickstart);如果不使用 Cloud,请参考[配置本地执行](/zh/start/setup#enforce-locally)。使用 `failproofai --version` 检查已安装的 CLI 版本。 + +从下方的 provider 获取 API 密钥,或准备好兼容端点及其密钥。Jev 在 `PreToolUse` 或 `PermissionRequest` 门控处审查具名工具调用,可以发出自己的裁决,但撤销现有策略拒绝还需要安装一条标记为[可审查](/zh/policies/authority)的策略。硬性策略拒绝始终为最终决定。 + +## 选择 provider + +Jev 可通过五条路由访问,选择其中任意一个并准备对应密钥即可。 + +| Provider | `--provider` | 端点 | 默认模型 | 备注 | +| --- | --- | --- | --- | --- | +| TypeSafe | `typesafe` | `api.typesafe.ai/v1/systemone` | `jev-1.13.0` | 精确版本锁定。 | +| OpenRouter | `openrouter` | `openrouter.ai/api/v1/systemone` | `typesafe/jev-1.13` | 请求仅路由到零数据保留端点,不会回退到其他 provider。返回类似 `typesafe/jev-1.13-20260917` 的日期版本号。 | +| Vercel AI Gateway | `vercel` | `ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | Jev 仅以别名标识,因此响应版本记录为未验证。 | +| Cloudflare Workers AI | `cloudflare` | `api.cloudflare.com/client/v4/accounts//ai/run` | `typesafe/jev` | 需要 `--account-id`。实测每个密钥约每秒六次调用后触发 HTTP 429。 | +| 自定义端点 | `custom` | `/systemone` | `jev-1.13.0` | 任何接受 TypeSafe 请求体并报告响应模型的端点。仅支持 `https`;本地测试时允许使用明文 `http` 连接回环地址(`localhost`、`127.0.0.1`、`::1`)。 | + + +使用 Vercel 自带密钥功能时,失败的请求会静默地使用 Vercel 的凭证重试。如果你需要所有调用均计费至且仅对你自己的 TypeSafe 账户可见,请直接使用 TypeSafe。 + + +## 配置方法 + +一条命令,指定端点和密钥。先以 `observe` 模式启动,以便在现有策略继续决定调用的同时查看 Jev 的裁决: + +```bash +failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key +``` + +### URL 决定 provider + +你无需手动指定 provider:URL 的**主机名**即可确定使用哪个 provider。 + +| URL 主机 | Provider | 额外参数 | +| --- | --- | --- | +| `api.typesafe.ai` | `typesafe` | — | +| `openrouter.ai` | `openrouter` | — | +| `ai-gateway.vercel.sh` | `vercel` | — | +| `api.cloudflare.com` | `cloudflare` | `--account-id <32-hex-account-id>` | +| 其他主机 | `custom` | — 你提供的 URL 即为 base URL | + +由此产生三条规则: + +- **若 URL 是该 provider 的官方 API,则不写入任何覆盖配置。** `--url https://api.typesafe.ai/v1` 与 `--provider typesafe` 产生完全相同的配置。若在已知 provider 下使用不同的路径或主机,则会作为 base URL 存储,效果等同于 `--base-url`。 +- **`--provider` 仍可覆盖自动推断**,这正是通过自有主机代理某个 provider API 的方式:`--url https://jev-proxy.internal/v1 --provider typesafe`。 +- **`--provider` 与主机矛盾时会被拒绝**,而非猜测处理。`--provider openrouter --url https://api.typesafe.ai/v1` 不会写入任何配置,并会说明原因:两种写法对密钥发送目标存在分歧。同样的组合在 `jev setup --base-url` 和控制台的 Jev 设置中也会被拒绝。(`--provider custom` 不构成矛盾——它的含义是"将此 URL 视为其本身"——但在 Cloudflare 主机上除外,其按账户区分的端点无法通过自定义路由访问。) + +`--url` 的验证规则与配置文件中 `baseUrl` 的验证规则完全一致,拒绝时使用相同的提示:在任何模式下均需使用 `https`,仅在本地测试时允许对回环地址(`localhost`、`127.0.0.1`、`::1`)使用明文 `http`。风险提示:回环服务器无任何身份验证,在其停机期间,其他本地进程可能占用其端口并响应请求;请在本地测试之外使用 `https`。 + +### 密钥 + +通过 `--key-stdin` 管道传入,或在终端中不带该参数运行命令并在遮蔽提示符处粘贴密钥。两种方式都会将密钥直接写入配置文件,不会以任何形式回显。 + + + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + ``` + + + ```bash + failproofai jev --url https://openrouter.ai/api/v1 --mode observe --key-stdin < ~/openrouter.key + ``` + + + ```bash + failproofai jev --url https://ai-gateway.vercel.sh/typesafe/v1 --mode observe \ + --key-stdin < ~/vercel-gateway.key + ``` + + + ```bash + failproofai jev --url https://api.cloudflare.com/client/v4 \ + --account-id <32-hex-account-id> --mode observe --key-stdin < ~/cloudflare.token + ``` + + + ```bash + failproofai jev --url https://jev.internal.example.com/v1 --mode observe --key-stdin < ~/jev.key + ``` + + + +`failproofai jev setup` 接受相同的参数,是完整写法:使用 `setup --provider ` 可以直接指定 provider 名称而非 URL。 + +### `--token` 及其代价 + +`--token ` 将密钥放在命令行参数中,这是配置机器最快的方式,也是唯一会将密钥留在配置文件之外的写法: + +```bash +failproofai jev --url https://openrouter.ai/api/v1 --token +``` + + +命令行参数执行后会留在你的 shell 历史文件中,且在命令运行期间会出现在进程列表里——任何以你的身份运行的进程均可从 `/proc` 读取到。每次使用 `--token` 时,`setup` 都会给出提示。在共享机器上、在有录制的会话中,或在历史文件会同步的环境下,建议优先使用 `--key-stdin`;如果以这种方式传递过密钥,请及时轮换。 + + +`--token`、`--key-stdin` 和 `--key-from-env` 三者互斥,只能选其一。 + +配置完成后,发送一次小型实时请求以验证密钥、端点和响应的 Jev 版本: + +```bash +failproofai jev test +``` + +```text + failproofai jev test ok · 523 ms + + provider cloudflare + model asked typesafe/jev + answered by jev-1.13.0 (Jev 1.13 family — verified) + latency 523 ms — within the 3000 ms timeout +``` + +当答复在超时后才到达(此时每个 hook 都会回退到 `timeout` 下的正则策略),或检查问题回答有误时,`jev test` 退出码为 1,并在标题中注明。 + +Hooks 在每次工具调用时读取配置,因此配置从下一次调用起立即生效,无需重启任何服务,无论是否使用守护进程。 + +## 查看运行状态 + +```bash +failproofai jev status +failproofai jev status --json +``` + +`status` 显示 provider、端点、模型、模式、配置文件及其权限,但永远不显示密钥。下方还会汇总近期活动:Jev 评估了多少次调用、因何原因回退到正则策略及回退次数、延迟情况,以及清除了哪些可审查策略。 + +## 验证实际调用 + +在已挂钩的 agent 中开启新会话,要求其使用文件读取工具读取 `README.md` 并报告标题。确认会话中包含该工具调用后,再次运行 `failproofai jev status`:近期已评估调用次数应有所增加。在[本地控制台](/zh/reference/local-dashboard#review-policy-activity)中打开 **Policies → Activity**,查看该调用的 Jev 裁决和模式。在 observe 模式下,策略结果仍然决定调用结果。只有当可审查策略匹配且 Jev 清除了所有指定检查项时,才会出现清除记录;普通读取操作可能没有需要清除的策略。 + +## Observe 模式 + +默认模式为 `enforce`。如需观察 Jev 而不让其影响任何决定,切换到 `observe` 模式:Jev 仍会被调用且其裁决会被记录,但实际执行的是正则策略结果。 + +```bash +failproofai jev setup --mode observe +failproofai jev setup --mode enforce +failproofai jev setup --mode off +``` + +`off` 保留配置(端点和密钥)并停止调用 Jev:hooks 将完全按没有配置时的方式执行正则策略,`failproofai jev status` 显示"off (switched off)"。使用 `--mode observe` 或 `--mode enforce` 可重新启用。 + +对同一 provider 重新运行 `setup` 会保留已存储的密钥,因此切换模式只需一个参数。切换 provider 则需从头配置并提供新 provider 的密钥。将请求迁移到不同主机的 `--base-url` 也同样如此:已存储的密钥仅发送到其最初配置时对应的主机或该 provider 的官方 API。 + +## 配置文件 + +所有配置集中存储在一个文件中:由 `setup` 写入的 `~/.failproofai/jev.json`: + +```json +{ + "provider": "cloudflare", + "apiKey": "", + "accountId": "<32-hex-account-id>", + "mode": "enforce", + "timeoutMs": 3000 +} +``` + +| 字段 | 含义 | +| --- | --- | +| `provider` | `typesafe`、`openrouter`、`vercel`、`cloudflare` 或 `custom`——也可以是 `failproofai`,其密钥来自 FailproofAI Cloud 连接而非本文件(见[通过 FailproofAI Cloud 使用 Jev](/zh/reference/jev-cloud))。 | +| `apiKey` | 以 `Authorization: Bearer ` 方式发送。 | +| `baseUrl` | `custom` 时必填;否则替换 provider 的 API base。必须使用 `https`。仅在 `mode: observe` 时接受明文 `http` 到 `localhost`:本地端口无身份验证,代理停机时,机器上任何进程(包括被审查的 agent 本身)都可能在其位置上响应。 | +| `accountId` | 仅 Cloudflare 需要:32 位小写十六进制字符。 | +| `model` | 替换 provider 的默认模型 ID。带版本的 ID 必须指向 Jev 1.13。形如 API 密钥的值会被拒绝(且不会回显),因此误填到 `--model` 的密钥不会被存储或作为模型名发送。 | +| `timeoutMs` | 工具调用等待 Jev 响应的超时时间,超时后使用正则策略结果。范围 100–10000,默认 3000。 | +| `mode` | `enforce`(默认)、`observe` 或 `off`(保留配置,不运行 Jev)。 | + +三条规则保护此文件: + +- **仅限所有者访问。** 文件以 `0600` 权限写入。任何其他用户或组可读可写的副本将被**拒绝**,hooks 将回退到正则策略,直到你执行 `chmod 600 ~/.failproofai/jev.json` 或重新运行 `setup`。目录也会被检查:`~/.failproofai` 不得被其他任何人**写入**,因为有写入权限者可以替换文件,无论文件本身的权限如何。`setup` 发现此类写入位时会将其移除。`failproofai jev status` 会在配置被拒绝时给出提示,并显示文件所指向的端点:他人可能已修改过该文件,请在执行 `chmod` 前确认文件内容属于你。对这类文件重新运行 `setup` 时,已存储的密钥仅发送到 provider 的官方 API;文件中指向其他端点的配置需重新提供密钥(`--key-stdin`),或使用 `--base-url default` 将请求重定向回 provider。 +- **仅全局配置有效。** 仓库无法开启 Jev、将其指向其他端点或选择模型:项目内的 `.failproofai/jev.json` 会被忽略,provider、URL、模型和账户 ID 只从上述全局文件读取——而非从环境变量读取(仓库的 agent 设置可以设置环境变量)。(`FAILPROOFAI_HOME` 也无法绕过此限制:它会移动整个 failproofai 目录(包括策略),而不是单独重定向 Jev。) +- **仅密钥可从环境变量读取。** 若文件中没有 `apiKey`,`FAILPROOFAI_JEV_API_KEY` 将在当前会话中提供密钥(`setup --key-from-env` 会写入这样的文件)。它不会替换文件中已有的密钥,也无法在没有配置文件的情况下单独启用 Jev。若未设置该变量,Jev 在该 shell 中仅为关闭状态:`failproofai jev status` 会给出提示,以退出码 0 退出并保持配置不变(`status --json` 返回 `"status": "key-missing"` 及 `"reason": "no-env-key"`)。`failproofaid` 守护进程无法访问你的 shell 环境变量,因此在通过 `failproofai config` 配置的机器上,请将密钥保存在文件中。 + +## 响应的 Jev 版本 + +Failproof AI 的决策阈值是针对 Jev 1.13 校准的,因此只有来自该版本家族的答复才会被使用:`jev-1.13.x`,或 OpenRouter 的 `typesafe/jev-1.13-`。若 provider 仅以别名标识 Jev 且未报告版本(Vercel,以及未说明版本的 Cloudflare),答复仍会被使用,但记录为未验证。`custom` 端点必须报告响应的模型名;唯一的例外是你为其配置的无版本号 `--model` 名称,该名称回显时同样记录为未验证。报告其他版本的答复,或未报告模型的 `custom` 答复,均不会被使用:该调用将以 `model-mismatch` 为原因回退到正则策略。 + +## Jev 无法给出答复时 + +以下每种情况都会使该调用回退到正则策略结果,并记录相应原因,`failproofai jev status` 会汇总各原因的次数: + +| 原因 | 触发条件 | +| --- | --- | +| `timeout` | 在 `timeoutMs` 内未收到答复。 | +| `http-429` | provider 对该密钥触发了速率限制。 | +| `rate-limited` | Failproof AI 自身的限速器在发送前拦截了该调用:每秒最多 5 次请求,突发上限也为 5 次,provider 返回 `429` 后会短暂暂停。非 provider 侧限制。 | +| `http-500`、`http-502`、`http-503`……| provider 侧服务器错误,具体状态码会被记录。 | +| `out-of-credits` | HTTP 402:provider 账户积分已耗尽。 | +| `provider-refused` | Cloudflare 返回的 HTTP 402,提示"Model execution failed (Payment error)":provider 拒绝在此请求上运行模型。通常与计费无关,充值不能解决问题。 | +| `http-401`、`http-403` | 密钥被拒绝。 | +| `http-404` | `/systemone` 路径下无内容,说明 base URL 有误——`/systemone` 会被附加在其后,每个 provider 在其版本根路径下提供该接口。`failproofai jev models` 可查看端点实际提供的内容。 | +| `network` | 无法连接到端点。 | +| `http-301`、`http-302`、`http-307`、`http-308` | 端点返回了重定向。重定向永远不会被跟随,答复只会来自配置中的 URL;请将 `--base-url` 设置为最终 URL。 | +| `malformed` | 端点有响应,但不是 Jev 格式的答复——响应体不是 JSON,或其中不含答案。 | +| `cloudflare-error`、`cloudflare-incomplete` | Cloudflare 信封报告了失败,或任务尚未完成。 | +| `model-mismatch` | 响应的 Jev 版本不是 1.13,或 `custom` 端点未说明响应的模型。 | +| `request-cut` | **不是故障。** Jev 已响应,但只看到了部分调用内容,因此其答复不能清除任何拒绝。详见[Jev 有响应但未覆盖完整调用时](#when-jev-answered-but-not-on-the-whole-call)。 | + +`failproofai jev status` 还可能显示一些更罕见的原因,例如 `upstream-error`(答复携带了 provider 自身的错误)或 `config`,以及将所有无法命名的原因汇总为 `other`。 + +`request-cut` 被收录在此表中,是因为 `failproofai jev status` 会将其与其他原因一并汇总,且它同样会保持所有拒绝有效。但它是这里唯一与 provider 状态无关的原因:请求已到达评估器,Jev 也已给出答复。与上方所有行不同,该答复仍然有效——Jev 自身的拒绝或警告会在正则策略结果之上叠加,而非被丢弃。因此,若连续出现多个此类记录,说明到达评估器的调用内容过大无法完整发送,而非端点异常,充值积分或更换 URL 也无法改变这一数字。 + +## Jev 有响应但未覆盖完整调用时 + +还有两种情况,都不是 Jev 未能给出答复,而是关于调用本身或对话的多少内容能装入一次请求。 + +**调用内容本身未能完整装入。** 工具调用在固定预算内发送,对于超大调用——非常大的 `Write`、巨型 MCP 体、被填充到上限的命令——会发送能装入的部分。Jev 仍会给出答复,该答复仍然有效:其自身的拒绝或警告照常生效。但它无法**清除**任何内容,因为基于部分调用给出的裁决不是对整个调用的裁决。因此所有策略拒绝保持有效,该调用以 `request-cut` 为原因记录为回退,`failproofai jev status` 会将其与上方的原因一并汇总。这条规则的含义是:让调用变得更大可能导致其失去清除授权,但永远无法换取授权。 + +**某条消息未能完整装入。** 你粘贴的长提示词、agent 的最后一条消息,或已被此评估器自身的存储截断过的提示词。**这种情况不会改变任何结果**:该调用的判断、清除和记录与其他调用完全相同,也不会被计为回退。你输入内容的长度永远不会决定裁决,截断也无法制造同意:若提示词在到达时已被截断,"你没有要求此操作"就不再是一个可以得出的结论,而非变成一个结论。 + +两者的区别在于文本的作者。调用是 agent 编写的,若允许其长度降低严重性,则等于给了 agent 可利用的规则;提示词是你写的,将其长度视为信号只会惩罚粘贴规格文档或调用栈的正当行为。 + +## 什么内容会离开本机 + +对于 Jev 评估的每次工具调用,会向你的 provider 发送一次请求,内容包括: + +- 工具调用本身,其中 API 密钥、Bearer token 和 `KEY=` 赋值等密钥信息已脱敏处理; +- 你最近输入的提示词,其中 agent harness 添加的文本已移除; +- 在你最近一条提示词之前 agent 发送的最后一条消息,标注为 agent 编写; +- 本地计算的事实信息,例如路径是否在项目目录内——会话首次接受审查时所在的目录,[在会话期间锁定](/zh/reference/jev-intent#the-project-root)——以及当前 git 分支。 + +请求仅发送到你配置中指定的端点,使用你自己的密钥。 + +## 关闭 Jev + +```bash +failproofai jev remove +``` + +此命令会删除 `~/.failproofai/jev.json`。从下一次工具调用起,hooks 将完全按之前的方式执行正则策略。`~/.failproofai/state/semantic/` 下的会话级存储(`sessions/` 中的已记录提示词、`roots/` 中的项目根目录)将保留原位并自然老化过期。若想停止调用 Jev 但保留配置,请改用 `failproofai jev setup --mode off`。 + +## 命令参考 + +| 命令 | 效果 | +| --- | --- | +| `failproofai jev --url --key-stdin` | 一条命令完成配置;provider 由 URL 主机名决定 | +| `failproofai jev --url --token ` | 同上,密钥放在命令行——会出现在历史文件和进程列表中 | +| `failproofai jev setup --provider --key-stdin` | 从 stdin 管道读取密钥并写入配置 | +| `failproofai jev setup --provider ` | 同上,在遮蔽提示符处输入密钥 | +| `failproofai jev setup --key-from-env` | 不存储密钥;每次会话从 `FAILPROOFAI_JEV_API_KEY` 读取 | +| `failproofai jev setup --mode observe` | 切换模式(`enforce`、`observe` 或 `off`),保留已存储密钥 | +| `failproofai jev setup --model ` / `--base-url ` | 覆盖模型或 API base;使用 `default` 清除覆盖 | +| `failproofai jev setup --timeout-ms ` | 修改每次调用的超时预算 | +| `failproofai jev status [--json]` | 配置、权限及近期活动;永不显示密钥 | +| `failproofai jev test [--json]` | 一次实时请求:显示延迟和响应版本 | +| `failproofai jev models [--provider ] [--url ] [--json]` | 该端点 `/models` 接口报告的模型 ID,并标注当前配置的模型 | +| `failproofai jev remove` | 删除配置;Jev 关闭 | \ No newline at end of file diff --git a/docs/zh/reference/jev.mdx b/docs/zh/reference/jev.mdx new file mode 100644 index 000000000..39888de90 --- /dev/null +++ b/docs/zh/reference/jev.mdx @@ -0,0 +1,22 @@ +--- +title: "Jev 集成参考" +description: "Jev 的配置、提供商、密钥、请求数据及故障行为说明。" +icon: "braces" +--- + +Jev 在 Failproof AI 中有两种用途: + +| 用途 | 运行时机 | 返回内容 | 入口 | +| --- | --- | --- | --- | +| 会话评估 | 会话结束后 | 固定答案问题的评分 | [Jev 评估](/zh/evaluations/jev) | +| 工具调用策略审查 | 受管控的工具调用执行前 | 与已安装策略一并返回的裁决结果 | [Jev 策略](/zh/policies/jev) | + +## 参考页面 + +| 主题 | 详情 | +| --- | --- | +| [评估问题](/zh/reference/jev-evaluations) | 布尔型与有序评分标准、结果、限制及回填说明。 | +| [提供商对比与自有密钥配置](/zh/reference/jev-providers) | TypeSafe、OpenRouter、Vercel、Cloudflare 及自定义端点;URL 推断、模型 ID、`jev.json`、模式与回退码。 | +| [FailproofAI Cloud 路由](/zh/reference/jev-cloud) | 机器密钥权限、自动观测配置、用量限制、连接状态及数据处理。 | + +本地 CLI 命令详见 [Failproof AI CLI 参考](/zh/reference/failproof-cli)。[本地仪表盘参考](/zh/reference/local-dashboard#set-up-jev)介绍了其 Jev 设置与活动视图。 \ No newline at end of file diff --git a/docs/zh/reference/mcp.mdx b/docs/zh/reference/mcp.mdx new file mode 100644 index 000000000..1f458d2fb --- /dev/null +++ b/docs/zh/reference/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "MCP 服务器" +description: "使用您自己的权限将 Claude、Cursor、Codex 或其他 MCP 客户端连接到 Failproof AI Cloud。" +icon: "plug" +--- + +将 AI 工具连接到 Failproof AI Cloud,并通过它处理您的 Agent 数据。您的工具可以查询会话和事件、执行只读 SQL、读取仪表板、告警、问题、审计和策略,如果您拥有相应权限,还可以进行更改,例如创建告警或部署策略。 + +每次调用都以**您自己的**权限运行,在您连接时选择的**某一个**组织中执行。 + +所有人共用同一个地址,无论是托管版还是自托管版: + +```text +https://gateway.befailproof.ai/mcp +``` + +## 连接客户端 + +将上述地址添加到您的客户端。第一次使用某个工具时,浏览器会自动打开。选择您的 Failproof AI Cloud 所在位置,登录,选择一个组织,然后点击**允许**。点击**取消**则不会连接任何内容。 + +页面会显示应用名称及其回调地址。如果某个应用没有通过自己的网址进行标识,则会被标记为**未验证应用**,只有在您确认是从自己的客户端发起连接时才应继续操作。 + + + + 在 claude.ai 或 Claude Desktop 中,前往**设置 → 连接器 → 添加自定义连接器**。将其命名为 `Failproof AI`,输入上述地址,点击**添加**,然后点击**连接**。 + + 在 Team 和 Enterprise 计划中,需要由所有者先为组织添加连接器,然后每位成员再分别连接自己的账户。 + + + ```bash + claude mcp add --transport http failproofai https://gateway.befailproof.ai/mcp + ``` + + 然后在 Claude Code 中运行 `/mcp`,选择 `failproofai`,并选择**验证身份**。 + + + 将以下内容添加到 `~/.cursor/mcp.json`,或项目的 `.cursor/mcp.json` 中: + + ```json + { + "mcpServers": { + "failproofai": { "url": "https://gateway.befailproof.ai/mcp" } + } + } + ``` + + Cursor 会在服务器旁边显示**需要登录**。点击该提示以完成登录。 + + + 将以下内容添加到 `~/.codex/config.toml`: + + ```toml + [mcp_servers.failproofai] + url = "https://gateway.befailproof.ai/mcp" + ``` + + 然后运行 `codex mcp login failproofai`。 + + + 任何支持通过 Streamable HTTP 与 OAuth 访问远程 MCP 服务器的客户端均可使用。提供上述地址即可,无需配置客户端 ID 或密钥。 + + + +## 每个连接对应一个组织 + +一个连接只在您选择的组织中运行。如需使用两个组织,请将服务器添加两次并使用不同的名称,例如 `failproofai-acme` 和 `failproofai-sandbox`,并分别连接到各自的组织。 + +演示组织不接受连接,请选择您自己的组织。 + +## 权限 + +连接可以执行您在该组织中有权执行的操作,范围限于以下权限集。连接会跟随您当前的权限:管理员授予您更多权限后,工具将在下次调用时获得相应权限;若权限被撤销,工具也将在下次调用时失去该权限。 + +| 权限 | 允许工具执行 | +| --- | --- | +| `events:read` | 列出事件、读取会话概览、列出 Agent 和环境 | +| `evaluations:read` | 列出会话,读取并汇总评估结果和任务 | +| `evaluations:trigger` | 创建评估、发布新版本、开启或关闭评估、回填数据,以及重新评估某个会话 | +| `dashboards:read`、`dashboards:write` | 读取仪表板,或创建、重命名仪表板及向其添加查询 | +| `queries:read`、`queries:write` | 读取已保存的查询,或保存并编辑查询 | +| `queries:run` | 执行一次只读 SQL 查询并读取查询 Schema | +| `alerts:read`、`alerts:write` | 读取告警,或创建、编辑、暂停、删除和测试告警 | +| `issues:read` | 读取问题、确认问题并发表评论 | +| `issues:create` | 针对某个告警创建问题 | +| `issues:close` | 解决并关闭问题 | +| `audits:read`、`audits:write` | 读取审计、运行记录和发现项,或创建、编辑审计并启动运行 | +| `code_fixes:read` | 查看问题的修复方案,并获取上下文以供您自己的 Agent 修复 | +| `code_fixes:write` | 在 Failproof AI Cloud 中启动修复流程,该流程会在您的 GitHub 上创建一个 Pull Request | +| `policies:read`、`policies:write` | 读取策略、机器和部署信息,或发布、部署和回滚策略 | + +少数工具无需权限,因为它们不读取任何组织数据:构建会话和事件链接,以及搜索本文档。 + +AI 工具无法访问 API 密钥、用户、设置或组织管理功能,也无法发送事件。 + +## 审批变更 + +如果您的客户端支持显示提示,写入操作会先向您确认。您可以查看将要发生的变更,然后选择**批准此变更**以继续。如果您拒绝或在约 4 分钟内未作回应,则不会有任何变更。部分客户端等待时间不到 1 分钟,请及时回应。 + + + 不支持提示功能的客户端不会进行询问,写入操作会在客户端发起调用后立即执行。在此情况下,客户端自身的确认是唯一的确认机制,因此请确保对写入工具保持开启状态。 + + +## 已连接应用与撤销授权 + +**设置 → 集成 → MCP** 列出您在当前组织中已连接的应用,包括其权限和最后使用时间。点击**撤销**可立即断开某个应用的连接。在客户端中移除服务器也会撤销连接。 + +每个组织最多可连接 5 个应用。重新连接同一应用将替换其之前的连接。 + +## 自托管部署 + +连接时选择**自托管 Failproof AI Cloud**,并输入您登录时使用的地址。您的部署必须可通过公共 HTTPS 访问。 + +工具调用及其结果在您的 AI 工具和您的部署之间传输时,会经过托管的 Failproof AI 网关。该网关不存储这些数据。 + +## 数据处理说明 + +结果将发送至您连接的 AI 工具,该工具的提供商将依据其自身条款对数据进行处理。对于每次工具调用,Failproof AI 仅记录工具名称、调用结果、耗时和所属组织,不记录参数或结果内容。请参阅[隐私政策](https://befailproof.ai/privacy/)。 + +## 故障排查 + +| 看到的现象 | 解决方法 | +| --- | --- | +| "在另一个浏览器中启动" | 请在客户端打开的浏览器中完成登录(需允许 Cookie),然后重新从客户端发起连接 | +| 点击**允许**后出现错误 | 该链接仅可使用一次,且 10 分钟后过期,请重新从客户端发起连接 | +| 预期的工具不见了 | 您在此组织中没有对应权限,请联系管理员。获得权限后无需重新连接 | +| 客户端反复要求登录 | 连接已被撤销、您已离开该组织,或连接闲置超过 90 天。请重新连接 | +| "您已有 5 个已连接应用" | 在**设置 → 集成 → MCP** 中撤销一个应用,然后重新连接 | + +仍有问题?请发送邮件至 [support@befailproof.ai](mailto:support@befailproof.ai)。 \ No newline at end of file diff --git a/docs/zh/reference/otel.mdx b/docs/zh/reference/otel.mdx new file mode 100644 index 000000000..aaa822507 --- /dev/null +++ b/docs/zh/reference/otel.mdx @@ -0,0 +1,77 @@ +--- +title: "OpenTelemetry CLI" +description: "为编程智能体启用 OTEL,检查数据传输状态,并恢复之前的设置。" +icon: "radio" +--- + +`failproofai otel` 用于配置向 FailproofAI Cloud 发送可选的 OpenTelemetry 报告。首先通过 `failproofai config` 连接您的机器,并请组织管理员启用 **Settings → OpenTelemetry**。 + +交互式设置会在 Cloud 密钥字段和智能体选择器之后询问 OpenTelemetry 相关选项。该步骤为可选,默认选择"否"。选择"是"可选择 OTEL 智能体;连接写入后将运行相同的启用代码。在设置完成前按 Esc 不会应用任何更改。非交互式设置、提供密钥、开源模式以及保留已保存的连接均不会自动启用该功能。 + +## 启用智能体 + +```bash +failproofai otel enable claude +failproofai otel enable codex --local +failproofai otel enable codex --no-content +failproofai otel enable copilot +failproofai otel enable all --yes +``` + +支持的智能体包括 `claude`、`codex` 和 `copilot`(VS Code)。Copilot 的设置需要 VS Code 可执行文件或已安装的 Copilot 扩展。仅有残留的设置目录是不够的;若两者均未找到,设置将跳过 Copilot。 + +`--local` 将数据发送至本地中继,而非直接发送至 Cloud。Copilot 会自动使用中继,因为其设置无法存储认证头。 + +中继仅在您的本机上监听。您配置的 FailproofAI 守护进程将在数秒内识别到变更,无需重启。如果另一个应用程序占用了中继端口,状态将显示为关闭,守护进程将继续运行。 + + +文本捕获默认开启。添加 `--no-content` 可省略提示词和工具详情。不同版本的智能体可能提供不同的内容控制选项;在将其用于敏感数据之前,请仔细查看您的智能体会导出哪些内容。 + + +Codex 仅导出对话日志,不导出内部运行时跟踪或指标。如果您的 Codex 配置中明确设置了 `log_user_prompt = false`,该设置将保持关闭状态;启用时,若保留了该选项,程序会打印一条提示信息。 + +### 选择一种报告路径 + +如果某智能体已启用会话记录报告,设置将询问: + +> failproofai already sends Claude Code sessions to Cloud. Send them with OTEL instead? Transcript upload for Claude Code stops. + +默认选择"否"。使用 `--yes` 可在不提示的情况下接受切换。其他智能体和策略执行不受影响。 + +Codex 的设置会等待守护进程确认收集器变更后,再写入其导出器设置。如果确认超时,设置将提示您在启动 Codex 之前稍作等待。 + +Config v2 将已记录的跟踪列表保存在 `agents.selected`(检测历史保存在 `agents.seen`)。各智能体的会话记录偏好保留在 `collector.agents..sessions`,OTEL 所有权保留在 `otel.agents`,中继设置保留在 `collector.otlp.enabled` / `collector.otlp.port`。这些独立的键使旧版 OTEL 配置保持可读性:设置可以在不丢失传输偏好或恢复智能体设置所需状态的情况下更改跟踪列表。 + +## 检查设置 + +```bash +failproofai otel status +``` + +状态信息会显示每个智能体的情况,包括:其设置是否由 FailproofAI 管理、目标地址、组织的数据接收开关、中继状态以及最近一次中继上传结果。 + +组织开关显示为 `unknown` 意味着服务器未提供该信息或无法访问。这不是错误,也不会阻止在旧版 Cloud 上进行配置。 + +如果 Cloud 尚不支持 OTEL,中继将保留被拒绝的导出数据,而非直接丢弃。如果组织的数据接收功能已关闭,`enable` 将不写入任何内容并以错误退出;请先请管理员开启该功能。 + +## 为应用程序打印配置 + +```bash +failproofai otel env --service my-agent +failproofai otel env --service my-agent --local +``` + +输出为适用于 OTLP/HTTP 导出器的 shell 环境变量块。Cloud 输出将 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置为 Cloud 的 OTLP 基础地址 `https:///otel`,导出器会自动追加 `/v1/`;若使用 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 等按信号类型设置的变量,则需要完整路径 `https:///otel/v1/logs`。本地输出指向中继地址 `http://127.0.0.1:`。Cloud 输出包含已配置的 API 密钥,请将其视为机密信息。本地输出不包含密钥。如需使用本地输出,请先启用一个本地智能体以确保中继正在运行。 + +## 恢复之前的设置 + +```bash +failproofai otel disable claude +failproofai otel disable all +``` + +Disable 仅恢复由 FailproofAI 写入的设置,保留无关的更改,并恢复每个智能体之前的会话记录报告选项。当最后一个受管理的本地智能体被禁用时,中继将停止接受导出数据。 + +对于 Codex,disable 还会记录 `collector.agents.codex.sessions_resume_after`(Unix 毫秒时间戳)。现有的已传输字节将被视为已投递,因此通过 OTEL 捕获的会话不会被再次上传;之后追加的内容仍会通过会话记录报告传输。 + +所有命令均支持 `--help`。有关应用程序和编程智能体的示例,请参阅 [OpenTelemetry in Cloud](/zh/agenteye/opentelemetry)。 \ No newline at end of file diff --git a/docs/zh/reference/slack.mdx b/docs/zh/reference/slack.mdx new file mode 100644 index 000000000..692396fdb --- /dev/null +++ b/docs/zh/reference/slack.mdx @@ -0,0 +1,111 @@ +--- +title: "Slack 应用" +description: "在 Slack 中向 Failproof 助手提问,在对话线程中获取图表,并通过按钮审批变更。" +icon: "slack" +--- + +在 Slack 中使用 [Failproof 助手](/zh/sessions/assistant)。在频道中 @ 提及该应用,直接向其发送消息,或使用 `/failproof <问题>`。回答使用**您自己的** Failproof AI 权限,图表会出现在对话线程中,任何会引发变更的操作都会先请求您审批。 + +只有一个官方应用,无论您的 Failproof AI Cloud 是托管版还是自托管版,使用方式完全相同。 + + + 回答由 AI 模型生成,可能存在不准确之处。请务必对照关联的源数据核实重要信息。 + + +## 连接工作区 + +您需要在 Failproof AI 中拥有 `settings:write` 权限,同时在 Slack 中是工作区管理员或所有者,或者是负责添加该应用的人员。 + + + + 1. 前往 **Settings → Integrations**,选择 **Add to Slack**。 + 2. 在 Slack 中授权该应用。 + 3. 返回 Failproof AI,确认将该工作区连接到您的组织。 + + + 1. 添加应用后,打开其 **Home** 标签页。 + 2. 选择 **Continue with FailproofAI Cloud**,或选择 **Use my own URL** 并输入您的登录地址。 + 3. 点击继续按钮,登录,选择组织并确认。该链接仅可使用一次,10 分钟后失效。 + + + +一个工作区对应一个组织,一个组织也只能对应一个工作区。 + +还没有账户?请先[创建一个](https://app.befailproof.ai/login),然后再进行连接。 + +## 您在 Slack 中的身份 + +首次提问时,应用会自动识别您的成员身份: + +- **通过邮箱自动匹配**:当您是已连接工作区的正式成员、Slack 邮箱已验证,且组织中有且仅有一名成员使用该邮箱时,系统会自动完成匹配。 +- **其他情况**:您会收到一个私信发送的 **Link your account** 按钮,点击后会跳转至 Failproof AI,将您的 Slack 用户与账户关联。 + +## 提问方式 + +| 场景 | 操作方式 | +| --- | --- | +| 频道 | @ 提及该应用。在其对话线程中回复即可继续,无需再次提及 | +| 直接消息 | 直接向该应用发送消息 | +| 应用所在的群组直接消息 | 提及它,之后在对话线程中回复即可继续 | +| Slack Connect 频道 | 提及该应用 | +| 应用所在的任意对话 | `/failproof <问题>` 会创建一个包含回答的对话线程 | +| `/failproof help` | 查看该应用的功能说明 | +| `/failproof status` | 查看已连接的组织以及您关联的账户身份 | +| `/failproof link` | 查看您关联的 Failproof AI 账户 | + +一个线程对应一段对话。同事可以在同一线程中提及该应用,应用会根据各自的权限分别作出回答。只有发起该线程的人可以在无需提及的情况下继续对话。 + +当回答涉及数据时,应用会发布图表或表格,并附上在 Failproof AI 中打开的链接。 + +## 审批变更 + +助手执行的每项变更都会先显示 **Approve** 和 **Cancel** 按钮,且 Slack 在 **Approve** 前还会再次确认。只有提问的人才能响应这些按钮,按钮在 5 分钟后失效,变更将以该人员的权限执行。 + +在 Slack 中,助手可以在您拥有相应权限的情况下,修改已保存的查询和仪表板、评估、告警、审计、问题、策略,以及建议代码修复。它无法更改 API 密钥、用户或设置。 + +## 链接预览 + +在托管版 Failproof AI Cloud 中,粘贴到 Slack 的 Failproof AI 问题、会话和评估链接会展开为卡片。卡片仅显示触发该预览的人员有权查看的内容。自托管地址的链接不会展开,但助手自身回答中的卡片仍会正常显示。 + +## Slack Connect 频道 + +其他工作区的人员在关联账户后,只要是组织成员,即可使用该应用。回答对对话中的所有人可见,包括不是您组织成员的人,因此请在所有人都可能看到回答的场合谨慎提问。 + +只有当频道中其他所有工作区都有成员与该组织关联后,应用才会开始回答。在此之前,应用会向提问者说明原因。 + +## 应用申请的权限 + +| Slack 权限 | 用途 | +| --- | --- | +| `app_mentions:read` | 识别何时有人提及该应用 | +| `channels:history`、`groups:history`、`im:history`、`mpim:history` | 接收直接消息以及应用线程中的回复。应用会忽略其他消息,且不会读取对话的历史记录 | +| `channels:read`、`groups:read`、`im:read`、`mpim:read` | 检查所在对话的类型,以便了解哪些人可以看到回答 | +| `chat:write` | 发布回答和审批按钮 | +| `commands` | 提供 `/failproof` 命令 | +| `files:write` | 发布图表 | +| `links:read`、`links:write` | 显示粘贴的 Failproof AI 链接预览 | +| `users:read`、`users:read.email` | 将您与 Failproof AI 账户匹配,并显示姓名 | + +## 断开连接 + +前往 **Settings → Integrations** 并选择 **Disconnect**,或在应用的 **Home** 标签页使用 **Disconnect**,或直接从 Slack 中移除该应用。 + +以上任意操作都会删除该工作区的连接、机器人令牌、关联账户及线程记录。Slack 中的历史对话仍可在仪表板中查看。之后该组织可立即连接任意工作区。 + +## 数据与隐私 + +问题和回答会作为对话保存在您组织的仪表板中,归属于发起该线程的人员。Slack 数据不会被用于训练 AI 模型。请参阅[隐私政策](https://befailproof.ai/privacy/)了解应用接收的数据内容及保留时长。 + +## 故障排查 + +| 显示内容 | 处理方法 | +| --- | --- | +| "This workspace isn't connected to a FailproofAI Cloud yet." | 由工作区管理员打开应用的 **Home** 标签页并选择一个 Cloud | +| "This link expired or was already used." | 在 **Home** 标签页重新选择您的 Cloud 以获取新链接 | +| "This org is already connected to a Slack workspace." | 请先在设置中断开连接 | +| "That Slack workspace is connected to another org." | 请先从该组织中断开该工作区 | +| "Link your account to use the assistant." | 点击按钮并在 Failproof AI 中确认 | +| 应用在群组直接消息中没有回应 | 重新将应用添加到 Slack 以授予群组权限,您的连接会保留 | +| "I won't post answers from your organization here" | 请让该工作区中属于该组织成员的某人提及该应用并关联其账户 | + +仍有问题?请发送邮件至 [support@befailproof.ai](mailto:support@befailproof.ai)。 \ No newline at end of file diff --git a/docs/zh/sessions/sentiment.mdx b/docs/zh/sessions/sentiment.mdx new file mode 100644 index 000000000..6c0ffb632 --- /dev/null +++ b/docs/zh/sessions/sentiment.mdx @@ -0,0 +1,43 @@ +--- +title: "情感分析" +description: "通过 Jev 情感评分,找出沮丧、困惑和纠正性消息。" +icon: "smile" +--- + +Jev 对用户发送给 agent 的每条消息,从 0 到 100 进行四种情绪评分——**愤怒**、**沮丧**、**高兴**和**困惑**——以及三个关于 agent 表现的信号: + +- **纠正**:用户指出 agent 犯了错误。 +- **已解决**:用户确认 agent 解决了他们的问题。 +- **存疑**:用户质疑 agent 的回答是否准确,或者 agent 是否真正完成了工作。 + +使用情感分析可以发现用户耐心正在消耗的对话、被频繁纠正的 agent,以及反响良好的回复。这是内置的 Jev 评分功能,无需自行编写评估。如需针对固定答案的问题进行评估,请[创建 Jev 评估](/zh/evaluations/jev)。 + + + 情感分析默认关闭,需由管理员在组织级别开启。Jev 对每条消息发起一次评分请求,并在评分时获取该消息及其前一条 agent 回复。评分消耗组织的模型预算。 + + +## 开启情感分析 + +1. 前往 **Administration → Settings**。 +2. 在 **Human input sentiment** 下,将其切换为**开启**并保存。 + +系统将优先对过去一天的消息进行评分。之后,新消息将在到达后的一两分钟内完成评分。 + +## 查找待审查的对话 + +打开 **Observe → Sentiment**。可按时间、环境、agent 或会话 ID 进行筛选。顶部统计栏显示消息和会话数量、**已标记**的消息数量,以及最主要的信号类型。当愤怒、沮丧、纠正、困惑或存疑分数达到 100 分中的 35 分时,该消息将被标记。 + +![情感分析仪表盘,显示消息和会话数量、已标记消息以及随时间变化的 Jev 评分。](/images/dashboard/sentiment-overview.png) + +使用 **Score over time** 对比各信号。选择要展示的评分维度,然后点击某个时间点查看该时间段内的消息。**By agent** 表格展示信号的集中分布情况。在 **Messages** 中,可按最强负面评分排序,或选择单一评分维度。在会话中打开某条消息,阅读上下文对话,再判断问题所在。 + +![按最强负面评分排序的情感消息列表,附有指向各来源会话的链接。](/images/dashboard/sentiment-messages.png) + +## 哪些消息会被评分 + +仅对用户本人撰写的消息评分: + +- 通过 SDK 以人工输入方式记录的自定义 agent 消息。 +- 在 Claude Code、Codex、OpenCode、pi、Hermes 和 OpenClaw 中输入的提示词(在发送会话记录时,即默认情况下)。定时任务、注入的指令、子 agent 交接及 agent 运行时自动生成的文本不在评分范围内。非交互式运行(如 `claude -p`、`codex exec` 和 `hermes -z`)同样不被评分——这些提示词由脚本生成,而非真人输入。 + +评分仅针对用户自身的表达。简短直白的指令(如"修好它")不会被判定为愤怒,提问也不会被判定为困惑。新请求不构成纠正,单纯表达感谢也不计为已解决。 \ No newline at end of file diff --git a/docs/zh/start/use-jev.mdx b/docs/zh/start/use-jev.mdx new file mode 100644 index 000000000..ca6d96817 --- /dev/null +++ b/docs/zh/start/use-jev.mdx @@ -0,0 +1,63 @@ +--- +title: "使用 Jev" +description: "为已完成的会话配置 Jev 评估,或为实时工具调用审查配置 Jev policies。" +icon: "sparkles" +--- + +Jev 在智能体运行的两个环节发挥作用:对已完成的会话按已知答案打分,或在您向智能体下达指令的上下文中审查工具调用。 + + + + 当一个已完成的会话可以针对少量已知答案进行评分时,请使用 Jev eval,例如"客户是否要求退款?请回答是或否。"它能帮助您发现跨会话的规律。 + + ## 创建 eval + + 在 Cloud 仪表板中,依次打开 **Analyze → eval authoring → new eval**。输入一个固定答案的问题,选择 **draft**,并确认它选择了分类器评分方式。在真实会话上[测试](/zh/evaluations/test)后,再将其部署。 + + ![共享的 eval 创作表单,您可以在此描述问题、审阅草稿并进行部署。截图展示的是代码草稿;Jev 请使用固定答案类型的问题。](/images/dashboard/eval-authoring-draft.png) + + ## 查看评分 + + 新会话完成后,打开 **Observe → Evaluations**,或使用 Cloud CLI: + + ```bash + fp evals --since 7d + fp evals --aggregate --since 7d + ``` + + CLI 用于读取评分;创建 Jev eval 目前需通过仪表板完成。有关问题类型和示例,请参阅 [Jev evaluations](/zh/evaluations/jev)。 + + + 当基于字符串匹配的 policy 需要结合您的请求上下文来判断工具调用是否安全时,请使用 Jev policy 审查。建议先以 **observe** 模式启动,这样您可以查看 Jev 的判断结果,同时让已安装的 policies 继续处理每次调用。 + + Jev 的检查规则来自规则包;Failproof AI 默认不附带任何规则包。在您安装之前,即使已完成配置,Jev 也不会进行任何检查: + + ```bash + failproofai policies add FailproofAI/jev-policies + ``` + + ## 配置 Cloud Jev + + 在 Cloud 仪表板中,打开 **Administration → Keys**,使用 **machine** 预设创建一个密钥。按照[快速入门](/zh/start/quickstart)中的说明,配合 `failproofai config` 使用该密钥。在未配置 Jev 的机器上,此操作会以 observe 模式启用 Cloud Jev。通过以下命令检查连接状态: + + ```bash + failproofai jev status + failproofai jev test + ``` + + ## 使用自定义端点 + + 在本地仪表板中,打开 **Settings → Jev**。选择提供商,粘贴其令牌,选择 **observe**,然后开启 Jev。 + + ![本地 Jev 设置面板,包含提供商选项、令牌输入框,以及已选中的 observe 模式。](/images/dashboard/jev-settings.png) + + 或者在终端中配置并测试您的端点: + + ```bash + failproofai jev --url https://api.typesafe.ai/v1 --mode observe --key-stdin < ~/typesafe.key + failproofai jev test + ``` + + 让一个已挂钩的智能体对 `README.md` 使用其文件读取工具。确认该工具调用出现在会话记录中,然后在本地仪表板的 **Policies → Activity** 下检查它。一旦 observe 结果符合预期,请参阅 [Jev policies](/zh/policies/jev) 了解何时开启强制执行。有关提供商详情和配置说明,请参阅[集成参考](/zh/reference/jev)。 + + \ No newline at end of file