Servidor d'Agent

Què és PocketHook Agent Server?

#

El servidor d’agent converteix PocketHook en un assistent d’IA complet. En lloc d’escriure la lògica de resposta tu mateix, connectes un LLM (Claude, GPT, Gemini, etc.) que processa missatges, crida eines i retorna respostes estructurades de PocketHook — incloent l’activació de Shortcuts.

El servidor s’executa a la teva pròpia màquina. Les teves dades es queden amb tu.

Això és un punt de partida. El servidor ve amb un conjunt bàsic d’eines i està dissenyat per ser ampliat per tu. Afegeix les teves pròpies integracions — correu, calendaris, documents, APIs — i fes-lo teu.

Funcionalitats

#

• LLM multi-proveïdor — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (local), LM Studio (local)
• Autenticació OAuth — GitHub Copilot i OpenAI Codex via flux de codi de dispositiu / navegador
• Eines d’agent — Comandes shell, lectura/escriptura de fitxers, llistat de directoris, cerca web, web scraping, gestió de servidors dev
• Separació framework / usuari — Els fitxers del framework (skills/, custom-tools/, config/) són de només lectura. Les teves personalitzacions viuen sota data/user/ (habilitats, eines personalitzades, instruccions, prefs tipades). Les actualitzacions del framework s’apliquen sense sobreescriure la teva feina
• Preferències d’usuari tipades — Emmagatzema valors com la teva app de mapes preferida o el teu domini de túnel a data/user/prefs.json. Refereix-t’hi en les habilitats com {{prefs.key}} i el servidor els substitueix en carregar
• Tasques de programació en una sola crida — La meta-eina run_code_job crea un treball en segon pla de tipus prompt (executat pel teu LLM configurat) i envia a l’usuari l’acusament en un sol pas, substituint el fràgil patró “respond + create-job”
• Eines de protocol tipades — Sis eines respond_* dedicades (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), més eines de treballs tipades (create_once_job, create_cron_job) i eines de workspace tipades (create_project, list_projects, delete_project). Els esquemes rebutgen URLs malformades, sintaxi de botons i combinacions type/schedule abans que arribin al dispositiu
• Escriptors tipats per a la personalització — create_user_skill i create_custom_tool construeixen el markdown de la capa d’usuari amb el frontmatter correcte, de manera que el carregador sempre els analitza i l’agent mai no escriu aquests fitxers a mà
• Treballs en segon pla — Tasques úniques o recurrents amb expressions cron o intervals simples
• Habilitats dinàmiques — Defineix dreceres i regles de comportament com a fitxers .md. Només un índex compacte es carrega al prompt; el contingut complet s’obté sota demanda via l’eina load_skill
• Habilitats autogestionades — L’agent pot crear, editar i eliminar definicions d’habilitats (les escriptures sempre aterren a la capa d’usuari)
• Memòria semàntica — Cerca basada en vectors amb embeddings (Ollama, LM Studio o OpenAI). Els records són auto-classificats en dimensions de wing/room/hall/status pel LLM
• Graf de coneixement — Magatzem de triples temporals per a fets duradors amb auto-invalidació. Les relacions multi-valor coexisteixen; els fets de valor únic es reemplacen automàticament
• Mètode PARA amb cascada de tancament de projecte — Cada record s’etiqueta amb un estat (Projecte, Àrea, Recurs, Arxiu). Quan un projecte acaba, una sola crida a complete_project arxiva els seus vectors, invalida tots els triples de planificació lligats al seu slug i registra la finalització — una crida en lloc de tres
• Recuperació híbrida — Combina cerca per paraules clau FTS5 amb cerca semàntica per vectors usant fusió de rang recíproc
• Memòria a llarg termini — SQLite + cerca de text complet FTS5 com a alternativa quan la memòria semàntica està deshabilitada
• Gestió de servidors dev amb contracte de túnel — Inicia, atura i llista servidors dev. Quan es demana tunnel: true, el servidor ho exigeix tant en la comprovació prèvia com després del spawn — mai no es deixa corrent en silenci un servidor localhost inabastable
• Sanejament automàtic d’URLs — Si l’agent deixa una URL localhost en una resposta, les eines respond_* la reescriuen a la URL de túnel corresponent perquè el teu telèfon sempre rebi un enllaç accessible
• Eines personalitzades — L’agent pot instal·lar eines CLI i registrar-les com a noves capacitats
• Versionat — Versionat git automàtic per a fitxers del workspace; còpies de seguretat de configuració per a habilitats i permisos
• Tauler web — Vista en directe de treballs en segon pla, personalitzable per usuari. /dashboard i /api/jobs no estan autenticats per disseny — restringeix l’accés a la capa de xarxa (ACL de Tailscale, tallafoc, proxy invers amb autenticació bàsica) o configura DASHBOARD=false si no el necessites
• Túnels HTTPS — Suport integrat per a Tailscale, ngrok i Cloudflare Tunnel
• Servei del sistema — Instal·la com a servei persistent a macOS, Linux o Windows
• Limitació de taxa — Límits de peticions per token amb llindars configurables

Requisits

#

• Runtime Bun
• Una clau API o credencials OAuth per al teu proveïdor LLM
• (Opcional) Tailscale, ngrok o cloudflared per a túnels HTTPS

Inici Ràpid

#

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

# Configuració interactiva — tria proveïdor, model, token d'auth, port
bun run setup

# Iniciar servidor + túnel HTTPS
bun run dev:tunnel

L’assistent de configuració et guiarà per triar un proveïdor LLM, configurar l’autenticació i establir els permisos d’eines.

Un cop en funcionament, copia les URLs mostrades a la Configuració de PocketHook:

Com Funciona

#

1. Envies un missatge a PocketHook
2. El servidor el reenvia al teu LLM triat amb l’historial de conversa, records recuperats i eines disponibles
3. El LLM processa el missatge — pot executar comandes shell, llegir/escriure fitxers, cercar a la web, programar treballs en segon pla, recordar fets o iniciar servidors dev
4. La resposta es retorna en format PocketHook (msg + shortcut + data + url)
5. PocketHook mostra el missatge i executa qualsevol Shortcut al teu dispositiu

Proveïdors LLM Suportats

#

Canvia de proveïdor en qualsevol moment amb bun run switch. Ollama i LM Studio s’executen completament a la teva màquina — sense clau API, sense dades que surtin de la teva xarxa.

Memòria

#

El sistema de memòria té tres capes, cadascuna amb un propòsit diferent.

El disseny de la memòria semàntica combina idees de MemPalace (una arquitectura de palau de memòria que organitza records en ales, passadissos i habitacions) i el mètode PARA de Tiago Forte (Projectes, Àrees, Recursos, Arxiu) per a la gestió del cicle de vida del coneixement.

Memòria de conversa

#

SQLite amb cerca de text complet FTS5. Tots els missatges s’emmagatzemen amb marques de temps i IDs de sessió.

• Curt termini — Els últims MAX_HISTORY missatges es mantenen en memòria per sessió
• Llarg termini — Tots els missatges persisteixen a SQLite, cercables via coincidència de paraules clau FTS5
• Recuperació per torn — Quan la memòria semàntica està activada, MAX_RECALL controla quants records rellevants s’injecten al prompt en cada torn
• Les sessions expiren després de SESSION_TTL_MINUTES, però la memòria a llarg termini persisteix per sempre

Ajusta-ho de manera interactiva amb bun run memory.

Memòria semàntica

#

Requereix VECTOR_MEMORY=true i un proveïdor d’embeddings (Ollama, LM Studio o OpenAI).

Cada record es converteix en un vector i s’auto-classifica pel LLM en quatre dimensions:

• Wing — L’entitat: user, person:john, project:blog, place:london
• Room — El tipus: facts, preferences, events, decisions, requests
• Hall — El tema: personal, tech, health, travel, food, work
• Status — Classificació PARA: project, area, resource, archive

Quan fas una pregunta, l’extracció d’entitats enfoca la cerca vectorial als wings més rellevants. Els resultats es fusionen amb els resultats de paraules clau FTS5 usant fusió de rang recíproc — per obtenir el millor d’ambdós, coincidència per paraules clau i semàntica.

Graf de coneixement

#

Un magatzem de triples temporals per a fets estructurats i duradors:

• Triples: (subjecte, predicat, objecte) amb marques de temps valid_from / valid_until
• Els predicats de valor únic (lives_in, partner) auto-invaliden el valor anterior en actualitzar
• Els predicats de multi-valor (child, friend, hobby) coexisteixen sense invalidació
• Els fets del graf de coneixement s’injecten juntament amb els records recuperats a cada conversa

Quan dius a l’agent “M’he mudat a Berlín”, invalida el triple antic de lives_in i en crea un de nou — automàticament.

Cicle de vida PARA

#

Cada record s’etiqueta amb un estat PARA:

• Projecte — Treball actiu amb límit de temps
• Àrea — Responsabilitats continuades
• Recurs — Material de referència (llistes, recomanacions, tutorials)
• Arxiu — Projectes completats o cancel·lats

Quan un projecte es completa, l’agent usa similitud semàntica per arxivar només els records d’aquell projecte mentre preserva el material de referència per a ús futur.

Cascada de tancament de projecte

#

Digues “cancel·lo el viatge a Barcelona” i una sola crida d’eina ho gestiona tot:

1. Arxiva els vectors del projecte (esdeveniments, decisions i peticions lligats a Barcelona).
2. Invalida tots els triples actius del graf de coneixement el predicat dels quals coincideixi amb el slug del projecte (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Enregistra la finalització com un nou triple: (user, "cancelled_visit_barcelona", "2026-04-15").

La coincidència respecta els límits de paraula — un projecte diferent anomenat revisit_barcelona queda intacte. L’agent ja no ha d’orquestrar tres crides separades en l’ordre correcte, així que els models més petits també ho encerten.

Si VECTOR_MEMORY està deshabilitat o el proveïdor d’embeddings no està disponible, el sistema recorre a només FTS5 sense errors.

Habilitats

#

Les habilitats són fitxers .md a skills/ que defineixen Shortcuts d’iOS que l’agent pot activar i/o regles de comportament. Usen càrrega dinàmica: només un índex compacte (títol, descripció, llista de dreceres) s’injecta al prompt del sistema. L’agent carrega el contingut complet sota demanda via l’eina load_skill, mantenint l’ús de tokens baix a mesura que afegeixes més habilitats.

Cada fitxer d’habilitat usa frontmatter 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

Camps del frontmatter

#

Les habilitats també poden ser regles de comportament sense dreceres (per exemple, “com planificar un viatge familiar”). Usa shortcuts: [] per a aquests.

L’agent pot crear i gestionar habilitats quan se li demana — demana-li que “creï una habilitat per controlar els meus llums” i escriurà el fitxer .md per tu. Les habilitats noves i editades aterren sempre a la teva capa d’usuari (data/user/skills/), de manera que les actualitzacions del framework mai no les sobreescriuen. Consulta la secció Personalitzant el teu agent més avall.

Executar dreceres al servidor Mac

#

Quan una habilitat té target: mac, les dreceres s’executen silenciosament al servidor Mac via la CLI shortcuts run en lloc d’enviar-se al dispositiu iOS. Això és ideal per a accions que creen contingut sincronitzat per iCloud — notes, recordatoris, esdeveniments de calendari — perquè el resultat se sincronitza automàticament a tots els teus dispositius sense que l’app PocketHook hagi de fer res.

Com funciona:

1. L’agent decideix que una drecera s’ha d’executar (per exemple, “crea una nota amb els apunts de la reunió d’avui”)
2. El servidor invoca shortcuts run "shortcutName" amb les dades passades com a JSON per stdin, usant el mateix format embolcall que utilitza PocketHook iOS
3. Si sync_app està configurat, el servidor obre breument aquesta app en segon pla (open -gj -a Notes) per forçar la sincronització d’iCloud, i la tanca després de 5 segons
4. L’usuari rep un missatge de confirmació al xat; la drecera en si no s’envia al dispositiu

Requisits:

• El servidor ha d’executar-se a macOS — shortcuts run és exclusiu de macOS. En altres plataformes, el servidor registra un avís i recorre a l’execució al dispositiu
• La drecera ha d’estar instal·lada a Shortcuts.app al Mac servidor
• La drecera ha d’esperar un Diccionari com a entrada (PocketHook embolcalla les dades en { context, timestamp, app, data })

Quan usar target: mac:

• Accions sincronitzades per iCloud (Notes, Recordatoris, Calendari) — el resultat arriba a tots els dispositius igualment
• Processament de llarga durada que vulguis mantenir fora del dispositiu iOS
• Qualsevol drecera que no necessiti interactuar amb la UI de l’iPhone

Quan mantenir target: device (per defecte):

• Dreceres que necessiten funcions exclusives de l’iPhone (càmera, ubicació precisa, automatitzacions locals d’apps)
• Dreceres que demanen entrada interactiva a l’usuari
• Dreceres que usen App Intents d’apps només per a iOS

Treballs en Segon Pla

#

Demana a l’agent que programi tasques i ell s’encarregarà de la resta:

• “Comprova el temps cada matí a les 8am i crea una nota”
• “Executa aquest script cada hora”
• “Recorda’m comprovar el meu correu en 30 minuts”

Els treballs suporten expressions cron (0 8 * * *) i intervals simples (30m, 1h, 2d). Els resultats s’entreguen a PocketHook quan consulta l’endpoint /jobs.

Dos tipus d’execució:

• Shell — Executa una comanda bash, captura la sortida. Pot activar un Shortcut en completar-se
• Prompt — Processat per l’agent d’IA amb accés complet a eines, emmagatzema la resposta completa de PocketHook

Servidors Dev

#

Quan l’agent crea un projecte web al workspace (Hugo, Astro, Next.js, Flask, Go, etc.), ofereix proactivament servir-lo:

• Vista prèvia — Inicia un servidor dev local en un port auto-assignat per a una vista ràpida
• Públic — Inicia el servidor i l’exposa via túnel HTTPS perquè sigui accessible des de qualsevol lloc

L’agent gestiona el cicle de vida: iniciar, aturar i llistar servidors en funcionament. Tots els servidors es netegen quan el servidor principal s’atura.

Contracte de túnel

#

Quan l’agent arrenca un servidor demanant exposició per túnel, el runtime ho exigeix: si no hi ha cap eina de túnel instal·lada (Tailscale, ngrok, cloudflared), el servidor es nega a arrencar. Si la configuració del túnel falla després del spawn, el procés orfe s’atura i se li comunica a l’agent de manera explícita — perquè pugui recórrer al mode vista prèvia o demanar-te que instal·lis un túnel. L’URL retornada és sempre la URL del túnel quan la tunelització està activada, amb una nota que l’URL local és només per al host.

Com a xarxa de seguretat, cada eina respond_* post-processa el seu missatge: qualsevol URL de localhost o 127.0.0.1 que s’escoli a una resposta es reescriu automàticament a la URL de túnel corresponent quan un servidor gestionat en té una. Quan no pot reescriure-la, reps un avís als logs en lloc d’un enllaç trencat al telèfon.

Tauler

#

El tauler web integrat a /dashboard mostra una vista en directe dels treballs en segon pla.

No autenticat per disseny. Tant /dashboard com /api/jobs són endpoints GET oberts — qualsevol que pugui arribar al host pot llistar els treballs. Restringeix l’accés a la capa de xarxa (ACL de Tailscale, tallafoc, proxy invers amb autenticació bàsica) o configura DASHBOARD=false si no el necessites. L’app de PocketHook per a iOS no fa servir aquests endpoints.

És completament personalitzable:

• Edició ràpida — Col·loca un dashboard.html a workspace/dashboard/ per a personalitzacions simples
• Projecte complet — Crea un projecte amb framework (Svelte, React, Vue, etc.) a workspace/dashboard/ amb sortida de build a dist/

Demana a l’agent que personalitzi el teu tauler i ell s’encarregarà de la resta — cada usuari obté un tauler únic i personalitzat.

Eines Personalitzades

#

L’agent pot instal·lar eines CLI i registrar-les com a noves capacitats — estenent-se a si mateix sense modificar el codi del servidor.

Per exemple, digues “instal·la Playwright i utilitza’l per fer captures de pantalla”. L’agent:

1. Instal·larà la dependència
2. Crearà una definició d’eina (un simple fitxer .md)
3. Utilitzarà la nova eina en converses futures

Les eines personalitzades es recarreguen en calent — no cal reiniciar. Elimina el fitxer .md per eliminar una eina.

Versionat

#

Totes les dades d’usuari es versionen automàticament:

• Fitxers del workspace — Rastreats amb un repositori git local dins de workspace/. Cada escriptura crea un auto-commit. Demana a l’agent que “desfaci l’últim canvi” o usa git revert HEAD manualment
• Fitxers de configuració — config/agent-instructions.md, config/personality.md, skills/ i permissions.json es copien de seguretat abans de cada modificació. Fins a 20 versions per fitxer

Git és opcional — si no està instal·lat, els canvis del workspace no es versionen. Les còpies de seguretat de configuració sempre funcionen.

Personalitzant el teu agent

#

El servidor d’agent ve amb una base mínima del framework i espera que hi afegeixis la teva personalització a sobre. El runtime manté totes dues parts separades perquè les actualitzacions del framework mai no esclafin la teva feina.

Framework vs. usuari

#

pockethook-agent-server/
├── skills/                      # habilitats del framework (només lectura)
├── custom-tools/                # reservat per a eines del framework (només lectura)
├── config/
│   ├── agent-instructions.md    # instruccions de l'agent del framework (només lectura)
│   └── personality.md           # personalitat del framework (només lectura)
└── data/user/                   # LA TEVA personalització viu aquí (ignorat per git)
    ├── skills/                  # les teves pròpies habilitats (prevalen per nom de fitxer)
    ├── custom-tools/            # les teves eines personalitzades instal·lades
    ├── instructions.md          # les teves addicions a les instruccions de l'agent
    └── prefs.json               # valors tipats referenciats com {{prefs.key}}

La personalització d’usuari s’escriu mitjançant eines tipades dedicades (create_user_skill, create_custom_tool) de manera que els fitxers resultants sempre coincideixen amb el format del carregador. L’eina write també rebutja qualsevol ruta sota skills/, custom-tools/ o config/ i redirigeix l’agent a data/user/* — així, fins i tot les edicions directes de fitxers acaben a la capa d’usuari.

Nota sobre el directori base custom-tools/. Avui només conté una plantilla (_example.md) que el carregador ignora — cada eina que l’agent instal·la per tu va a data/user/custom-tools/. El directori queda reservat perquè futures versions del framework puguin dur eines integrades opcionals sense trepitjar les teves instal·lacions. Quan això passi, els teus fitxers de la capa d’usuari continuen guanyant en cas de col·lisió per nom d’eina, així que no hi ha res a migrar.

Quatre maneres de personalitzar

#

No cal que escriguis aquests fitxers a mà. Només digues a l’agent què vols i ell tria la capa adequada automàticament.

Preferències tipades amb {{prefs.*}}

#

Imagina que escrius una habilitat planificadora de rutes que necessita saber el teu punt de partida per defecte. En lloc d’incrustar “Barcelona” a l’habilitat, referencia la pref:

- **Punt de partida**: {{prefs.routeOrigin}}, tret que l'usuari n'especifiqui un altre.

I guarda el valor a data/user/prefs.json:

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

El servidor substitueix els marcadors en carregar l’habilitat. Les claus imbricades ({{prefs.tunnel.domain}}) també funcionen. Les claus desconegudes es deixen tal qual perquè les errades quedin visibles.

Editant directament la base del framework

#

Si t’autoallotges i vols ajustar el framework mateix, pots editar config/agent-instructions.md, config/personality.md, skills/ o custom-tools/ directament — el servidor no t’atura si fas servir un editor de fitxers. Però l’agent no escriurà en aquestes rutes des d’una conversa. I les actualitzacions del framework sobreescriuran les teves edicions. Prefereix la capa d’usuari per a qualsevol cosa que vulguis conservar.

Estendre el Servidor

#

• Eines personalitzades — Demana a l’agent que instal·li eines CLI; aterren automàticament a data/user/custom-tools/
• Afegir habilitats — Demana a l’agent que creï una habilitat; el fitxer va a data/user/skills/
• Canviar comportament — Demana a l’agent que apliqui una regla global; s’afegeix a data/user/instructions.md
• Configurar permisos — Executa bun run permissions per controlar quines eines pot usar l’agent
• Afegir eines integrades — Implementa noves funcions d’eines a src/tools.ts per a integracions més profundes (cal fer un fork del servidor)

Configuració

#

Tots els ajustos s’emmagatzemen a .env (creat per bun run setup). Opcions principals:

Consulta la referència completa de configuració al repositori de GitHub.

Executar com a Servei

#

Instal·la com un servei persistent que s’inicia automàticament:

bun run service install

INSTANCE_NAME per defecte és el basename del directori del projecte amb el prefix pockethook- eliminat (per exemple, un checkout a pockethook-agent-server/ esdevé agent-server). Configura-ho explícitament per executar diversos checkouts a la mateixa màquina sense col·lisions — cada instància manté el seu propi data/ i logs.

Gestiona amb bun run service status, restart, stop o uninstall.

Seguretat

#

• HTTPS requerit — PocketHook exigeix HTTPS per a totes les URLs
• Autenticació per token Bearer — Secret compartit entre l’app i el servidor
• Limitació de taxa — Límits per token prevenen abusos
• Eines en sandbox — Comandes shell i accés a fitxers restringits per permisos
• Patrons bloquejats — Comandes perilloses (sudo, rm -rf /) bloquejades per defecte
• Límit de directori de treball — L’agent no pot escapar del seu directori designat
• Fitxers sensibles protegits — .env, .git, *.key, *.pem bloquejats per a l’agent
• Versionat automàtic — Tots els canvis del workspace es rastregen amb git per a una fàcil reversió