Server agent

Ce este PocketHook Agent Server?

#

Serverul agent transformă PocketHook într-un asistent IA complet. În loc să scrii singur logica de răspuns, conectezi un LLM (Claude, GPT, Gemini, etc.) care procesează mesajele, apelează instrumente și returnează răspunsuri PocketHook structurate — inclusiv declanșarea de Scurtături.

Serverul rulează pe propria ta mașină. Datele tale rămân la tine.

Acesta este un punct de plecare. Serverul vine cu un set de instrumente de bază și este conceput să fie extins de tine. Adaugă propriile tale integrări — email, calendare, documente, API-uri — și fă-l al tău.

Funcționalități

#

• LLM multi-furnizor — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (local), LM Studio (local)
• Autentificare OAuth — GitHub Copilot și OpenAI Codex prin cod de dispozitiv / flux din browser
• Instrumente agent — Comenzi shell, citire/scriere fișiere, listare directoare, căutare web, web scraping, gestionare servere de dezvoltare
• Separare framework / utilizator — Fișierele framework (skills/, custom-tools/, config/) rămân doar-în-citire. Personalizările tale trăiesc sub data/user/ (competențe, instrumente personalizate, instrucțiuni, prefs tipizate). Actualizările framework-ului se aplică curat, fără să suprascrie munca ta
• Prefs de utilizator tipizate — Stochează valori precum aplicația ta preferată de hărți sau domeniul de tunel în data/user/prefs.json. Referă-le în competențe ca {{prefs.key}}, iar serverul le substituie la încărcare
• Sarcini de programare într-un singur apel — Meta-instrumentul run_code_job creează o sarcină de fundal de tip prompt (rulată de LLM-ul tău configurat) și trimite utilizatorului confirmarea într-un singur pas — înlocuiește tiparul predispus la erori “respond + create-job”
• Instrumente de protocol tipizate — Șase instrumente respond_* dedicate (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus instrumente tipizate pentru sarcini (create_once_job, create_cron_job) și instrumente tipizate pentru workspace (create_project, list_projects, delete_project). Schemele resping URL-uri malformate, sintaxă de butoane și combinații type/schedule înainte să ajungă la dispozitiv
• Scriitori tipizați pentru personalizare — create_user_skill și create_custom_tool construiesc markdown-ul stratului utilizator cu frontmatter-ul corect, astfel încât încărcătorul să le analizeze întotdeauna și agentul să nu scrie niciodată aceste fișiere de mână
• Sarcini în fundal — Sarcini unice sau recurente cu expresii cron sau intervale simple
• Competențe dinamice — Definește scurtături și reguli de comportament ca fișiere .md. Doar un index compact este încărcat în prompt; conținutul complet este recuperat la cerere prin instrumentul load_skill
• Competențe autogestionate — Agentul poate crea, edita și șterge definiții de competențe (scrierile ajung întotdeauna în stratul utilizatorului)
• Memorie semantică — Căutare vectorială cu embeddings (Ollama, LM Studio sau OpenAI). Amintirile sunt auto-clasificate în dimensiuni aripă/cameră/coridor/statut de către LLM
• Graf de cunoștințe — Stocare de triplete temporale pentru fapte durabile cu invalidare automată. Relațiile multi-valoare coexistă; faptele cu valoare unică se înlocuiesc automat
• Metoda PARA cu cascadă la finalul proiectului — Fiecare amintire este etichetată cu un statut (Proiect, Domeniu, Resursă, Arhivă). Când un proiect se încheie, un singur apel complete_project arhivează vectorii săi, invalidează fiecare triplet de planificare legat de slug-ul său și înregistrează finalizarea — un singur apel în loc de trei
• Rechemare hibridă — Combină căutarea prin cuvinte cheie FTS5 cu căutarea semantică vectorială folosind fuziune de ranguri reciproce
• Memorie pe termen lung — SQLite + căutare full-text FTS5 ca soluție de rezervă când memoria semantică este dezactivată
• Gestionare servere de dezvoltare cu contract de tunel — Pornire, oprire și listare servere de dezvoltare. Când se cere tunnel: true, serverul impune acest lucru înainte de pornire și după spawn — un server localhost inaccesibil nu este lăsat niciodată să ruleze în tăcere
• Curățare automată a URL-urilor — Dacă agentul lasă un URL localhost într-un răspuns, instrumentele respond_* îl rescriu la URL-ul de tunel corespunzător, astfel încât telefonul tău primește întotdeauna un link accesibil
• Instrumente personalizate — Agentul poate instala instrumente CLI și le poate înregistra ca noi capabilități
• Versionare — Versionare git automată pentru fișierele din spațiul de lucru; backup-uri de configurare pentru competențe și permisiuni
• Tablou de bord web — Vedere de ansamblu în timp real a sarcinilor în fundal, personalizabil per utilizator. /dashboard și /api/jobs nu sunt autentificate prin design — restricționează accesul la nivel de rețea (ACL Tailscale, firewall, reverse proxy cu autentificare de bază) sau setează DASHBOARD=false dacă nu ai nevoie
• Tuneling HTTPS — Suport integrat pentru Tailscale, ngrok și Cloudflare Tunnel
• Serviciu de sistem — Instalare ca serviciu persistent pe macOS, Linux sau Windows
• Limitare de rată — Limite de cereri per token cu praguri configurabile

Cerințe

#

• Runtime Bun
• O cheie API sau acreditări OAuth pentru furnizorul tău LLM
• (Opțional) Tailscale, ngrok sau cloudflared pentru tuneling HTTPS

Pornire rapidă

#

git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install

# Configurare interactivă — alege furnizorul, modelul, token-ul de autentificare, portul
bun run setup

# Pornește serverul + tunelul HTTPS
bun run dev:tunnel

Asistentul de configurare te va ghida prin alegerea unui furnizor LLM, configurarea autentificării și stabilirea permisiunilor pentru instrumente.

Odată ce serverul rulează, copiază URL-urile afișate în Setările PocketHook:

Cum funcționează

#

1. Trimiți un mesaj în PocketHook
2. Serverul îl transmite LLM-ului ales cu istoricul conversației, amintirile rechemate și instrumentele disponibile
3. LLM-ul procesează mesajul — poate rula comenzi shell, citi/scrie fișiere, căuta pe web, planifica sarcini în fundal, memora fapte sau porni servere de dezvoltare
4. Răspunsul este returnat în format PocketHook (msg + shortcut + data + url)
5. PocketHook afișează mesajul și execută orice Scurtături pe dispozitivul tău

Furnizori LLM suportați

#

Schimbă furnizorul oricând cu bun run switch. Ollama și LM Studio rulează în întregime pe mașina ta — fără cheie API necesară, nicio dată nu părăsește rețeaua ta.

Memorie

#

Sistemul de memorie are trei straturi, fiecare servind un scop diferit.

Designul memoriei semantice combină idei din MemPalace (o arhitectură de palat al memoriei care organizează amintirile în aripi, coridoare și camere) și metoda PARA a lui Tiago Forte (Proiecte, Domenii, Resurse, Arhive) pentru gestionarea ciclului de viață al cunoștințelor.

Memorie de conversație

#

SQLite cu căutare full-text FTS5. Toate mesajele sunt stocate cu marcaje temporale și identificatori de sesiune.

• Termen scurt — Ultimele MAX_HISTORY mesaje păstrate în memorie per sesiune
• Termen lung — Toate mesajele persistate în SQLite, căutabile prin potrivire de cuvinte cheie FTS5
• Rechemare per tură — Când memoria semantică este activă, MAX_RECALL controlează câte amintiri relevante sunt injectate în prompt la fiecare tură
• Sesiunile expiră după SESSION_TTL_MINUTES, dar memoria pe termen lung persistă pentru totdeauna

Reglează aceste setări interactiv cu bun run memory.

Memorie semantică

#

Necesită VECTOR_MEMORY=true și un furnizor de embeddings (Ollama, LM Studio sau OpenAI).

Fiecare amintire este încorporată ca vector și auto-clasificată de LLM în patru dimensiuni:

• Aripă — Entitatea: user, person:john, project:blog, place:london
• Cameră — Tipul: facts, preferences, events, decisions, requests
• Coridor — Subiectul: personal, tech, health, travel, food, work
• Statut — Clasificare PARA: project, area, resource, archive

Când pui o întrebare, extracția de entități concentrează căutarea vectorială pe aripile cele mai relevante. Rezultatele sunt fuzionate cu rezultatele de cuvinte cheie FTS5 folosind fuziunea de ranguri reciproce — astfel obții ce e mai bun din potrivirea prin cuvinte cheie și cea semantică.

Graf de cunoștințe

#

Un depozit de triplete temporale pentru fapte structurate și durabile:

• Triplete: (subiect, predicat, obiect) cu marcaje temporale valid_from / valid_until
• Predicatele cu valoare unică (lives_in, partner) invalidează automat valoarea veche la actualizare
• Predicatele multi-valoare (child, friend, hobby) coexistă fără invalidare
• Faptele din graful de cunoștințe sunt injectate alături de amintirile rechemate în fiecare conversație

Când îi spui agentului „M-am mutat la Berlin", invalidează tripletul vechi lives_in și creează unul nou — automat.

Ciclul de viață PARA

#

Fiecare amintire este etichetată cu un statut PARA:

• Proiect — Muncă activă, limitată în timp
• Domeniu — Responsabilități continue
• Resursă — Material de referință (liste, recomandări, ghiduri practice)
• Arhivă — Proiecte finalizate sau anulate

Când un proiect este finalizat, agentul folosește similaritatea semantică pentru a arhiva doar amintirile acelui proiect, păstrând materialele de referință pentru utilizare viitoare.

Cascadă la finalul proiectului

#

Spune „Îmi anulez călătoria la Barcelona" și un singur apel de instrument se ocupă de tot:

1. Arhivează vectorii proiectului (evenimente, decizii, cereri legate de Barcelona).
2. Invalidează fiecare triplet activ din graful de cunoștințe al cărui predicat se potrivește cu slug-ul proiectului (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Înregistrează finalizarea ca un triplet nou: (user, "cancelled_visit_barcelona", "2026-04-15").

Potrivirea ține cont de limite — un alt proiect numit revisit_barcelona rămâne neatins. Agentul nu mai trebuie să orchestreze trei apeluri separate în ordinea corectă, astfel încât și modelele mai mici reușesc corect.

Dacă VECTOR_MEMORY este dezactivat sau furnizorul de embeddings este inaccesibil, sistemul trece pe FTS5 fără erori.

Competențe

#

Competențele sunt fișiere .md în skills/ care definesc Scurtăturile iOS pe care agentul le poate declanșa și/sau reguli de comportament. Folosesc încărcare dinamică: doar un index compact (titlu, descriere, listă de scurtături) este injectat în promptul de sistem. Agentul încarcă conținutul complet la cerere prin instrumentul load_skill, menținând utilizarea de tokeni scăzută pe măsură ce adaugi mai multe competențe.

Fiecare fișier de competență folosește un antet YAML:

---
title: Notes
description: Create notes on the user's device with a title and body
shortcuts: [newNote]
target: mac
sync_app: Notes
---

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

Data fields:
- title (string, required): Note title
- content (string, required): Note body

Câmpuri frontmatter

#

Competențele pot fi și reguli de comportament fără scurtături (de ex. „cum să planifici o vacanță în familie"). Folosește shortcuts: [] pentru acestea.

Agentul poate crea și gestiona competențe la cerere — cere-i să „creeze o competență pentru controlul luminilor" și va scrie fișierul .md pentru tine. Competențele noi și cele editate ajung întotdeauna în stratul tău de utilizator (data/user/skills/), astfel încât actualizările framework-ului nu le suprascriu niciodată. Consultă secțiunea Personalizarea agentului tău de mai jos.

Executarea scurtăturilor pe serverul Mac

#

Când o competență are target: mac, scurtăturile rulează în tăcere pe serverul Mac prin CLI-ul shortcuts run în loc să fie trimise către dispozitivul iOS. Este ideal pentru acțiuni care creează conținut sincronizat cu iCloud — notițe, memento-uri, evenimente de calendar — deoarece rezultatul se sincronizează automat pe toate dispozitivele tale fără ca aplicația PocketHook să fie nevoită să facă ceva.

Cum funcționează:

1. Agentul decide că o scurtătură trebuie să ruleze (de ex. „creează o notiță cu notițele ședinței de azi")
2. Serverul invocă shortcuts run "numeScurtătură" cu datele transmise ca JSON pe stdin, folosind același format de ambalaj ca PocketHook iOS
3. Dacă sync_app este setat, serverul deschide scurt acea aplicație în fundal (open -gj -a Notes) pentru a forța sincronizarea iCloud, apoi o închide după 5 secunde
4. Utilizatorul primește un mesaj de confirmare în chat; scurtătura în sine nu este trimisă pe dispozitiv

Cerințe:

• Serverul trebuie să ruleze pe macOS — shortcuts run există doar pe macOS. Pe alte platforme, serverul înregistrează un avertisment și revine la execuția pe dispozitiv
• Scurtătura trebuie să fie instalată în Shortcuts.app pe Mac-ul server
• Scurtătura ar trebui să aștepte un Dictionary ca intrare (PocketHook împachetează datele în { context, timestamp, app, data })

Când să folosești target: mac:

• Acțiuni sincronizate cu iCloud (Notes, Reminders, Calendar) — rezultatul ajunge oricum pe fiecare dispozitiv
• Procesare de durată pe care vrei să o ții departe de dispozitivul iOS
• Orice scurtătură care nu trebuie să interacționeze cu interfața iPhone-ului

Când să păstrezi target: device (implicit):

• Scurtături care au nevoie de funcții disponibile doar pe iPhone (cameră, locație precisă, automatizări locale de aplicații)
• Scurtături care cer utilizatorului intrare interactivă
• Scurtături care folosesc App Intents din aplicații disponibile doar pe iOS

Sarcini în fundal

#

Cere agentului să planifice sarcini și se ocupă de rest:

• „Verifică vremea în fiecare dimineață la 8 și creează o notă"
• „Rulează acest script la fiecare oră"
• „Amintește-mi să verific emailul în 30 de minute"

Sarcinile suportă expresii cron (0 8 * * *) și intervale simple (30m, 1h, 2d). Rezultatele sunt livrate către PocketHook când acesta interoghează endpoint-ul /jobs.

Două tipuri de execuție:

• Shell — Rulează o comandă bash, capturează ieșirea. Poate declanșa o Scurtătură la finalizare
• Prompt — Procesat de agentul IA cu acces complet la instrumente, stochează răspunsul PocketHook complet

Servere de dezvoltare

#

Când agentul creează un proiect web în spațiul de lucru (Hugo, Astro, Next.js, Flask, Go, etc.), oferă proactiv să îl servească:

• Previzualizare — Pornește un server de dezvoltare local pe un port auto-alocat pentru vizualizare rapidă
• Public — Pornește serverul și îl expune prin tunel HTTPS pentru a fi accesibil de oriunde

Agentul gestionează ciclul de viață: pornire, oprire și listarea serverelor care rulează. Toate serverele sunt curățate când serverul principal se oprește.

Contract de tunel

#

Când agentul pornește un server cu expunere prin tunel solicitată, runtime-ul o impune: dacă niciun instrument de tunel (Tailscale, ngrok, cloudflared) nu este instalat, serverul refuză să pornească. Dacă configurarea tunelului eșuează după spawn, procesul orfan este oprit și agentul este informat explicit — astfel încât poate reveni la modul de previzualizare sau îți poate cere să instalezi un tunel. URL-ul returnat este întotdeauna URL-ul de tunel când tunelarea este activă, cu o notă că URL-ul local este doar pentru gazdă.

Ca plasă de siguranță, fiecare instrument respond_* post-procesează mesajul său: orice URL localhost sau 127.0.0.1 care se strecoară într-un răspuns este rescris automat la URL-ul de tunel corespunzător atunci când un server gestionat are unul. Când nu poate fi rescris, primești un avertisment în jurnale în loc de un link rupt pe telefon.

Tablou de bord

#

Tabloul de bord web integrat la /dashboard arată o vedere de ansamblu în timp real a sarcinilor în fundal.

Neautentificat prin design. Atât /dashboard, cât și /api/jobs sunt endpoint-uri GET deschise — oricine poate ajunge la gazdă poate lista sarcinile. Restricționează accesul la nivel de rețea (ACL Tailscale, firewall, reverse proxy cu autentificare de bază) sau setează DASHBOARD=false dacă nu ai nevoie. Aplicația PocketHook pentru iOS nu folosește aceste endpoint-uri.

Este complet personalizabil:

• Editare rapidă — Plasează un dashboard.html în workspace/dashboard/ pentru personalizări simple
• Proiect complet — Creează un proiect cu framework (Svelte, React, Vue, etc.) în workspace/dashboard/ cu ieșirea de compilare în dist/

Cere agentului să personalizeze tabloul de bord și se ocupă de rest — fiecare utilizator primește un tablou de bord unic și personalizat.

Instrumente personalizate

#

Agentul poate instala instrumente CLI și le poate înregistra ca noi capabilități — extinzându-se singur fără a modifica codul serverului.

De exemplu, spune „instalează Playwright și folosește-l pentru a face capturi de ecran". Agentul va:

1. Instala dependența
2. Crea o definiție de instrument (un simplu fișier .md)
3. Folosi noul instrument în conversațiile viitoare

Instrumentele personalizate sunt reîncărcate la cald — nu e nevoie de restart. Șterge fișierul .md pentru a elimina un instrument.

Versionare

#

Toate datele utilizatorului sunt versionate automat:

• Fișiere din spațiul de lucru — Urmărite cu un depozit git local în workspace/. Fiecare scriere creează un commit automat. Cere agentului să „anuleze ultima modificare" sau folosește git revert HEAD manual
• Fișiere de configurare — config/agent-instructions.md, config/personality.md, skills/ și permissions.json sunt salvate înainte de fiecare modificare. Până la 20 de versiuni per fișier

Git este opțional — dacă nu este instalat, modificările din spațiul de lucru nu sunt versionate. Backup-urile de configurare funcționează întotdeauna.

Personalizarea agentului tău

#

Serverul agent vine cu o bază framework minimă și așteaptă ca tu să adaugi propriile personalizări deasupra. Runtime-ul le ține pe cele două separate, astfel încât actualizările framework-ului să nu-ți zdrobească niciodată munca.

Framework vs. utilizator

#

pockethook-agent-server/
├── skills/                      # competențe livrate de framework (doar-în-citire)
├── custom-tools/                # rezervat pentru instrumente livrate de framework (doar-în-citire)
├── config/
│   ├── agent-instructions.md    # instrucțiuni agent framework (doar-în-citire)
│   └── personality.md           # personalitate framework (doar-în-citire)
└── data/user/                   # Personalizarea TA trăiește aici (ignorat de git)
    ├── skills/                  # propriile tale competențe (suprascriu baza după numele fișierului)
    ├── custom-tools/            # instrumentele personalizate instalate de tine
    ├── instructions.md          # adăugirile tale la instrucțiunile agentului
    └── prefs.json               # valori tipizate referite ca {{prefs.key}}

Personalizarea utilizatorului este scrisă prin instrumente tipizate dedicate (create_user_skill, create_custom_tool), astfel încât fișierele rezultate să corespundă întotdeauna formatului încărcătorului. Instrumentul write respinge, de asemenea, orice cale sub skills/, custom-tools/ sau config/ și redirecționează agentul către data/user/* — astfel încât chiar și editările directe ale fișierelor ajung în stratul utilizatorului.

Notă despre directorul de bază custom-tools/. Astăzi conține doar un șablon (_example.md) pe care încărcătorul îl ignoră — fiecare instrument pe care agentul îl instalează pentru tine merge în data/user/custom-tools/. Directorul este rezervat astfel încât versiunile viitoare ale framework-ului să poată livra instrumente opționale încorporate fără să-ți suprascrie instalările. Când se întâmplă asta, fișierele tale din stratul utilizatorului tot câștigă în caz de coliziune de nume, deci nu e nimic de migrat.

Patru moduri de personalizare

#

Nu trebuie să scrii niciodată aceste fișiere manual. Spune-i pur și simplu agentului ce vrei și alege stratul corect automat.

Preferințe tipizate cu {{prefs.*}}

#

Să zicem că scrii o competență de planificator de trasee care trebuie să cunoască punctul tău de plecare implicit. În loc să codifici „Madrid" în competență, referă prefs-ul:

- **Punct de plecare**: {{prefs.routeOrigin}}, dacă utilizatorul nu specifică o altă origine.

Și stochează valoarea în data/user/prefs.json:

{
  "routeOrigin": "Madrid, Spania",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

Serverul substituie substituenții când competența este încărcată. Cheile imbricate ({{prefs.tunnel.domain}}) funcționează și ele. Cheile necunoscute rămân neatinse, astfel încât greșelile de tastare rămân vizibile.

Editarea directă a bazei framework-ului

#

Dacă te auto-găzduiești și vrei să modifici framework-ul în sine, poți edita direct config/agent-instructions.md, config/personality.md, skills/ sau custom-tools/ — serverul nu te oprește când folosești un editor de fișiere. Dar agentul nu va scrie la acele căi dintr-o conversație. Și actualizările framework-ului vor suprascrie editările tale. Preferă stratul utilizatorului pentru orice vrei să păstrezi.

Extinderea serverului

#

• Instrumente personalizate — Cere agentului să instaleze instrumente CLI; ajung automat în data/user/custom-tools/
• Adaugă competențe — Cere agentului să creeze o competență; fișierul merge în data/user/skills/
• Schimbă comportamentul — Cere agentului să aplice o regulă globală; se adaugă în data/user/instructions.md
• Configurează permisiunile — Rulează bun run permissions pentru a controla ce instrumente poate folosi agentul
• Adaugă instrumente integrate — Implementează noi funcții de instrumente în src/tools.ts pentru integrări mai profunde (necesită forking-ul serverului)

Configurare

#

Toate setările sunt stocate în .env (creat de bun run setup). Opțiuni principale:

Consultă referința completă de configurare în depozitul GitHub.

Rulare ca serviciu

#

Instalează ca serviciu persistent care pornește automat:

bun run service install

INSTANCE_NAME are ca valoare implicită basename-ul directorului proiectului cu prefixul pockethook- eliminat (de exemplu, un checkout în pockethook-agent-server/ devine agent-server). Setează-l explicit pentru a rula mai multe checkout-uri pe aceeași mașină fără coliziuni — fiecare instanță își păstrează propriul data/ și log-urile.

Gestionează cu bun run service status, restart, stop sau uninstall.

Securitate

#

• HTTPS obligatoriu — PocketHook impune HTTPS pentru toate URL-urile
• Autentificare prin token Bearer — Secret partajat între aplicație și server
• Limitare de rată — Limite per token pentru prevenirea abuzului
• Instrumente sandboxate — Comenzi shell și acces la fișiere restricționate de permisiuni
• Tipare blocate — Comenzi periculoase (sudo, rm -rf /) blocate implicit
• Limita directorului de lucru — Agentul nu poate ieși din directorul desemnat
• Fișiere sensibile protejate — .env, .git, *.key, *.pem blocate de la accesul agentului
• Versionare automată — Toate modificările din spațiul de lucru sunt urmărite prin git pentru rollback facil