Référence SDK / API

La façon dont vous communiquez avec la passerelle Crew dépend de l'endroit où votre code s'exécute. Cette page fait correspondre chaque surface à l'API appropriée.

Il n'existe aucun paquet npm de client de passerelle TypeScript publié. Les noms de méthodes kirocrew-client ci-dessous décrivent la surface canonique de l'API Gateway — les mêmes points de terminaison que tout client (y compris fetch brut) utilise.

Les pages d'interface du tableau de bord importent des hooks à portée de permission depuis @kirocrew/app-sdk, résolus à l'exécution via la carte d'importation de l'hôte :

import { useAppApi, useAppEvents } from '@kirocrew/app-sdk'

function MyPage() {
  const api = useAppApi()               // permission-scoped GET/POST/PUT/PATCH/DELETE
  useAppEvents('notification', (e) => console.log(e))
  // ...
}

useAppApi() retourne un client dont les méthodes (get, post, put, patch, del) appellent les points de terminaison de la Gateway listés ci-dessous, à portée de votre liste d'autorisations permissions.api. Les chemins hors portée lancent une erreur. L'hôte injecte l'authentification automatiquement.

Importez depuis @kirocrew/app-sdk/ui :

Card, CardTitle, Btn, SendBtn, Input, SearchInput, Badge, AimBadge, StatCard, Skeleton, ContentSkeleton, EmptyState, PageHeader, Toggle, InfoTip, SegmentedControl, MarkdownRenderer.

pip install kirocrew-client

Client asynchrone autonome utilisant aiohttp. Aucune dépendance au paquet principal Crew.

from kirocrew_client import CrewClient

async with CrewClient(app_name="my-app") as mc:
    ok = await mc.ping()
    slots = await mc.list_slots()
    task_id = await mc.dispatch_agent_async("my-agent", "Analyze ticket T-123")
    result = await mc.get_task_result(task_id)

CrewClient(
    base_url="",              # default: http://localhost:{KIROCREW_PORT or 5476}
    token="",                 # optional for localhost
    app_name="",              # enables app-scoped storage + auto-auth
    timeout=30,               # request timeout seconds
    max_retries=3,
    retry_base_delay=1.0,
    message_length_limit=40000,
    on_auth_expired=None,     # async callback returning new token
)

Lorsque app_name est défini et qu'aucune authentification explicite n'est fournie, le client lit automatiquement le secret de l'application depuis ~/.kiro/crew/apps/{name}/.app_secret et l'échange contre un jeton d'authentification à courte durée de vie via POST /api/apps/{name}/token.

Les noms de méthodes ci-dessous utilisent snake_case pour Python; les noms TypeScript sont indiqués pour la lisibilité. Les mêmes points de terminaison sont accessibles via fetch() brut depuis Node ou un navigateur.

Toutes les méthodes d'abonnement retournent une fonction de désabonnement.

Types d'événements (liste partielle) : chat_chunk, chat_done, chat_message, chat_error, tool_call, notification, slots, slot_title, dashboard, log, refresh, approval, subagent_done, task_update, task_complete, proactive_notification, app_reload, error.

Hooks dans la Gateway uniquement. Ces aides sont disponibles pour les points d'entrée backend.hooks.* qui s'exécutent à l'intérieur du processus de la Gateway. Les processus backend autonomes utilisant kirocrew-client ne reçoivent pas ce contexte.

Les hooks backend reçoivent deux aides sur leur contexte d'application :

Appelez ctx.scrub.outbound avant qu'une application journalise ou transmette du contenu généré par le modèle. ctx.audit.record est au mieux et s'utilise pour les décisions d'accès, les autorisations, les refus et les mutations que l'application doit reconstruire ultérieurement.

Déclarez les extensions d'interface à l'exécution sous contributes dans app.json :

L'hôte valide chaque déclaration et monte uniquement les applications activées. Consultez la référence du manifeste pour le schéma de champs complet et les limites.

Un serveur MCP avec interface routé via le stub de la Gateway hérite des couleurs, polices, rayons et ombres actifs du tableau de bord, et reçoit les changements de thème pendant qu'il est monté.

Contexte silencieux en arrière-plan — apparaît au prochain tour initié par l'utilisateur sans déclencher de réponse.

Options : { source?: string, ephemeral?: boolean, maxAge?: number }.

Pour les backends d'applications : vérifier qu'une requête a été signée par le proxy inverse de la passerelle.

La signature est HMAC-SHA256(timestamp:method:/api/path[?query]:sha256(body)) avec le secret de l'application comme clé. Les horodatages doivent se situer dans une plage de ±60 s par rapport à maintenant. Utilise une comparaison à temps constant.

Pour les opérations de cycle de vie des applications au-delà des enveloppes du client :

kirocrew-client fournit également deux aides pour l'automatisation de l'installation.

Valider et sérialiser app.json :

from kirocrew_client import AppManifest

m = AppManifest.from_dict({"name": "my-app", "version": "1.0.0", ...})
errors = m.validate()   # list[str] — empty if valid
data = m.to_dict()

Gérer l'installation de l'application via l'API REST de la Gateway :

from kirocrew_client import CrewClient, AppLifecycle

async with CrewClient() as mc:
    lifecycle = AppLifecycle(mc)
    await lifecycle.install("/path/to/my-app")
    await lifecycle.enable("my-app")
    await lifecycle.disable("my-app")
    await lifecycle.uninstall("my-app")
    apps = await lifecycle.list()

Gérer le processus de la passerelle Crew (démarrage, arrêt, vérification de l'état) :

from kirocrew_client import GatewayManager

gm = GatewayManager(port=5476)
await gm.start()
healthy = await gm.is_healthy()
await gm.stop()

Toutes les erreurs de kirocrew-client sont des instances CrewError avec code, message, status, body.

from kirocrew_client import CrewError

try:
    await mc.send_message("slot-1", "hello")
except CrewError as e:
    print(e.code, e.message, e.status)