@palai/cloud

Palai Cloud'un kontrol düzlemi istemcisi: proje aç, anahtar üret ve iptal et, kullanımı kaldığın yerden oku. Sıfır çalışma zamanı bağımlılığı.

Bu paket ajan koşturmaz. Plane'i sürmek — oturum açmak, ajan çalıştırmak, akış okumak — sk_… proje anahtarıyla @palai/sdk'nin işi. Bu paket onları açar ve sayar.

‼️ Org anahtarı bir sırdır, tarayıcıya inmez

pak_… 192 bit rastgelelik taşır ve proje anahtarı basabilir. Bir tarayıcı paketine konursa her ziyaretçi organizasyon adına anahtar üretebilir. Bu istemci sizin sunucunuzda koşar.

Kurulum

npm i @palai/cloud

import { createCloud } from "@palai/cloud";

const cloud = createCloud({
  apiKey: process.env.PALAI_CLOUD_ORG_KEY!,   // pak_…
});

Yapılandırılacak tek şey anahtardır. Adres yok: Palai Cloud barındırılan tek bir üründür ve bu istemci nereye bağlanacağını bilir (CLOUD_BASE_URL diye dışa açık, ama bir giriş değil).

Organizasyonun agent'ları

Bir kez tanımla, organizasyonun her projesine insin — ve yarın açtığın projeye de.

const a = await cloud.agents.define({
  name: "reviewer",
  instructions: "Be terse.",
  tools: ["palai.workspace.grep"],
});
// a.projections -> her proje için { palaiProjectId, state, detail }

state üç değerden biri ve ikisi aynı şey değil:

| | | |---|---| | projected | o projede duruyor | | refused | o projede aynı adda, Cloud'un yaratmadığı bir agent var — müşterinin kendi agent'ı ezilmez, yeniden denenmez | | failed | ulaşılamadı; bir sonraki süpürmede yeniden denenir |

Palai'de "organizasyonun agent'ı" diye bir şey yok ve olmayacak (MASTER-SPEC §39.1: proje üstü tenancy Palai'nin değil, onu işleten katmanın işi). Cloud tanımı kendi tutuyor ve her projeye sıradan bir proje-kapsamlı agent olarak yansıtıyor — bu yüzden müşterin @palai/sdk ile plane'e doğrudan bağlandığında yalnız kendi agent'larını görüyor, komşusununkini değil.

Aynı adı ikinci kez tanımlamak ConflictError (409) döner.

Bir müşteri açmak

const p = await cloud.projects.create({ name: "musteri-42" });
// p.palaiProjectId — kendi kullanıcınızın yanına yazın
// p.apiKey        — BİR KEZ gösterilir, bir daha asla. Müşterinize verin.
// p.keyId         — sır değil; o anahtarı iptal etmenin TEK yolu, saklayın.

Sonradan ikinci bir anahtar:

const k = await cloud.projects.keys.create(p.palaiProjectId);
await cloud.projects.keys.revoke(p.palaiProjectId, k.keyId);   // sonraki istekte geçerli

İptalin geri dönüşü yoktur — Palai un-revoke sunmuyor.

Kredi düşümü

Ledger append-only ve her satır bir metrelenmiş olay. Toplam bir iddia, ledger kanıttır.

let cursor = await db.lastCursor(projectId);

for await (const row of cloud.projects.usage.ledger(projectId, { after: cursor })) {
  await db.debit(row);            // machine.minutes, model.input_tokens, …
}

Cursor'ı kendiniz saklamak isterseniz tek sayfa da alabilirsiniz:

const page = await cloud.projects.usage.ledgerPage(projectId, { after: cursor, limit: 100 });
await db.saveCursor(projectId, page.next_cursor);

next_cursor opaktır: Palai onu kiracı başına imzalar. Ayrıştırmayın, yeniden kurmayın — saklayın ve geri verin.

Anlık toplamlar

await cloud.projects.usage.summary(projectId);              // dört sayaç
await cloud.projects.usage.series(projectId, { bucket: "day" });
await cloud.balance.get();                                   // kredi ORGANIZASYONUN

Hatalar

Durum koduna göre tiplidir ve sunucunun cümlesini olduğu gibi taşır.

import { NotFoundError, UnauthorizedError } from "@palai/cloud";

try {
  await cloud.projects.usage.summary("prj_baskasinin");
} catch (e) {
  if (e instanceof NotFoundError) { /* bu organizasyonda böyle bir proje yok */ }
  if (e instanceof UnauthorizedError) { /* org anahtarı yok, bozuk ya da iptal */ }
  // e.requestId — sunucu loglarında aynı kimlik duruyor
}

Bilinen sınırlar

• Proje silinemez. Palai'nin yönlendiricisinde silme ucu yok; bu paket olmayan bir yeteneği close() diye sunmaz.
• Harcama kırılımı proje düzeyinde. Anahtar başına harcama yok: usage_ledger'da api_key_id sütunu bulunmuyor.