# Dil bağımsız yerel process worker

`tm worker run --process` operatörün seçtiği güvenilir programı iş başına ayrı process olarak başlatır. Python/Go/Rust gibi runtime'lar TypeScript SDK yazmadan kalıcı inbox katmanını kullanabilir. Sunucu uzaktan program çalıştırmaz; executable/argv mesajdan alınmaz. Bir ürün CLI'sinin stdout'u bu ABI ile aynı değildir; adapter programı sözleşmeyi uygulamalıdır.

## Gerçek Python örneği

Python 3 interpreter'ı gerekir; sunucunun/diğer worker'ların zorunlu bağımlılığı değildir. `/usr/bin/python3` test edilen Linux yoludur; başka sistemde kendi mutlak interpreter yolunuzu kullanın. Repository kökünde:

```bash
node --input-type=module -e '
import {writeFile} from "node:fs/promises";
import {resolve} from "node:path";
await writeFile("python-worker.json", JSON.stringify({
  command: "/usr/bin/python3",
  args: [resolve("examples/agents/process-agent.py")],
  env: []
}, null, 2));
'
tm --profile alici --json worker run python-worker --from now \
  --process ./python-worker.json --handler-timeout 20000
# Arkadaşlığı kabul edilmiş gönderenin ayrı terminalinde:
tm --profile gonderen --compact send ALICI_NUMARASI 'istanbul güzel 👋' --ask
```

Python örneği gerçek mesajı Türkçe büyük harfe çevirir; aynı API/DB'ye gerçek response kaydedilir. LLM, eval, shell veya dosya/URL araçları kullanmaz. `--builtin`, `--handler`, `--process` seçeneklerinden tam bir tanesi gerekir. `--policy` aynı sender/oda/saat/bütçe sınırlarını uygular. Restart aynı runtime/policy/from ile checkpoint'i korur.

## Process yapılandırması

Strict JSON; ek alanlar, NUL ve geçersiz env isimleri reddedilir:

```json
{
  "command": "/MUTLAK/PROGRAM/YOLU",
  "args": ["/MUTLAK/ADAPTER/YOLU.py"],
  "cwd": "/MUTLAK/CALISMA/DIZINI",
  "env": ["MY_PROVIDER_API_KEY"]
}
```

`args`/`env` belirtilmezse boş liste; `cwd` belirtilmezse worker'ın çalışma dizini. `command` ve varsa `cwd` mutlak yol. Argümanlar shell expansion olmadan argv olarak aktarılır. En fazla 32 argüman/32 env ismi; argüman başına 4096 karakter, toplam argv 32768 UTF-8 byte; config dosyası 64 KiB. Secret değerleri config'e konmaz.

Default child env yalnızca mevcut `PATH`, `LANG`, `LC_ALL`, `TZ`, `TMPDIR` değerleridir. `env` listesi operatörün mevcut süreç ortamından açıkça eklediği isimlerdir. Varsayılan HOME, model anahtarı, Node/Python startup hook veya bütün parent env mirası yoktur. `TM_TOKEN`, `TM_SERVER`, `TM_PROFILE`, `TM_CONFIG_DIR`, `DATABASE_URL`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` açık listede bile reddedilir. İletişim authority'si host worker'da kalır. Provider anahtarı kullanacaksanız ayrıca kendi runtime güvenliğini uygulayın; örnek provider çağırmaz.

Program OS sandbox değildir: güvenilir operatör kodu aynı kullanıcının dosyaları/ağına erişebilir. Farklı agentları farklı OS hesapları veya erişimi kısıtlanmış container'larla ayırın. Env kısıtı disk credential'larını tek başına korumaz. Self-detach/setsid ile gruptan kaçan programlara karşı sandbox garantisi yoktur. Otomatik indirme, mesajdan executable seçme veya uzaktan shell motoru yoktur.

Bu ABI iş başına process açar; zaten sürekli çalışan bir asistan için HTTP/SDK bağlantısını programın içinde tutmak process başlatma maliyetini taşımadan haberleşmesini sağlar. Worker'ın kalıcı HTTP/WS bağlantıları model çağırmaz. Process yük ölçümü kuyruk ve interpreter başlangıcı dahil test raporunda (repo: `docs/TEST-RESULTS.md`) verilmiştir.

Process group cleanup POSIX'tir. Windows doğrudan process handler `process_handler_requires_posix` ile reddedilir; WSL/Linux veya SDK/HTTP runtime kullanın. macOS'ta bu özellik çalıştırılmadı; Windows Job Object uygulaması/testi yoktur. [Node child-process API](https://nodejs.org/download/release/v22.22.1/docs/api/child_process.html#optionsdetached).

## Request/response

Aşağıdaki JSON örnekleri okunabilirlik için biçimlendirilmiştir; wire üzerinden her request/response tek satır halinde gönderilir.

[Üretilmiş JSON Schema](process.schema.json) config/request/response şemalarını birlikte içerir. Parent ayrıca byte, absolute path, env denylist ve job korelasyonu kurallarını denetler. Bu yerel Relayger process ABI sözleşmesidir; MCP/ACP/A2A değildir.

STDIN: tek UTF-8 JSON satırı ve EOF; en fazla 131072 byte, newline dahil. Token/leaseOwner verilmez. `jobKey` dış side effect için sabit idempotency anahtarıdır, retry'da aynı kalır; `attempt` artar. Mesaj mevcut compact sözleşmesinden türetilir; sıra decimal string kalır:

```json
{
  "schemaVersion": 1,
  "jobKey": "00000000-0000-4000-8000-000000000001:00000000-0000-4000-8000-000000000002",
  "runtimeId": "00000000-0000-4000-8000-000000000001",
  "attempt": 1,
  "untrustedExternalData": true,
  "message": {
    "id": "00000000-0000-4000-8000-000000000002",
    "room": "00000000-0000-4000-8000-000000000003",
    "seq": "9007199254740993",
    "from": "1234567897",
    "type": "text",
    "body": { "text": "istanbul güzel" },
    "attention": { "kind": "question" }
  }
}
```

STDOUT: tam bir JSON satırı, isteğe bağlı LF/CRLF, en fazla 131072 byte; `schemaVersion:1`, aynı jobKey ve exit code 0 zorunlu. Banner/log/ikinci sonuç eklenmez. Metindeki newline JSON içinde escape edilir. Geçersiz UTF-8, yanlış iş, ek alan, boş reply, skip+reply/note veya non-zero exit reddedilir:

```json
{
  "schemaVersion": 1,
  "jobKey": "00000000-0000-4000-8000-000000000001:00000000-0000-4000-8000-000000000002",
  "result": {
    "reply": "İSTANBUL GÜZEL",
    "usage": { "modelCalls": 0, "inputTokens": 0, "outputTokens": 0 }
  }
}
```

`result` ortak `{reply?,skip?,note?,usage?}` handler sözleşmesi; reply 16000 UTF-8 byte. Kaynaklı not sınırları [runtime rehberinde](RUNTIMES.md). `{}` tamamlar fakat cevap üretmez; `{skip:true}` işi atlar. Usage yoksa bilinmeyen raporlanır; sıfır yalnızca gerçekten model çağrılmadığında kullanılır.

STDERR terminale/JSON'a aktarılmaz, depolanmaz, hata içine eklenmez; toplam 32768 byte üzeri işi başarısız kılar. Stdout da sınırda kesilir, sınırsız birikmez. Timeout/SIGINT/lease iptali process grubunu SIGKILL ile kapatır. Token revoke worker'ın bağlantısını kapatıp iptalini tetikler; karar anındaki sunucu yetkisi stale sonucu reddeder. Parent erken çıkarsa sıradan child'lar için grup yine kapatılır. Dış eylemler geri alınmaz. Varsayılan süre 20 saniye, worker üst sınırı 120 saniye; adapter doğrudan SDK çağrısında da 120 saniyelik üst süre uygular. Soru deadline'ı daha erken bitebilir.

## SDK

```typescript
import {TerminalMessage, runWorker, createProcessHandler} from '@terminal-message/sdk';
const client = await TerminalMessage.fromProfile({profile:'alici'});
const cancel = new AbortController();
process.once('SIGINT', () => cancel.abort());
try {
  await runWorker(client, {
    name:'python-worker', from:'now', signal:cancel.signal,
    handler:createProcessHandler({
      command:'/usr/bin/python3',
      args:['/MUTLAK/YOL/termchat/examples/agents/process-agent.py'],
    }),
  });
} finally { client.disconnect(); }
```

Worker kayıt/claim/heartbeat/finish ve atomik reply transaction'ını mevcut SDK üzerinden yapar. Process DB'ye veya message tokenına doğrudan erişmez. Restart, iptal ve eski lease fencing'i korunur. Model/araç işi tekrar çalışabilir; dış exactly-once garantisi yoktur. Provider/model kurulumu bu teslimatta eklenmedi.

## Doğrulama

`tests/process.test.ts` gerçek Python/Node process'leriyle korelasyon, Unicode, argv/env sınırları, stderr, oversize çıktı, invalid UTF-8, nonzero exit ve process group cancellation'ı denetler. `tests/process-integration.test.ts` gerçek PostgreSQL/API, iki insan sahibi, TypeScript coordinator ve ayrı CLI/Python worker ile insan → coordinator → Python → coordinator → insan akışını çalıştırır; offline soru, API/worker restart, tek kalıcı cevap, yetkisiz erişim ve revoke sonrası worker çıkışını denetler. Model API'si gerekmez. Çalıştırma kaydı (repo: `docs/TEST-RESULTS.md`).