Riferimento API Dell’SDK

Il pacchetto esporta bridge tipizzati e lazy per le app integrate, un client connect() per i processi locali esterni, tipi condivisi per richieste e risultati e funzioni di validazione.

Namespace Integrati

Importa questi namespace nel codice browser che Kucedr apre come app:

import { agent, app, coder, isKucedr, models, terminal, win } from '@kucedr/sdk';

Namespace	Scopo	Disponibilità
`app`	Tema, lingua, impostazioni, eventi e spazio dati isolato dell’app	Integrato; la maggior parte delle impostazioni non legate allo storage è disponibile anche da remoto.
`agent`	API dell’agente e del workspace	Integrato, con operazioni sensibili limitate dall’host. Il client remoto espone solo le operazioni del workspace.
`models`	API dei modelli configurati, inclusa generazione e modifica di immagini	Solo integrato. Le credenziali del provider non vengono esposte all’app.
`win`	Menu contestuali nativi, stato della finestra e controlli della barra del titolo gestiti dall’host	Solo integrato.
`coder`	Progetti, sessioni persistenti, esecuzioni Agent e Shell, impostazioni, autenticazione, streaming e annullamento	Solo integrato e riservato all’app Coder registrata.
`terminal`	Creazione di pseudoterminali con proprietario, input, ridimensionamento, output ed eventi di uscita	Solo integrato e limitato alle finestre Kucedr autorizzate e all’app Coder.

Il bridge è lazy: importare un namespace è sicuro, ma chiamarlo fuori da Kucedr genera un errore. Usa isKucedr() prima della prima chiamata all’host.

Spazio Dati Dell’App

Le app integrate ricevono automaticamente un proprio namespace di storage. Non passano e non scelgono mai un ID app.

import { app, isExtensionStoreValue } from '@kucedr/sdk';

await app.setExtensionStoreValue('preferences', {
  compact: true,
  accent: 'violet',
});

const value = await app.getExtensionStoreValue('preferences');

if (!isExtensionStoreValue(value)) {
  throw new Error('Valore salvato non supportato');
}

I valori possono contenere numeri finiti, stringhe, booleani, null, array densi e oggetti semplici. Non salvare segreti: i valori sono JSON in chiaro. Valori e file restano disponibili quando un’app viene rimossa, quindi reinstallare lo stesso ID ripristina lo stato.

I metodi per i file usano Uint8Array e percorsi relativi alla directory isolata dell’app:

const data = new TextEncoder().encode('Contenuto della bozza');
await app.writeExtensionStoreFile('drafts/first.txt', data);

const saved = await app.readExtensionStoreFile('drafts/first.txt');
console.log(new TextDecoder().decode(saved));

await app.deleteExtensionStoreFile('drafts/first.txt');

I percorsi devono usare slash /. Percorsi assoluti, vuoti o con segmenti . e .. vengono rifiutati. Eliminare un valore o file mancante è sicuro; leggere un file mancante genera un errore.

Temi E Controlli Della Finestra

Usa il tema risolto da Kucedr invece di presumere che la modalità salvata system sia chiara o scura:

const stopTheme = app.onThemeModeChanged((theme) => {
  document.documentElement.dataset.theme = theme.isDark ? 'dark' : 'light';
});

win.setTitlebarOptions({
  title: 'Dashboard del progetto',
  leftButtons: [
    {
      id: 'toggle-sidebar',
      label: 'Mostra o nascondi la barra laterale',
      icon: 'panel-left',
      expanded: true,
    },
  ],
  sidebarOpen: true,
  sidebarWidth: 240,
});

const stopButtons = win.onTitlebarButtonClick((buttonId) => {
  if (buttonId === 'toggle-sidebar') {
    // Aggiorna lo stato dell’app, poi invia le nuove opzioni della barra del titolo.
  }
});

// Richiama queste funzioni durante il cleanup.
stopTheme();
stopButtons();

Le icone della barra del titolo devono provenire da EXTENSION_TITLEBAR_BUTTON_ICONS; non è possibile inviare markup arbitrario oltre il confine della finestra. Passa null a win.setTitlebarOptions() per ripristinare il titolo del manifest e rimuovere i controlli forniti dall’app.

Generazione Di Immagini

models.image.createImage() usa il provider e il modello immagini configurati in Kucedr:

const generated = await models.image.createImage({
  prompt: 'A calm, modern reading room',
});

const revised = await models.image.createImage({
  prompt: 'Replace the armchair with a leather lounge chair.',
  source: {
    base64: generated.base64,
    mimeType: 'image/png',
  },
});

Le immagini sorgente accettano dati JPEG, PNG o WebP fino a 18 MiB. Usa il MIME type restituito quando trasformi i byte del risultato in un data URL o in un file.

Client Esterno

Kucedr salva un bearer token in <userData>/sdk-token. Su macOS il percorso predefinito è ~/Library/Application Support/Kucedr/sdk-token. Mantieni privato il token e leggilo durante l’esecuzione invece di copiarlo nel codice sorgente.

import { readFileSync } from 'node:fs';
import { connect } from '@kucedr/sdk';

const kucedr = connect({
  token: readFileSync(
    '/Users/me/Library/Application Support/Kucedr/sdk-token',
    'utf8',
  ).trim(),
});

await kucedr.ping();

const files = await kucedr.agent.listWorkspaceFiles();
const userProfile = await kucedr.agent.readWorkspaceFile('USER.md');

const stop = kucedr.agent.onWorkspaceChanged((event) => {
  console.log(event.type, event.path);
});

// Durante l’arresto:
stop();
kucedr.close();

connect() usa per impostazione predefinita http://127.0.0.1:8765 e accetta un url o un’implementazione fetch alternativi. I callback degli eventi aprono una connessione Server-Sent Events al primo utilizzo. Chiama close() durante l’arresto per chiudere lo stream.

Sicurezza A Runtime

Tratta il token dell’SDK come una password: qualsiasi processo che lo possiede può chiamare l’API locale esposta.
Non inserire credenziali nello spazio dati dell’app perché viene salvato in chiaro.
Prevedi che l’host rifiuti le API che l’app corrente non è autorizzata a usare.
La directory di lavoro di un progetto non è una sandbox del sistema operativo. Le operazioni di coding e terminale vengono eseguite con i permessi dell’utente desktop.
Le app ricevono eventi degli strumenti dell’agente oscurati e non ricevono le credenziali dei provider.