Okidači

Okidač pokreće sesiju po rasporedu, putem webhooka, događaja u aplikaciji ili nadzornika.

Окидач покреће сесију без присуства особе. Користите окидач да бисте аутоматизовали понављајуће послове или послове покренуте догађајем.

Да бисте се касније вратили на задатак из неке сесије — „провери сутра да ли су одговорили“ — користите подсетник. Подсетник је окидач ограничен на ту сесију. Чува се у бази података, а не у beeuni.yaml.

Типови окидача

Beeuni подржава четири типа окидача.

• cron — покреће се по распореду који подесите.
• webhook — покреће се када спољна услуга пошаље потписан захтев на URL веб-куке пројекта.
• event — покреће се када се нешто догоди у повезаној апликацији, на пример када се отвори нови захтев за повлачење или стигне нова порука е-поште. Погледајте Окидачи догађаја у апликацијама.
• monitor — непрекидно, 24/7, покреће команду из вашег спремишта. Сваки ред који команда испише на stdout покреће окидач. Експериментално: погледајте Монитори.

Окидаче дефинишете у манифесту пројекта, beeuni.yaml. Сваки окидач садржи упит који се приказује као прва порука покренуте сесије. Стање током извршавања — као што су време последњег покретања и статус — чува се изван манифеста, у бази података. Покретање окидача не прави коммит.

Када окидач направите, ажурирате или обришете преко контролне табле, промене се уписују директно у подразумевану грану. Не пролазе кроз захтев за измену (CR). Измена датотеке beeuni.yaml унутар сесије и покретање beeuni ship прате уобичајени ток рада са граном и CR-ом.

Подесите cron окидач

beeuni triggers add daily-digest --type cron \
  --cron "0 0 9 * * 1-5" --timezone America/Los_Angeles \
  --prompt "Summarize yesterday's activity and save it as a daily note."

beeuni ship

beeuni triggers ls

Подесите окидач веб-куке

Окидачу веб-куке потребна је тајна. Beeuni је користи за проверу потписа сваког долазног захтева.

beeuni secrets set WEBHOOK_SECRET=<a-random-value>

beeuni triggers add new-lead --type webhook \
  --secret-env WEBHOOK_SECRET \
  --prompt "A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM."

beeuni ship

POST /v1/webhooks/projects/<project-id>/<slug>

Подразумевано, свако покретање започиње нову сесију у новој грани. Окидач може уместо тога поново да користи или да буде везан за одређену сесију, а окидач веб-куке може да филтрира које корисне терете ће покренути сесију — погледајте одељке Стратегија сесије и Шаблонисање корисног терета испод.

Окидачи догађаја у апликацијама

Окидач догађаја покреће агента када се у апликацији догоди догађај: отвори се захтев за повлачење, стигне порука е-поште, промени се статус проблема. Не морате да подешавате веб-куку, тајну ни потпис. Beeuni се претплаћује на догађај уместо вас и не морате ручно ништа да потписујете.

Догађај потиче од извора догађаја: адаптера који испоручује догађаје апликације. ID-ови као што је GITHUB_PULL_REQUEST_CREATED означавају догађаје које тај извор подржава. Изаберите догађај за свој конектор у каталогу догађаја.

Подешавање у веб-апликацији

1. Отворите пројекат, па изаберите Triggers и New trigger.
2. Изаберите App event.
3. Изаберите апликацију. Испод ње изаберите конектор и један од његових заједничких налога или повежите други налог. Користи се налог означен као Default, осим ако изаберете други.
4. Изаберите догађај. Испод њега ће се појавити образац са подешавањима догађаја, као што је спремиште.
5. Напишите упит и сачувајте га.

Окидач је активан чим на ознаци пише Live. Остале ознаке су Activating, Needs connection и Error. Оне одговарају статусима pending, needs_connection и error у наставку.

Прегледајте све окидаче догађаја у апликацијама

У веб-апликацији отворите Triggers и изаберите App events. У реду са филтерима налазе се All, Schedules, App events и Webhooks, сваки са бројем. Избор се чува у адреси као ?type=event, тако да можете да поставите везу до њега. Редови су груписани по апликацији. Испод њих, одељак Apps with events наводи све апликације које могу да покрену агента, а најпре приказује апликације које ваш пројекат већ користи. Изаберите апликацију да бисте отворили образац за нови окидач за ту апликацију.

Прозор конектора има картицу Triggers са догађајима апликације на том конектору. Картица се приказује само за апликације које имају догађаје.

Помоћу CLI-ја:

beeuni triggers ls --type event                 # every app event trigger, grouped by app
beeuni triggers ls --connector github-work      # the app events on one connector
beeuni triggers ls --type event --json          # the same list as JSON

--type прихвата и cron, webhook и monitor. --connector и --type могу да се комбинују.

Подешавање помоћу CLI-ја

Агент или особа обављају ове кораке редом. Сваки корак исписује оно што је потребно за следећи.

beeuni triggers events --apps
beeuni triggers events --app github
beeuni connectors add github --provider composio --app github --apply
beeuni connectors connect github --owner project
beeuni triggers events --connector github
beeuni triggers events --connector github --event GITHUB_PULL_REQUEST_CREATED
beeuni triggers add pr-review --type event \
  --connector github --event GITHUB_PULL_REQUEST_CREATED \
  --config repo=hekmat/api \
  --prompt "Review {{ event.data.html_url }}" --apply
beeuni triggers info pr-review

1. triggers events --apps приказује апликације које могу да покрећу догађаје. Апликације су груписане према извору догађаја (source: composio). За сваку апликацију приказани су њени конектори (профили) и њихови заједнички налози. У колони STATE пише connected или needs account; апликације без конектора приказују се у одељку No connector yet.
2. connectors add додаје конектор ако га апликација нема. Прескочите овај корак ако је подешено CONNECTOR.
3. connectors connect <slug> --owner project исписује везу. Особа је отвара да би повезала заједнички налог. Приватни налог члана се не рачуна. Покрените команду поново да бисте додали други заједнички налог, па му доделите ознаку помоћу connectors rename <id> <label>.
4. triggers events --connector <slug> приказује догађаје. Додајте --event <TYPE> да бисте видели подешавања догађаја и његове променљиве {{ event.data.* }}. Прочитајте опис сваког подешавања: неки догађаји захтевају пуно име у једном подешавању, као што је repo: hekmat/api, и одбијају исту вредност подељену између owner и repo.
5. triggers add --apply одмах прави окидач и исписује његов статус и следећи корак. Ако подешавање недостаје или није важеће, команда се завршава кодом 2 и наводи све проблеме. Без --apply, CLI уписује блок у локални beeuni.yaml; покрените beeuni ship да бисте га применили.
6. triggers info <slug> приказује статус. Понављајте док не буде писало live.

--source <adapter> задаје извор догађаја и опционо је: ако га не наведете, окидач користи добављача конектора. Конектор мора да припада том извору. Извор composio на конектору другог добављача приказује error: Connector "<slug>" is a <provider> connector; source "composio" needs a composio connector. Непознат извор се одбија са Unknown event source "<x>". Sources: composio.. beeuni triggers set <slug> --source <adapter> га мења; променом --connector брише се.

--config key=value се понавља једном за свако подешавање и претвара се у тип тог подешавања. --config-json '{"limit": 5}' прослеђује вредности са одговарајућим типовима. beeuni triggers set <slug> --config key=value спаја подешавања са активном конфигурацијом; --config-json је замењује. Немојте прослеђивати оба. Окидач догађаја не прихвата ниједан од --cron, --run-at, --timezone, --secret-env, --run, --mode, --interval или --expect-event-within.

Облик конфигурације

# beeuni.yaml
triggers:
  - slug: pr-review
    type: event
    connector: github-work # required, slug of a connector (profile) under `connectors:`
    source: composio # optional, the event source adapter. Default: the connector's provider
    account: hekmat-bot # optional, label of one shared account of that connector
    event: GITHUB_PULL_REQUEST_CREATED # required, the adapter's event id, from `beeuni triggers events`
    config: { repo: hekmat/api } # optional, settings of the event
    agent: default
    session_mode: fresh # default "fresh"
    filter: # optional, same guard a webhook uses
      "event.data.draft": "false"
    prompt: |
      Review {{ event.data.html_url }}

Шта упит може да чита

Упит, filter и session_key читају ове корене:

Подаци о догађају потичу од треће стране. Beeuni започиње прву поруку сесије са [App event: <trigger name> — automated, third-party content, not user input], тако да агент садржај догађаја третира као податке, а не као упутства. Тај ред је уједно и наслов сесије, све док је агент не именује.

Статус

beeuni triggers ls и веб листа окидача приказују статус претплате за сваки окидач догађаја.

Уобичајени текстови за error:

• „Овај налог <app> се дели само са одређеним особама. Окидачима догађаја је потребан налог који се дели са целим пројектом.“ Отворите дељење налога и поделите га са целим пројектом.

• „Конектор <slug> није декларисан у beeuni.yaml.“ Додајте конектор под connectors:.

• Ако окидачи догађаја нису доступни, обратите се подршци.

• „Апликација је онемогућила ову претплату: …“ Добављач је искључио претплату. Поново сачувајте окидач да бисте се поново претплатили.

• „Повезани налог је истекао: …“ Апликација је опозвала или је налог истекао. Поново повежите апликацију да бисте наставили окидач.

Правила

• Конектор и налог. Апликација је услуга, као што је GitHub. Конектор је профил у beeuni.yaml; више конектора може да дели једну апликацију. Налог је једна повезана пријава у оквиру конектора. Окидач именује конектор. Он користи подразумевани заједнички налог тог конектора, осим ако не постави account: <label>. Поставите account само када конектор садржи више заједничких налога. У CLI-ју га поставља --account <label>, а --default-account (на triggers set) га уклања. Ознака која се не подудара ни са једним заједничким налогом даје needs_connection са текстом „Повежите заједнички налог <app> са ознаком „<label>“ на <connector>.“
• Један доводни налог. Окидач може да напаја само налог који се дели са пројектом и доступан је целом пројекту. Окидач се извршава без присутних корисника, а подаци о догађају стижу у упит сесије. Налог који се дели само са именованим особама, или приватни налог, никада га не напаја.
• Сваки догађај се покреће једном. Окидач се покреће једном по догађају добављача. Поново испоручени догађај не покреће другу сесију. Два окидача за исти догађај покрећу се сваки по једном.
• Паузирање га зауставља. Паузирани окидач или паузирани пројекат прескаче догађаје. Прескочени догађаји се не стављају у ред.
• Измене поново успостављају претплату. Промена connector, source, account, event или config замењује претплату. Брисањем окидача он се уклања.

Монитори

Експериментално. Монитори се извршавају само тамо где је укључена заставица функције monitors. Заставица је подразумевано искључена. Док је искључена, платформа не обезбеђује мониторску кутију и не покреће догађаје монитора.

Монитор надгледа нешто што ни не шаље вебхукове ни одговара распореду: активни дневник, дубину реда, страницу која се мења или цену. Beeuni покреће вашу команду 24/7 у мониторској кутији пројекта — један трајни microVM по пројекту, са истом границом изолације и истим тајнама пројекта које добија сесијски sandbox. Детерминистички код надгледа; агент се буди само када команда испише ред.

Уговор дефинишу четири правила:

• Редови стандардног излаза су догађаји. Ништа друго није. Стандардни излаз за грешке служи за дијагностику: видљив је у дневницима монитора, али никада не покреће окидач.
• Сваки ред покреће окидач тачно једном, путем путање коју вебхук већ користи: filter → шаблон упита → session_mode.
• Монитор не може нечујно да откаже. Излазак процеса, исцрпљивање буџета поновних покретања и тишина дужа од expect_event_within сваки покрећу догађај животног циклуса који платформа уписује у исти ток.
• session_mode је на монитору подразумевано reuse, а не fresh. Монитор се намерно покреће више пута, па би fresh направио по једну сесију за сваки догађај.

beeuni triggers add checkout-errors --type monitor \
  --run "./monitors/checkout-errors.ts" \
  --mode poll --interval 60s --expect-event-within 24h \
  --prompt "Checkout monitor emitted: {{ line }}"

beeuni ship

beeuni triggers ls
beeuni triggers info checkout-errors

Ограничења монитора

Платформа примењује свако ограничење наведено у наставку.

Мониторској кутији је потребан добављач који подржава трајни sandbox. Тамо где добављач пројекта не може да одржава такав sandbox, заставица monitors пријављује да није доступна.

Облик конфигурације

# beeuni.yaml
triggers:
  - slug: daily-digest # required, lowercase + dashes, unique per project
    name: Daily digest # optional, defaults to slug
    type: cron # "cron" | "webhook" | "event" | "monitor", required
    agent: beeuni # optional, defaults to "default"
    model: anthropic/claude-sonnet-4-5 # optional, resolves at fire time if unset
    enabled: true # optional, default true
    cron: "0 0 9 * * 1-5" # 6-field expression, mutually exclusive with run_at
    timezone: America/Los_Angeles # IANA name, default UTC
    session_mode: reuse # "fresh" | "reuse" | "pinned" | "keyed", default "fresh"
    filter: # optional, webhook payload guard
      "body.data.direction": "inbound"
    prompt: "Summarize {{ body.text }}" # required, template string

Монитор замењује поља распореда својом командом и обликом:

# beeuni.yaml
triggers:
  - slug: checkout-errors
    type: monitor
    run: ./monitors/checkout-errors.ts # required, repo-relative command
    mode: poll # "poll" | "stream", required
    interval: 60s # required on poll, invalid on stream
    expect_event_within: 24h # optional silence watchdog
    agent: oncall
    session_mode: reuse # the monitor default
    filter: # optional, same guard a webhook uses
      "line.severity": "error"
    prompt: "Checkout monitor emitted: {{ line }}"

Окидач догађаја замењује поља распореда апликацијом и догађајем који надгледа. Погледајте Окидачи догађаја апликације.

Застарели beeuni.toml користи иста поља у другом контејнеру; погледајте застарели TOML.

Поља

Окидач cron захтева cron или run_at, никад оба. Веб-кук окидач без secret_env се одбија — не постоји неаутентификовани веб-кук. Монитору су потребни run и mode, а cron, run_at, timezone и secret_env одбија безусловно — манифест који наводи распоред који извршилац монитора никад не чита је лажан.

Подесите тајну за потписивање пре него што направите или ажурирате окидач веб-кука:

beeuni secrets set WEBHOOK_SECRET=-
beeuni secrets delivery WEBHOOK_SECRET broker --consumer connector

Проследите вредност првој команди преко стандардног улаза. Ако је тајна раније коришћена за испоруку у окружењу sandbox, промените је након промене испоруке јер постојећи sandbox може да задржи претходну вредност.

Стратегија сесије

session_mode одређује коју сесију ће покретање поново упутити. Beeuni испробава наведене режиме редом и прелази на следећи ако сваки од њих не успе.

1. pinned — поново упути тачну сесију session_id. Ако сесија више не постоји или није успела, пређи на следећи режим.
2. keyed — прикажи session_key на основу садржаја, па потражи најновију сесију која није неуспела и која је раније означена том тачном кључном вредношћу. Ако кључна вредност буде празна или нема одговарајуће сесије, пређи на нову сесију. Никад не прелази на сесију са другом кључном вредношћу.
3. reuse — поново упути најновију сесију која није неуспела и коју је овај окидач претходно направио. И окидач са закаченом сесијом прво се враћа на овај режим, па тек онда прелази даље.
4. fresh — направи нови sandbox и грану. Ово је подразумевани режим и последња могућност за све режиме. Нова сесија постаје сесија окидача за будућа покретања reuse и keyed.

Сесија reuse или keyed чија историја више не стаје у модел, чак ни након аутоматског сажимања, повлачи се из употребе. Следеће покретање започиње нову сесију. У случају било ког другог неуспеха, сесија се задржава за следеће покретање.

Окидач cron који се често покреће и не треба стално да шаље све дужу историју може да ротира сесију на граници календарског периода: session_key: "merge-{{ cron.scheduled_date }}" задржава једну серијализовану сесију за сваки дан по UTC времену, а {{ cron.scheduled_hour }} једну за сваки сат по UTC времену.

Неуспела покретања

Када се покретање које је започео окидач заврши грешком, Beeuni бележи то на окидачу:

• last_status постаје failed, а last_error садржи разлог, на пример Out of credits: Payment Required: Insufficient credits.
• Страница Schedule означава окидач са „Последње покретање није завршено“ и приказује разлог у панелу.
• Власник налога добија једно мобилно пусх обавештење када прво покретање не успе. Неуспело касније покретање ажурира разлог без слања новог обавештења.
• Окидач остаје failed док наставља да се покреће. Ново покретање не доказује да ради.

Следеће покретање које се успешно заврши уклања евиденцију неуспеха. Покретање које сами зауставите, подагент и поновљени позив модела не рачунају се као исходи покретања. Неуспело покретање пре почетка рада, на пример када сесија не може да се направи, уклања се при следећем успешном покретању.

Приступ сесији

Сесије које направи окидач подразумевано користе приватну политику. Налог услуге агента окидача је њихов власник — идентитет агента је принципал service_account, па може да буде власник сесије и да има додељене приступе као и сваки други принципал. Менаџер пројекта увек може да их отвори. Власник налога и администратор налога имају приступ еквивалентан менаџерском у свим пројектима, па то важи и за њих. Особа која је подесила окидач или га ручно покренула не добија приступ том радњом, осим ако има једну од тих улога.

Подешавања окидача нуде три политике:

• Агент окидача и менаџери пројекта — ниједан обичан члан пројекта не може да отвори сесију.
• Изабрани чланови тима — агент окидача, менаџери пројекта и изабрани чланови пројекта или групе налога.
• Цео пројекат — сви чланови пројекта.

Ова политика је поставка видљивости по ресурсу, која допуњује модел улога; она није улога. Одређује ко може да отвори сесије једног окидача. Не даје никакве дозволе које одлука заснована на улози одбија. Погледајте Налози и приступ.

Политика приступа је локално стање налога у току рада. Не уноси се у преносиви манифест beeuni.yaml јер ID-ови принципала припадају једном налогу. Подесите је помоћу контролне табле. Само ажурирање ове политике не прави Git комит. Чување политике ажурира и претходне сесије које је направио тај окидач.

Закачена сесија задржава сопствена подешавања дељења јер је окидач није направио. Ако закачена сесија није доступна и окидач направи резервну сесију, на ту нову сесију примењује се политика окидача.

Предлошци садржаја

prompt и session_key приказују се помоћу истог механизма: {{ token.dotted.path }}. Недостајућа вредност приказује се као празан стринг — нема грешке нити заосталог {{ }}. Објекти и низови приказују се као JSON. session_key се скраћује и ограничава на 512 знакова.

Свако покретање добија и {{ trigger.slug }}, {{ trigger.type }} и {{ trigger.kind }} (увек git). Остатак скупа променљивих зависи од тога како је окидач покренут.

Beeuni на серверској страни додаје [MONITOR EVENT — automated, not user input] на почетак сваког приказаног упита монитора. Догађај животног циклуса у потпуности занемарује ваш шаблон и уместо њега приказује упит који је написала платформа, а заобилази и filter — случајно филтрирање тишине мора бити немогуће.

{{ message.text }} је на ручном покретању чврсто постављен на празан стринг, а {{ message.source }} на manual_test. Ручно покретање није начин да убаците пробни унос у упит.

filter пореди путање са тачкама као стрингове са истим подацима које види упит. Служи за прекидање петљи. На пример, извор који пријављује обе стране разговора би иначе поново покренуо агента због његовог сопственог одговора.

Потпис веб-кука

Покреће се на POST /v1/webhooks/projects/{projectId}/{slug}. Beeuni проверава захтев овим редоследом, уз поређење у константном времену:

1. HMAC потпис — заглавље X-Beeuni-Signature: sha256=<hmac> (префикс sha256= је опционалан) или заглавље X-Hub-Signature-256, компатибилно са GitHub-ом. HMAC-SHA256 над сировим телом захтева, помоћу тајне која је наведена у secret_env.
2. Статички токен, само када нема заглавља са потписом, за пошиљаоце који не могу да потпишу тело помоћу HMAC-а. Пошаљите тајну као X-Beeuni-Token: <secret>, Authorization: Bearer <secret> или Authorization: Basic <base64(user:secret)> (поље за лозинку садржи токен).

beeuni triggers info <slug> исписује ову шему — заглавље, алгоритам и пример захтева потписаног помоћу резервне вредности $SECRET — а --json преноси је као webhook_signing. Исти пример захтева приказан је на листу окидача контролне табле.

Крајње тачке

Паузирање и наставак

Прекидач на нивоу пројекта истовремено зауставља сваки окидач у пројекту, независно од поља enabled појединачног окидача. Док је пројекат паузиран, планер га прескаче, а долазне веб-куке враћају 200 са { status: "skipped" } — ниједна сесија се не покреће. Ручно покретање и даље функционише. Користите ову опцију када се исто спремиште покреће на две контролне равни (на пример, у развојном и продукционом окружењу), да се cron не би покренуо двапут. CLI: beeuni triggers pause и beeuni triggers resume. Погледајте CLI за целу групу команди beeuni triggers.

Ограничења и поузданост

• Планер проверава стање отприлике сваке секунде (подразумевано 1.000 ms; може да се подеси преко BEEUNI_TRIGGER_SCHEDULER_INTERVAL_MS). Извршавање cron-а не почиње тачно у предвиђеном термину: сваки окидач добија фиксно одлагање до четвртине свог периода, а највише 30 минута, како се многи окидачи заказани за исти минут не би покренули истовремено. Детаљи окидача и GET /triggers (next_fire_at) приказују време почетка следећег покретања.
• Ако покретање не успе, последњи статус окидача се поставља на „неуспешно“, уз приказ грешке. Ово важи за све изворе: cron, ручно покретање, веб-куку, догађај апликације и монитор. Следеће успешно покретање брише статус неуспелог покретања. Неуспело покретање се брише као што је описано у одељку Неуспела покретања.
• Сваки пројекат подразумевано дозвољава да се истовремено припремају 3 покренуте сесије. Покретање преко тог ограничења враћа queued (202) уместо да не успе и извршава се када се заврши припрема једне од њих. Нема ограничења броја сесија које могу истовремено да раде.
• Ручно покретање или покретање путем веб-куке има временско ограничење од 45 секунди. Учитавање манифеста има временско ограничење од 30 секунди.
• Cron покретање се идентификује према доспелом термину распореда, тако да се покретање које је истекло, али је заправо почело, не дуплира при поновном покушају.
• Испорука путем веб-куке се извршава једном по догађају. Beeuni чита ID догађаја из X-Beeuni-Delivery-Id, X-GitHub-Delivery, X-Gitlab-Event-UUID, Linear-Delivery, webhook-id или svix-id, тим редоследом; поновни покушај са истим ID-ом враћа 202 { status: "deduped" } и ништа не покреће. X-Request-Id није ID догађаја. Ако нема ID-а догађаја, идентично тело и потпис у року од 10 минута сматрају се истим догађајем; после тога се догађај поново извршава, тако да се задатак који при сваком објављивању шаље исто статичко тело извршава при сваком објављивању. Шаљите X-Beeuni-Delivery-Id са новом вредношћу за сваки догађај (у примеру захтева користи се $(uuidgen)).
• Испорука чији је ранији покушај коначно неуспео (на пример, зато што је на налогу понестало кредита) или чија је сесија обрисана, поново се извршава када се понови испорука са истим ID-ом. Дупликат не мења last_fired_at.