@kvman/kvcoder 0.1.10 → 0.1.12

package/dist/web-fetch/fetch-page.js

@@ -0,0 +1,108 @@
+import { lookup } from 'node:dns/promises';
+import http from 'node:http';
+import https from 'node:https';
+import { isIP } from 'node:net';
+import { ProblemError } from '@kvman/sdk';
+import { invalid } from "../problems.js";
+import { truncate } from "../result-text.js";
+import { isPrivateAddress } from "./private-address.js";
+// `web fetch` (plan 08 §8.5, ADR 0095): a page by its address, as Markdown or text. Every host is resolved and checked
+// before each request and each redirect, and the connection goes to the address that was checked.
+export const bodyLimit = 5 * 1024 * 1024;
+const redirectLimit = 5;
+const pageTimeoutMs = 30_000;
+const textTypes = new Set(['application/json', 'application/xml', 'application/javascript']);
+export const webFailed = (url, fields) => new ProblemError({ code: 'kvcoder/WEB_FAILED', message: `${url} couldn't be read: ${fields.status === undefined ? fields.reason ?? 'it failed' : `status ${String(fields.status)}`}.`, params: { url, ...fields } });
+// Reads at most the body limit; the rest of a larger body is left unread.
+function readBody(response) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        response.on('data', (chunk) => {
+            chunks.push(chunk);
+            size += chunk.length;
+            if (size >= bodyLimit)
+                response.destroy();
+        });
+        response.on('close', () => resolve(Buffer.concat(chunks).subarray(0, bodyLimit)));
+        response.on('error', reject);
+    });
+}
+/** The network: Node's resolver, and a request pinned to the checked address. */
+export const networkTransport = {
+    resolve: async (host) => (isIP(host) !== 0 ? [host] : (await lookup(host, { all: true, verbatim: true })).map((found) => found.address)),
+    request: (url, address, signal) => new Promise((resolve, reject) => {
+        const client = url.protocol === 'https:' ? https : http;
+        // Every lookup of this request answers the checked address, so a second resolution can't move it.
+        const pinned = (_host, options, done) => {
+            if (options.all === true)
+                done(null, [{ address, family: isIP(address) }]);
+            else
+                done(null, address, isIP(address));
+        };
+        const request = client.request(url, { method: 'GET', signal, lookup: pinned, headers: { accept: 'text/html, text/markdown, text/plain, application/json;q=0.9, */*;q=0.1', 'user-agent': 'kvman' } }, (response) => {
+            readBody(response).then((body) => resolve({ status: response.statusCode ?? 0, type: String(response.headers['content-type'] ?? ''), location: response.headers.location, body }), reject);
+        });
+        request.on('error', reject);
+        request.end();
+    }),
+};
+// turndown brings a whole DOM, about 14 MB, so a worker loads it with its first page, not at start (plan 12 §12.3).
+async function markdownOf(html) {
+    const { default: TurndownService } = await import('turndown');
+    const turndown = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
+    turndown.remove(['script', 'style', 'noscript']);
+    return turndown.turndown(html);
+}
+// A checked address of the host, or a refusal naming it.
+async function checkedAddress(transport, url) {
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    const addresses = await transport.resolve(host);
+    const [first] = addresses;
+    if (first === undefined || addresses.some(isPrivateAddress))
+        throw invalid(`${url.hostname} is a private or local address, which web fetch doesn't reach.`, { url: url.href });
+    return first;
+}
+function parsed(given) {
+    const url = URL.canParse(given) ? new URL(given) : undefined;
+    if (url === undefined || (url.protocol !== 'http:' && url.protocol !== 'https:'))
+        throw invalid('The address must start with http:// or https://.', { url: given });
+    if (url.username !== '' || url.password !== '')
+        throw invalid("The address can't hold a name or a password.", { url: given });
+    return url;
+}
+async function contentOf(type, body, url) {
+    const text = body.toString('utf8');
+    if (type === 'text/html' || type === 'application/xhtml+xml')
+        return markdownOf(text);
+    if (type.startsWith('text/') || textTypes.has(type) || type.endsWith('+json'))
+        return text;
+    throw invalid(`${url} is ${type === '' ? 'of no stated type' : type}, which web fetch doesn't read; only pages and text.`, { url, type });
+}
+/** Fetches a page, following redirects, each checked again. */
+export async function fetchPage(given, transport, signal) {
+    let url = parsed(given);
+    const timeout = AbortSignal.any([signal, AbortSignal.timeout(pageTimeoutMs)]);
+    for (let redirects = 0;; redirects += 1) {
+        const address = await checkedAddress(transport, url);
+        let response;
+        try {
+            response = await transport.request(url, address, timeout);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            throw webFailed(url.href, { reason: timeout.aborted ? 'it took longer than 30 s' : error instanceof Error ? error.message : 'the connection failed' });
+        }
+        if (response.status >= 300 && response.status < 400 && response.location !== undefined) {
+            if (redirects === redirectLimit)
+                throw webFailed(url.href, { reason: `more than ${String(redirectLimit)} redirects` });
+            url = parsed(new URL(response.location, url).href);
+            continue;
+        }
+        if (response.status >= 400)
+            throw webFailed(url.href, { status: response.status });
+        const type = (response.type.split(';')[0] ?? '').trim().toLowerCase();
+        return { url: url.href, status: response.status, type, content: truncate(await contentOf(type, response.body, url.href)) };
+    }
+}
+//# sourceMappingURL=fetch-page.js.map

package/dist/web-fetch/fetch-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-page.js","sourceRoot":"","sources":["../../src/web-fetch/fetch-page.ts"],"names":[],"mappings":"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"}

package/dist/web-fetch/private-address.d.ts

@@ -0,0 +1,3 @@
+/** Whether an address is one `web fetch` must not reach; something that isn't an address counts as one. */
+export declare function isPrivateAddress(address: string): boolean;
+//# sourceMappingURL=private-address.d.ts.map

package/dist/web-fetch/private-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-address.d.ts","sourceRoot":"","sources":["../../src/web-fetch/private-address.ts"],"names":[],"mappings":"AA2DA,2GAA2G;AAC3G,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKzD"}

package/dist/web-fetch/private-address.js

@@ -0,0 +1,69 @@
+import { isIP } from 'node:net';
+// The addresses `web fetch` never reaches (plan 08 §8.5, ADR 0095, 3): loopback, private, link-local, unique-local,
+// unspecified, and multicast, in IPv4 and IPv6, and IPv4 carried inside IPv6. Addresses are compared as numbers, so
+// every spelling of one address (`::ffff:127.0.0.1`, `::ffff:7f00:1`) is judged the same.
+const v4Blocks = [
+    [0x00000000, 8], // 0.0.0.0/8, unspecified
+    [0x0a000000, 8], // 10/8
+    [0x64400000, 10], // 100.64/10, shared
+    [0x7f000000, 8], // 127/8, loopback
+    [0xa9fe0000, 16], // 169.254/16, link-local
+    [0xac100000, 12], // 172.16/12
+    [0xc0a80000, 16], // 192.168/16
+    [0xe0000000, 4], // 224/4, multicast
+    [0xf0000000, 4], // 240/4, reserved
+];
+function privateV4(value) {
+    return v4Blocks.some(([base, bits]) => Math.floor(value / 2 ** (32 - bits)) === Math.floor(base / 2 ** (32 - bits)));
+}
+function v4Number(address) {
+    return address.split('.').reduce((total, part) => total * 256 + Number(part), 0);
+}
+/** The eight 16-bit groups of an IPv6 address, or nothing when it doesn't expand to exactly eight. */
+function hextets(address) {
+    const dotted = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(address);
+    const v4 = dotted?.[2] === undefined ? undefined : v4Number(dotted[2]);
+    const text = dotted?.[1] === undefined || v4 === undefined ? address : `${dotted[1]}${(v4 >>> 16).toString(16)}:${(v4 & 0xffff).toString(16)}`;
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const groups = (half) => (half === undefined || half === '' ? [] : half.split(':').map((group) => (/^[\da-f]{1,4}$/i.test(group) ? Number.parseInt(group, 16) : Number.NaN)));
+    const head = groups(halves[0]), tail = groups(halves[1]);
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 1 ? missing !== 0 : missing < 1)
+        return undefined;
+    const all = [...head, ...Array(halves.length === 1 ? 0 : missing).fill(0), ...tail];
+    return all.some(Number.isNaN) ? undefined : all;
+}
+const v4Of = (high, low) => high * 0x10000 + low;
+const zeros = (groups) => groups.every((group) => group === 0);
+function privateV6(address) {
+    const groups = hextets(address);
+    if (groups === undefined)
+        return true;
+    const [first = 0, second = 0, third = 0, , , sixth = 0, seventh = 0, eighth = 0] = groups;
+    // ::/96 holds :: and ::1 and the old IPv4-compatible form; ::ffff:0:0/96 is IPv4 mapped into IPv6.
+    if (zeros(groups.slice(0, 6)))
+        return true;
+    if (zeros(groups.slice(0, 5)) && sixth === 0xffff)
+        return privateV4(v4Of(seventh, eighth));
+    // 64:ff9b::/96 is NAT64 and 2002::/16 is 6to4: each carries an IPv4 address, judged as one.
+    if (first === 0x64 && second === 0xff9b && zeros(groups.slice(2, 6)))
+        return privateV4(v4Of(seventh, eighth));
+    if (first === 0x64 && second === 0xff9b && third === 1)
+        return true; // 64:ff9b:1::/48, NAT64 for local use
+    if (first === 0x2002)
+        return privateV4(v4Of(second, third));
+    // fc00::/7 unique-local, fe80::/10 link-local, fec0::/10 site-local, ff00::/8 multicast.
+    return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80 || (first & 0xffc0) === 0xfec0 || (first & 0xff00) === 0xff00;
+}
+/** Whether an address is one `web fetch` must not reach; something that isn't an address counts as one. */
+export function isPrivateAddress(address) {
+    const kind = isIP(address);
+    if (kind === 4)
+        return privateV4(v4Number(address));
+    if (kind === 6)
+        return privateV6(address.split('%')[0] ?? address);
+    return true;
+}
+//# sourceMappingURL=private-address.js.map

package/dist/web-fetch/private-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-address.js","sourceRoot":"","sources":["../../src/web-fetch/private-address.ts"],"names":[],"mappings":"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"}

package/dist/web-fetch/web-hosts.d.ts

@@ -0,0 +1,7 @@
+import type { RunCall } from '../calls/run-tool.ts';
+import type { TxRecords } from '../store/collections.ts';
+/** The host a `web fetch` call names, lowercase, or nothing for another call or an address that doesn't parse. */
+export declare function hostOf(call: RunCall): string | undefined;
+/** Adds the host of an allowed `web fetch` to the chat at the root, in the transaction that applies the answer. */
+export declare function allowHostInTx(store: TxRecords, sessionId: string, call: RunCall): void;
+//# sourceMappingURL=web-hosts.d.ts.map

package/dist/web-fetch/web-hosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-hosts.d.ts","sourceRoot":"","sources":["../../src/web-fetch/web-hosts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAKzD,kHAAkH;AAClH,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIxD;AAED,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAKtF"}

package/dist/web-fetch/web-hosts.js

@@ -0,0 +1,19 @@
+import { executionRootInTx } from "../sessions/execution-root.js";
+// The hosts a chat let `web fetch` reach (plan 08 §8.5, ADR 0095, 4): the first fetch from a host asks, and an allowed
+// one is kept on the chat at the root, so its helpers share it.
+/** The host a `web fetch` call names, lowercase, or nothing for another call or an address that doesn't parse. */
+export function hostOf(call) {
+    if (call.connector !== 'web' || call.command !== 'fetch')
+        return undefined;
+    const given = call.payload['url'];
+    return typeof given === 'string' && URL.canParse(given) ? new URL(given).hostname.toLowerCase() : undefined;
+}
+/** Adds the host of an allowed `web fetch` to the chat at the root, in the transaction that applies the answer. */
+export function allowHostInTx(store, sessionId, call) {
+    const host = hostOf(call);
+    const root = executionRootInTx(store, sessionId);
+    if (host === undefined || root === undefined || root.webHosts.includes(host))
+        return;
+    store.sessions.update(root.id, { webHosts: [...root.webHosts, host] });
+}
+//# sourceMappingURL=web-hosts.js.map

package/dist/web-fetch/web-hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-hosts.js","sourceRoot":"","sources":["../../src/web-fetch/web-hosts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE,uHAAuH;AACvH,gEAAgE;AAEhE,kHAAkH;AAClH,MAAM,UAAU,MAAM,CAAC,IAAa;IAClC,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9G,CAAC;AAED,mHAAmH;AACnH,MAAM,UAAU,aAAa,CAAC,KAAgB,EAAE,SAAiB,EAAE,IAAa;IAC9E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IACrF,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;AACzE,CAAC"}

package/docs/connectors.md

@@ -3,10 +3,9 @@
 A **connector** is a named set of commands the agent runs with its one tool, `run`:
 
 ```json
-{ "description": "Adding milk to the notes", "connector": "notes", "command": "add", "payload": { "text": "Buy milk" } }
+{ "connector": "notes", "command": "add", "payload": { "text": "Buy milk" } }
 ```
 
-- `description` is one sentence for the person, shown on the call's card.
 - `connector` and `command` name what runs; `payload` is the command's input, and may be left out when it takes none.
 - Every connector has the command `help`: with no payload it describes the connector and its commands, and with `{ "command": "add" }` it gives that command's payload and result as JSON Schema, with its examples.
 
@@ -37,14 +36,14 @@ ctx.registerHandler('kernel.started', {
 - `commands`: each command's `name`, the public `command` it runs, and optional `examples` (`{ description, input }`). `help` shows the registered descriptions, JSON Schemas, and examples, so give every input field a `.describe()`.
 - `asks: true` on a command makes the person approve every call of it first (see **A command that asks** below). The field takes only `true`; leave it out for a command that runs at once.
 - Each `command` must be a public command or query of the registering extension, or registration fails `VALIDATION_FAILED`. The command runs through `ctx.exec` with the payload as its input, so validation, cancel, and timeouts are the kernel's, and it runs to its end inside the agent's step.
-- The result the agent reads is the output as JSON on one line, or `error <code>: <message>`. A payload that doesn't fit returns each problem and then the payload's signature, such as `{ text, done? }`, so the agent can correct it in one try; a payload that isn't a plain object returns its JSON Schema on one line instead.
+- The result the agent reads is the output as JSON on one line, or `error <code>: <message>`. A payload that doesn't fit returns each problem and then the payload's signature, such as `{ text (≤200), done? }`, where `(≤N)` is a string's `max` length from your zod schema, so the agent can correct it in one try; a payload that isn't a plain object returns its JSON Schema on one line instead.
 - `binary`: a program on the system, with `{ check, install?, help? }`. `check` is a line whose exit code 0 means the program is usable; the connector is listed, and can be called, only while its check passes.
 
 ## A command that asks
 
 Mark a command with `asks: true` when it changes something the person didn't make in this chat: their settings, their data, what is installed.
 
-- Every call of it becomes an approval card in the chat, showing the call's `description`, the connector and command, and the payload. The turn waits for the answer.
+- Every call of it becomes an approval card in the chat, showing the connector and command, and the payload. The turn waits for the answer.
 - It asks with `kvcoder.approval` on `auto` and on `ask`, and runs at once on `never`, where nothing asks. Otherwise that setting covers kvcoder's own `shell`, `fs`, and `mcp` calls, which carry `risky`; a registered command has no `risky`, so the flag on its entry decides.
 - **Allow** runs the command at the start of the next step, and its result goes to the agent as usual. **Deny** returns `denied by the user`, and the command never runs.
 - The payload isn't checked before the person is asked; the kernel validates it when the command runs.
@@ -102,9 +101,9 @@ Register a connector with `optIn: true`, the only value the field takes, when it
 
 ## Built-in connectors
 
-kvcoder's own connectors are `shell` (one line in the real shell), `fs` (read, list, search, write, and edit files in the workspace folder), `artifact` (a document shown beside the chat), `background` (follow up on what was started with `background: true`), `ask` (a question that suspends the turn), `delegate` (`delegate run { worker, task, background? }` hands a task to a worker, which runs it in a helper session; the workers are the setting `kvcoder.delegate.workers`, and it is a connector of a session only while a worker is turned on), and `mcp` (the tools of the MCP servers the person added; it is a connector of a session only while the workspace has a server). Their names are taken: registering one fails `kvcoder/NAME_TAKEN`.
+kvcoder's own connectors are `shell` (one line in the real shell), `fs` (read, list, find, search, write, and edit files in the workspace folder; `read-files` reads several files in one call, and the model reads a file as numbered lines), `artifact` (a document shown beside the chat), `background` (follow up on what was started with `background: true`), `ask` (a question that suspends the turn), `delegate` (`delegate run { worker, title, task, background? }` hands a task to a worker, which runs it in a helper session, and `delegate continue { id, message, background? }` sends a follow-up to a helper that has ended, which goes on with its own history; the workers are the setting `kvcoder.delegate.workers`, and it is a connector of a session only while a worker is turned on), and `mcp` (the tools of the MCP servers the person added; it is a connector of a session only while the workspace has a server). Their names are taken: registering one fails `kvcoder/NAME_TAKEN`.
 
-`shell exec`, a binary's `exec`, `fs write`, `fs edit`, and `mcp call` ask the person first when the payload says `risky: true`, or always when `kvcoder.approval` is `ask`, and never when it is `never`. A registered command asks only when its entry has `asks: true`, and then always, except on `never`. `risky` is required: a call that leaves it out fails `VALIDATION_FAILED` and asks nobody. Only `shell exec`, a binary's `exec`, and `delegate run` take `background: true`; every other command runs to its end.
+`shell exec`, a binary's `exec`, `fs write`, `fs edit`, and `mcp call` ask the person first when the payload says `risky: true`, or always when `kvcoder.approval` is `ask`, and never when it is `never`. A registered command asks only when its entry has `asks: true`, and then always, except on `never`. `risky` is required: a call that leaves it out fails `VALIDATION_FAILED` and asks nobody. Only `shell exec`, a binary's `exec`, `delegate run`, and `delegate continue` take `background: true`; every other command runs to its end. A background helper's approvals show in the chat, and while it waits on the person its status is `waiting`.
 
 ## Ownership
 

package/locales/ar.json

@@ -15,20 +15,38 @@
   "kvcoder.errors.JOB_NOT_FOUND": "لا توجد في هذه المحادثة مهمة خلفية بهذا المعرّف.",
   "kvcoder.errors.MCP_SERVER_NOT_FOUND": "لا يوجد خادم MCP باسم {server}.",
   "kvcoder.errors.WORKER_NOT_FOUND": "لا يوجد مساعد باسم {worker}.",
+  "kvcoder.errors.WEB_FAILED": "تعذّرت قراءة {url}.",
   "kvcoder.errors.MCP_CONNECT_FAILED": "فشل خادم MCP {server}: {reason}",
   "kvcoder.errors.MCP_SIGN_IN_NEEDED": "خادم MCP {server} يحتاج إلى تسجيل دخولك.",
   "kvcoder.errors.MCP_SIGN_IN_FAILED": "لم ينجح تسجيل الدخول: {reason}",
   "kvcoder.notices.CANCELLED": "أوقفتَ هذه الجولة.",
   "kvcoder.notices.INTERRUPTED": "انقطعت هذه الجولة. قد تكون آثارها غير معروفة؛ لن تُعاد الخطوة القديمة تلقائيًا. أرسل رسالة جديدة للمتابعة.",
   "kvcoder.notices.STEP_FAILED": "توقفت الجولة: {error}",
+  "kvcoder.notices.MODEL_SWITCHED": "بلغ {from} حده، فانتقلت هذه المحادثة إلى النموذج البديل {to}.",
   "kvcoder.notices.MAX_STEPS": "توقفت الجولة بعد بلوغ الحد الأقصى للخطوات ({steps}).",
   "kvcoder.notices.SUMMARY_FAILED": "تعذّر تلخيص الرسائل السابقة: {error}",
   "kvcoder.notices.REPLY_LOST": "لم يصل رد النموذج كاملًا بعد عدة محاولات (ضاع نحو {tokens} توكن). اكتب «تابع» للمحاولة من جديد، أو اختر نموذجًا آخر.",
   "kvcoder.notices.REPLY_INCOMPLETE": "جاء رد النموذج فارغًا أو مقطوعًا عند حد الطول مرتين متتاليتين. أعد المحاولة، أو اختر نموذجًا آخر.",
   "kvcoder.ui.newChat": "محادثة جديدة",
+  "kvcoder.ui.changes.title": "التغييرات",
+  "kvcoder.ui.changes.toggle": "التغييرات ({count})",
+  "kvcoder.ui.changes.loading": "جارٍ قراءة التغييرات…",
+  "kvcoder.ui.changes.note": "الملفات التي غيّرتها هذه المحادثة، مقارنةً بآخر حفظ أو بالنسخة التي احتفظت بها. تغييرات أسطر الطرفية لا تظهر هنا.",
+  "kvcoder.ui.changes.noGit": "تعذّر تشغيل Git، فتظهر التغييرات بلا فروقها. تغييرات أسطر الطرفية لا تظهر هنا.",
+  "kvcoder.ui.changes.commit": "احفظ في Git",
+  "kvcoder.ui.changes.commitMessage": "احفظ هذه التغييرات في Git.",
+  "kvcoder.ui.changes.undo": "تراجع",
+  "kvcoder.ui.changes.none": "لم يبقَ أي تغيير.",
+  "kvcoder.ui.changes.state.changed": "مُعدَّل",
+  "kvcoder.ui.changes.state.created": "جديد",
+  "kvcoder.ui.changes.state.deleted": "محذوف",
   "kvcoder.ui.chats": "المحادثات",
   "kvcoder.ui.today": "اليوم",
   "kvcoder.ui.earlier": "الأقدم",
+  "kvcoder.ui.notify.title": "محادثة تحتاجك",
+  "kvcoder.ui.notify.ask": "احصل على تنبيه عندما تحتاجك محادثة وkvman في الخلفية.",
+  "kvcoder.ui.notify.on": "تفعيل",
+  "kvcoder.ui.notify.later": "ليس الآن",
   "kvcoder.ui.needsYou": "بانتظار ردّك",
   "kvcoder.ui.status.idle": "جاهزة",
   "kvcoder.ui.status.running": "قيد العمل…",
@@ -73,6 +91,11 @@
   "kvcoder.ui.no": "لا",
   "kvcoder.ui.allowCommands": "هل تسمح بتنفيذ هذه الأوامر؟ ({count})",
   "kvcoder.ui.allow": "سماح",
+  "kvcoder.ui.approval.denyWhy": "ارفض واذكر السبب…",
+  "kvcoder.ui.approval.reason": "ماذا يفعل الوكيل بدلًا من ذلك؟",
+  "kvcoder.ui.approval.alwaysLine": "اسمح دائمًا بالأسطر التي تبدأ بـ",
+  "kvcoder.ui.approval.always": "اسمح دائمًا",
+  "kvcoder.ui.approval.alwaysFiles": "اسمح دائمًا بتغيير الملفات هنا",
   "kvcoder.ui.deny": "رفض",
   "kvcoder.ui.allowAll": "سماح للكل",
   "kvcoder.ui.denyAll": "رفض الكل",
@@ -141,12 +164,16 @@
   "kvcoder.ui.reach.session": "هذه المحادثة",
   "kvcoder.ui.leftOut": "مستبعد: يتجاوز 64 كيلوبايت",
   "kvcoder.ui.model": "النموذج",
+  "kvcoder.ui.decideForMe": "قرّر عني",
+  "kvcoder.ui.decideForMeHint": "يتخذ الوكيل كل قرار بنفسه، بالخيار الذي يوصي به، ولا يسألك أسئلة في هذه المحادثة. طلبات الموافقة تبقى كما هي.",
   "kvcoder.ui.thinking": "التفكير",
   "kvcoder.ui.thinkingLevels.off": "بدون",
   "kvcoder.ui.thinkingLevels.minimal": "أدنى",
   "kvcoder.ui.thinkingLevels.low": "منخفض",
   "kvcoder.ui.thinkingLevels.medium": "متوسط",
   "kvcoder.ui.thinkingLevels.high": "مرتفع",
+  "kvcoder.ui.thinkingLevels.xhigh": "مرتفع جدًا",
+  "kvcoder.ui.thinkingLevels.max": "أقصى",
   "kvcoder.ui.menu": "المزيد",
   "kvcoder.ui.rename": "إعادة التسمية",
   "kvcoder.ui.fork": "نسخ إلى محادثة جديدة",
@@ -180,7 +207,11 @@
   "kvcoder.shell.run.description": "ينفّذ سطرًا واحدًا في الطرفية الفعلية، داخل مجلد مساحة العمل.",
   "kvcoder.binary.run.description": "يشغّل البرنامج بالوسائط المعطاة في الطرفية الفعلية، داخل مجلد مساحة العمل.",
   "kvcoder.fs.file.get.description": "يقرأ أسطرًا من ملف نصي.",
+  "kvcoder.fs.files.get.description": "يقرأ عدة ملفات نصية في استدعاء واحد، بالترتيب، كلًّا كما يقرؤه read.",
+  "kvcoder.change.list.description": "يسرد الملفات التي غيّرتها محادثة عبر fs، الأحدث أولًا، مع فرق كل منها.",
+  "kvcoder.change.undo.description": "يتراجع عن آخر تغيير أجرته المحادثة على ملف، كما يفعل fs undo؛ للشخص.",
   "kvcoder.fs.entry.list.description": "يسرد ملفات ومجلدات مجلد واحد.",
+  "kvcoder.fs.path.list.description": "يجد الملفات التي يطابق مسارها نمطًا، داخل مجلد، الأحدث أولًا.",
   "kvcoder.fs.text.search.description": "يجد الأسطر التي تطابق تعبيرًا نمطيًا، في ملف أو داخل مجلد.",
   "kvcoder.fs.write.description": "ينشئ ملفًا مع مجلداته الأصلية، أو يستبدل محتوى الملف.",
   "kvcoder.fs.edit.description": "يستبدل مقاطع نصية محددة في ملف موجود؛ وإذا فشل أحد الاستبدالات لا يُكتب شيء.",
@@ -190,15 +221,17 @@
   "kvcoder.artifact.write.description": "ينشئ مخرجًا، أو يستبدل عنوانه وصيغته ومحتواه.",
   "kvcoder.artifact.edit.description": "يستبدل مقاطع نصية محددة في مخرج موجود؛ وإذا فشل أحد الاستبدالات لا يتغير شيء.",
   "kvcoder.artifact.content.get.description": "يقرأ مخرجًا مع محتواه.",
-  "kvcoder.map.set.description": "ينشئ خريطة التنفيذ أو يستبدلها، والخطوة التي يبقى معرّفها تحتفظ بما وصلت إليه.",
+  "kvcoder.map.set.description": "ينشئ هيكل خريطة التنفيذ أو يستبدله، والخطوة التي يبقى معرّفها تحتفظ بتفاصيلها وبما وصلت إليه.",
+  "kvcoder.map.step.details.set.description": "يكتب تفاصيل خطوة واحدة من الخريطة.",
   "kvcoder.map.step.update.description": "يغيّر حالة خطوة أو أكثر من خطوات الخريطة.",
   "kvcoder.map.note.add.description": "يضيف ملاحظة إلى قائمة «مؤجَّل لوقت لاحق» في الخريطة.",
-  "kvcoder.map.state.get.description": "يقرأ خريطة التنفيذ كاملة.",
+  "kvcoder.map.state.get.description": "يقرأ خريطة التنفيذ دون تفاصيل خطواتها، أو خطوة واحدة كاملة.",
   "kvcoder.background.list.description": "يسرد أحدث 50 عملية في خلفية هذه المحادثة، الأحدث أولًا، كلٌّ بمعرّفها ونوعها وعنوانها وحالتها.",
   "kvcoder.background.output.get.description": "يعطي حالة عملية واحدة في الخلفية ومخرجاتها (آخر أسطر العملية، أو إجابة الوكيل المساعد، أو ما أعاده تشغيل عامل برنامج).",
   "kvcoder.background.wait.description": "ينتظر حتى تنتهي عملية في الخلفية أو ينقضي الوقت، ثم يعطي حالتها ومخرجاتها كما يفعل output.",
   "kvcoder.background.stop.description": "يوقف عملية في الخلفية أو تشغيل برنامج مساعد، أو يلغي وكيلًا فرعيًا في الخلفية.",
   "kvcoder.mcp.tool.describe.description": "يسرد أدوات خادم MCP، أو يعطي وصف أداة واحدة ومُدخلاتها.",
+  "kvcoder.web.page.get.description": "يقرأ صفحة على الويب بصيغة Markdown أو نصًا.",
   "kvcoder.mcp.tool.call.description": "يستدعي أداة من خادم MCP ويعيد نصّها.",
   "kvcoder.mcp.steps.run.description": "يستدعي عدة أدوات من خادم MCP على اتصال واحد بالترتيب، فيحتفظ الخادم بحالته بينها، ويتوقف عند أول أداة تُبلغ عن خطأ.",
   "kvcoder.mcp.server.check.description": "يتصل بخادم MCP ويخبر هل هو جاهز، أم يحتاج إلى تسجيل دخول، أم فشل.",
@@ -208,6 +241,7 @@
   "kvcoder.ask.choice.check.description": "يطلب من المستخدم الاختيار من بين خيارات وينتظر الإجابة.",
   "kvcoder.ask.confirm.check.description": "يسأل المستخدم سؤال نعم أو لا وينتظر الإجابة.",
   "kvcoder.delegate.check.description": "يشغّل مساعدًا على مهمة؛ وعدة تشغيلات في رد واحد تعمل بالتوازي.",
+  "kvcoder.delegate.continue.check.description": "يرسل متابعة إلى مساعد في هذه المحادثة أنهى عمله، مثل مساعد عاد متوقفًا أو بأسئلة: فيكمل بسجله نفسه.",
   "kvcoder.delegate.worker.check.description": "يتحقق من أن برنامج المساعد مثبت؛ والوكيل المساعد جاهز دائمًا.",
   "kvcoder.delegate.worker.run.description": "يشغّل برنامج المساعد على مهمته، ويعطي المحادثة إجابته.",
   "kvcoder.connector.help.get.description": "يعيد مساعدة موصّل: أوامره، أو حمولة أمر واحد ونتيجته وأمثلته.",
@@ -237,8 +271,26 @@
   "kvcoder.thinking.description": "مقدار تفكير النموذج في المحادثة الجديدة.",
   "kvcoder.maxSteps.title": "الخطوات في كل جولة",
   "kvcoder.maxSteps.description": "أقصى عدد من الخطوات تنفّذه الجولة قبل أن تتوقف. اتركه فارغًا لتبقى الجولة بلا حدّ.",
+  "kvcoder.preferences.title": "تفضيلاتك",
+  "kvcoder.preferences.description": "ما يجب أن تعرفه كل محادثة عن طريقتك في العمل، مثل لغة تطبيقاتك أو ألا يسألك الوكيل. يقرؤها الوكيل في كل محادثة.",
+  "kvcoder.config.preferences.placeholder": "ابنِ التطبيقات بالعربية أولًا.\nلا تطلب مني الاختيار: اختر ما توصي به.",
+  "kvcoder.config.preferences.save": "حفظ",
+  "kvcoder.ui.remember.this": "تذكّر هذا",
+  "kvcoder.ui.remember.question": "أتضيف هذا إلى تفضيلاتك؟ كل محادثة تقرؤها.",
+  "kvcoder.ui.remember.add": "أضف",
+  "kvcoder.ui.remember.added": "أُضيف إلى تفضيلاتك.",
+  "kvcoder.check.title": "فحص بعد التغييرات",
+  "kvcoder.check.description": "سطر يشغّله kvman بعد أن يغيّر الوكيل ملفات، مثل فحص الأنواع في المشروع؛ تُضاف نتيجته ومخرجاته إلى التغيير ليرى الوكيل الخطأ فورًا. فارغ لعدم التشغيل.",
+  "kvcoder.fallbackModel.title": "نموذج بديل",
+  "kvcoder.fallbackModel.description": "النموذج الذي تنتقل إليه المحادثة عندما يبلغ نموذجها حد الاستخدام، أو حد الطلبات بعد كل المحاولات. فارغ لعدم الانتقال.",
   "kvcoder.approval.title": "الموافقة",
   "kvcoder.approval.description": "متى يطلب الوكيل موافقتك قبل تنفيذ أمر أو تعديل ملف أو أي شيء آخر يحتاج إلى إذنك.",
+  "kvcoder.approval.allowed.title": "مسموح دائمًا",
+  "kvcoder.approval.allowed.description": "أوامر وتغييرات تعمل دون سؤالك: سطر يبدأ كل أمر فيه بأحد هذه البدايات، أو تغيير ملف في هذا المجلد.",
+  "kvcoder.config.approval.rules.line": "مسموح دائمًا: {prefix} …",
+  "kvcoder.config.approval.rules.files": "مسموح دائمًا: تغيير الملفات",
+  "kvcoder.config.approval.rules.none": "لا توجد أوامر مسموحة دائمًا.",
+  "kvcoder.config.approval.rules.remove": "إزالة",
   "kvcoder.config.approval.never.title": "عدم السؤال قبل أي عملية؟",
   "kvcoder.config.approval.never.text": "سينفّذ الوكيل الأوامر ويعدّل الملفات ويغيّر kvman نفسه ويشغّل برامج المساعدين دون أن يسألك. وما يقرؤه قد يوجّهه.",
   "kvcoder.config.approval.never.confirm": "أوقف السؤال",
@@ -261,6 +313,7 @@
   "kvcoder.artifact.list.description": "يسرد مخرجات المحادثة، الأحدث تعديلًا أولًا.",
   "kvcoder.artifact.get.description": "يعيد مخرجًا واحدًا من المحادثة مع محتواه.",
   "kvcoder.map.get.description": "يعطي خريطة التنفيذ لمحادثة، أو null إن لم تكن لها خريطة.",
+  "kvcoder.ui.backgroundDecision": "مساعد يعمل في الخلفية ينتظر قرارك.",
   "kvcoder.ui.jobs.title": "المهام الخلفية",
   "kvcoder.ui.jobs.running": "{count} قيد التشغيل",
   "kvcoder.ui.jobs.minutes": "{minutes} د {seconds} ث",
@@ -268,6 +321,7 @@
   "kvcoder.ui.jobs.stop": "إيقاف",
   "kvcoder.ui.jobs.noOutput": "لا يوجد ناتج بعد.",
   "kvcoder.ui.jobs.status.running": "قيد التشغيل",
+  "kvcoder.ui.jobs.status.waiting": "بانتظار ردّك",
   "kvcoder.ui.jobs.status.succeeded": "اكتملت",
   "kvcoder.ui.jobs.status.failed": "فشلت",
   "kvcoder.ui.jobs.status.cancelled": "أُوقفت",
@@ -275,7 +329,8 @@
   "kvcoder.ui.jobs.inBackground": "يعمل في الخلفية",
   "kvcoder.ui.jobs.background": "في الخلفية",
   "kvcoder.notices.STEP_FAILED_REASON": "توقفت الجولة: {error} {reason}",
-  "kvcoder.ui.activity.retrying": "جارٍ إعادة المحاولة… ({attempt} من {of})",
+  "kvcoder.ui.activity.retryingRateLimited": "إعادة المحاولة بعد {seconds} ث: المزوّد يحدّ من الطلبات ({attempt} من {of})",
+  "kvcoder.ui.activity.retryingUnavailable": "إعادة المحاولة بعد {seconds} ث: المزوّد لم يُجب ({attempt} من {of})",
   "kvcoder.ui.artifacts.title": "المخرجات",
   "kvcoder.ui.artifacts.open": "فتح",
   "kvcoder.ui.artifacts.close": "إغلاق",
@@ -293,7 +348,7 @@
   "kvcoder.ui.map.status.failed": "فشلت",
   "kvcoder.ui.map.status.skipped": "تم تخطيها",
   "kvcoder.ui.map.step": "الخطوة",
-  "kvcoder.ui.map.description": "الوصف",
+  "kvcoder.ui.map.details": "التفاصيل",
   "kvcoder.ui.map.after": "بعد",
   "kvcoder.ui.map.uses": "تستخدم",
   "kvcoder.ui.map.check": "التحقق",
@@ -301,6 +356,8 @@
   "kvcoder.ui.map.note": "ملاحظة",
   "kvcoder.ui.map.noted": "مؤجَّل لوقت لاحق ({count})",
   "kvcoder.ui.map.remaining": "{count} من خطوات خريطة التنفيذ لم تُنجز.",
+  "kvcoder.ui.map.continue": "تابع",
+  "kvcoder.ui.map.continueMessage": "تابع.",
   "kvcoder.ui.map.show": "عرض الخريطة",
   "kvcoder.ui.map.close": "إغلاق",
   "kvcoder.ui.artifacts.frameLabel": "معاينة {title}",
@@ -339,6 +396,7 @@
   "kvcoder.config.connector.background": "يسرد ما يعمل في الخلفية ويقرأ ناتجه ويوقفه.",
   "kvcoder.config.connector.ask": "يطرح عليك سؤالًا وينتظر إجابتك.",
   "kvcoder.config.connector.delegate": "يسند جزءًا من المهمة إلى مساعد: وكيل آخر له تعليماته.",
+  "kvcoder.config.connector.web": "يقرأ صفحات على الويب، مثل التوثيق الحالي، ويسألك قبل أول صفحة من كل موقع.",
   "kvcoder.config.connector.mcp": "يستخدم أدوات خوادم MCP التي تضيفها.",
   "kvcoder.config.connectors.use": "استخدام {name}",
   "kvcoder.config.connectors.configure": "إعداد {name}",
@@ -491,6 +549,7 @@
   "kvcoder.config.model.reset.workspace": "استخدام قيمة كل مساحات العمل",
   "kvcoder.config.model.ownValue": "لمساحة العمل {name} قيمة خاصة بها. انتقل إلى {name} لتغييرها.",
   "kvcoder.ui.milliseconds": "{count} مللي ث",
+  "kvcoder.ui.hoursMinutes": "{hours} س {minutes} د",
   "kvcoder.ui.minutesSeconds": "{minutes} د {seconds} ث",
   "kvcoder.ui.callFailed": "فشل",
   "kvcoder.ui.callParts": "كُتب في {written} · نُفّذ في {ran}",
@@ -499,6 +558,18 @@
   "kvcoder.ui.call.write": "كتابة",
   "kvcoder.ui.call.read": "قراءة",
   "kvcoder.ui.call.list": "عرض",
+  "kvcoder.ui.fold.read": "قراءة {count}",
+  "kvcoder.ui.fold.searched": "بحث {count}",
+  "kvcoder.ui.fold.changed": "تغيير {count}",
+  "kvcoder.ui.fold.ran": "تشغيل {count}",
+  "kvcoder.ui.fold.other": "أخرى {count}",
+  "kvcoder.ui.fold.failed": "فشل {count}",
+  "kvcoder.ui.call.fetch": "جلب",
+  "kvcoder.ui.call.find": "إيجاد",
+  "kvcoder.ui.call.files": "{count} ملف",
+  "kvcoder.ui.call.fileNotRead": "لم يُقرأ: استهلكت الملفات التي قبله حدّ هذا الاستدعاء (30 KB).",
+  "kvcoder.ui.call.fileUnchanged": "لم يتغيّر منذ قراءة سابقة في هذه المحادثة.",
+  "kvcoder.ui.call.filesFirst": "أول {count} ملف",
   "kvcoder.ui.call.search": "بحث",
   "kvcoder.ui.call.tools": "الأدوات",
   "kvcoder.ui.call.delegate": "تفويض",
@@ -506,16 +577,21 @@
   "kvcoder.ui.call.output": "ناتج",
   "kvcoder.ui.call.wait": "انتظار",
   "kvcoder.ui.call.mapSet": "خريطة",
+  "kvcoder.ui.call.mapDetail": "تفاصيل خطوة",
   "kvcoder.ui.call.mapUpdate": "خطوة في الخريطة",
   "kvcoder.ui.call.mapNote": "مؤجَّل لوقت لاحق",
   "kvcoder.ui.call.mapGet": "قراءة الخريطة",
   "kvcoder.ui.call.stop": "إيقاف",
   "kvcoder.ui.call.readArtifact": "قراءة المُخرَج",
+  "kvcoder.ui.call.writeArtifact": "كتابة المُخرَج",
+  "kvcoder.ui.call.editArtifact": "تعديل المُخرَج",
+  "kvcoder.ui.call.help": "مساعدة",
   "kvcoder.ui.call.created": "أُنشئ · {size}",
   "kvcoder.ui.call.replaced": "استُبدل · {size}",
   "kvcoder.ui.call.lines": "الأسطر {from}–{to} من {total}",
   "kvcoder.ui.call.entries": "{count} عنصر",
   "kvcoder.ui.call.entriesFirst": "أول {count} عنصر",
+  "kvcoder.ui.call.matchCount": "النتائج: {count}",
   "kvcoder.ui.call.matches": "{matches} نتيجة في {files} ملف",
   "kvcoder.ui.call.matchesFirst": "أول {matches} نتيجة في {files} ملف",
   "kvcoder.ui.call.toolCount": "{count} أداة",
@@ -524,7 +600,7 @@
   "kvcoder.ui.call.kilobytes": "{count} ك.ب",
   "kvcoder.ui.call.megabytes": "{count} م.ب",
   "kvcoder.ui.call.risky": "خطِر",
-  "kvcoder.ui.call.replacements": "{count} استبدال · من السطر {line}",
+  "kvcoder.ui.call.replacements": "الاستبدالات: {count} · من السطر {line}",
   "kvcoder.ui.call.showAll": "عرض كل الأسطر ({count})",
   "kvcoder.ui.call.showFewer": "عرض أقل",
   "kvcoder.ui.call.error": "الخطأ",