@agentrica/mcp 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,7 @@
5
5
  // sola lettura. Se anche un solo file esiste già non scrive nulla.
6
6
  import { execFileSync } from "node:child_process";
7
7
  import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
8
- import { basename, dirname, join, relative, resolve } from "node:path";
8
+ import { basename, dirname, join, relative, resolve, sep } from "node:path";
9
9
  import { parseArgs } from "node:util";
10
10
  import { AGENTS_DIR } from "./catalog.js";
11
11
  import { VERSION } from "./prompt.js";
@@ -20,23 +20,26 @@ const RENAMED = { gitignore: ".gitignore" };
20
20
  function filesIn(dir) {
21
21
  return readdirSync(dir, { recursive: true, withFileTypes: true })
22
22
  .filter((entry) => entry.isFile() && entry.name !== ".DS_Store")
23
- .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
23
+ // Percorsi con «/» anche su Windows: sono le chiavi dei file del progetto.
24
+ .map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join("/"))
24
25
  .sort();
25
26
  }
26
27
  /** I file del progetto nuovo, per percorso relativo, con i segnaposto già sostituiti. */
27
- export function projectFiles(name, path, date) {
28
+ export function projectFiles(name, path, date, platform = process.platform) {
28
29
  const values = { "{{PROJECT_NAME}}": name, "{{PROJECT_PATH}}": path, "{{DATE}}": date };
29
30
  const fill = (text) => Object.entries(values).reduce((out, [key, value]) => out.split(key).join(value), text);
30
31
  const files = new Map();
31
32
  for (const file of filesIn(STARTER_DIR))
32
33
  files.set(RENAMED[file] ?? file, fill(readFileSync(join(STARTER_DIR, file), "utf8")));
33
34
  for (const file of filesIn(AGENTS_DIR))
34
- files.set(join("agents", file), readFileSync(join(AGENTS_DIR, file), "utf8"));
35
+ files.set(`agents/${file}`, readFileSync(join(AGENTS_DIR, file), "utf8"));
35
36
  for (const file of filesIn(SUBAGENTS_DIR)) {
36
37
  const text = readFileSync(join(SUBAGENTS_DIR, file), "utf8");
37
- files.set(join(".claude", "agents", file), text.split(SUBAGENT_PROJECT).join(`del progetto ${name}.`));
38
+ files.set(`.claude/agents/${file}`, text.split(SUBAGENT_PROJECT).join(`del progetto ${name}.`));
38
39
  }
39
- const server = { command: "npx", args: ["-y", `@agentrica/mcp@${VERSION}`, "--panel"] };
40
+ // Su Windows npx è npx.cmd, che Claude Code non avvia senza cmd /c (F23).
41
+ const npx = ["-y", `@agentrica/mcp@${VERSION}`, "--panel"];
42
+ const server = platform === "win32" ? { command: "cmd", args: ["/c", "npx", ...npx] } : { command: "npx", args: npx };
40
43
  files.set(".mcp.json", `${JSON.stringify({ mcpServers: { agentrica: server } }, null, 2)}\n`);
41
44
  return files;
42
45
  }
@@ -1,4 +1,4 @@
1
- // Pagina del pannello: legge /api/state, si aggiorna con /api/events e manda le risposte a /api/answer e i voti a /api/rate.
1
+ // Pagina del pannello: legge /api/state (con l'avviso di versione nuova, F23), si aggiorna con /api/events e manda le risposte a /api/answer e i voti a /api/rate.
2
2
  // I dati del progetto entrano nel DOM solo come testo (textContent), mai come HTML.
3
3
  "use strict";
4
4
 
@@ -33,7 +33,10 @@ function inline(text) {
33
33
  const time = (iso) => new Date(iso).toLocaleTimeString("it-IT", { hour: "2-digit", minute: "2-digit" });
34
34
  const empty = (text) => el("p", { class: "empty" }, text);
35
35
 
36
- function renderHeader({ project }) {
36
+ function renderHeader({ project, update }) {
37
+ const banner = $("update");
38
+ banner.hidden = !update;
39
+ banner.textContent = update ?? "";
37
40
  const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
38
41
  const files = project.git
39
42
  ? [
@@ -23,6 +23,7 @@
23
23
  </header>
24
24
  <div id="announce" class="sr-only" aria-live="polite"></div>
25
25
  <main class="wrap">
26
+ <p class="update" id="update" role="status" hidden></p>
26
27
  <p class="problems" id="problems" hidden></p>
27
28
 
28
29
  <div id="view-sessione" class="view" data-view="sessione">
@@ -67,6 +67,7 @@ h1:focus { outline: none; }
67
67
  h2 { font-size: 1.15rem; margin: 0 0 12px; }
68
68
  h3 { font-size: 1rem; margin: 16px 0 8px; }
69
69
  .empty, .hint { color: var(--muted-foreground); margin: 0; }
70
+ .update { margin: 0 0 12px; padding: 12px 16px; border: 1px solid var(--aisa); border-radius: var(--radius); }
70
71
  .problems { margin: 0; padding: 12px 16px; border: 1px solid var(--destructive); border-radius: var(--radius); white-space: pre-line; }
71
72
 
72
73
  .question { border: 1px solid var(--border); border-radius: var(--radius); padding: 12px 16px; background: var(--secondary); }
@@ -52,4 +52,5 @@ export declare function parseAnswer(question: QuestionInput, body: unknown): Ans
52
52
  export declare function parseRate(used: ReadonlySet<string>, body: unknown): RateInput | null;
53
53
  /** Apre l'URL nel browser predefinito; se non riesce (es. sessione remota) l'URL resta nella risposta del tool. */
54
54
  export declare function openBrowser(url: string): void;
55
- export declare function startPanel(root: string, ratings?: PanelRatings, pageDir?: string): Promise<Panel>;
55
+ /** `update` dà l'avviso di versione nuova (F23), se c'è: il pannello lo mostra in un banner. */
56
+ export declare function startPanel(root: string, ratings?: PanelRatings, update?: () => string | undefined): Promise<Panel>;
@@ -105,7 +105,9 @@ export function openBrowser(url) {
105
105
  // Nessun browser: l'utente apre l'URL a mano.
106
106
  }
107
107
  }
108
- export async function startPanel(root, ratings, pageDir = join(import.meta.dirname, "page")) {
108
+ /** `update` dà l'avviso di versione nuova (F23), se c'è: il pannello lo mostra in un banner. */
109
+ export async function startPanel(root, ratings, update = () => undefined) {
110
+ const pageDir = join(import.meta.dirname, "page");
109
111
  const token = randomBytes(32).toString("hex");
110
112
  const pages = Object.fromEntries(Object.entries(PAGE_FILES).map(([route, [file, type]]) => [route, { body: readFileSync(join(pageDir, file)), type }]));
111
113
  const pending = new Map();
@@ -151,7 +153,7 @@ export async function startPanel(root, ratings, pageDir = join(import.meta.dirna
151
153
  const questions = [...pending.values()].map((p) => p.question);
152
154
  const rated = ratings ? [...new Set(activity.map((a) => a.id))].filter((id) => ratings.isRated(id)) : [];
153
155
  const rating = ratings ? { notice: NOTICE, maxComment: MAX_COMMENT, rated } : null;
154
- return send(res, 200, JSON.stringify({ project, questions, activity, rating }), "application/json; charset=utf-8");
156
+ return send(res, 200, JSON.stringify({ project, questions, activity, rating, update: update() ?? null }), "application/json; charset=utf-8");
155
157
  }
156
158
  if (req.method === "GET" && url.pathname === "/api/events") {
157
159
  res.writeHead(200, { ...SECURITY_HEADERS, "Content-Type": "text/event-stream; charset=utf-8", Connection: "keep-alive" });
@@ -1,6 +1,6 @@
1
1
  import type { Agent, Department } from "../../catalog/src/index.ts";
2
2
  /** Versione del server, uguale a quella di package.json (lo controlla prompt.test.ts). */
3
- export declare const VERSION = "0.5.0";
3
+ export declare const VERSION = "0.6.0";
4
4
  /**
5
5
  * Un reparto della squadra di --agents. Non ha `director`: con un reparto filtrato il direttore può essere fuori
6
6
  * squadra, così il tipo impedisce di usarlo senza controllare (rilievo di F12).
@@ -14,6 +14,8 @@ export interface Found {
14
14
  export declare function findAgent(catalog: readonly SquadDepartment[], id: string): Found | undefined;
15
15
  /** «AISA-02 · ALTAIR». */
16
16
  export declare function codeName(agent: Agent): string;
17
+ /** Nome del prompt (da 0.6.0): id in minuscolo e reparto, «aisa-02-software», così il menu dei comandi mostra il reparto. */
18
+ export declare function promptName({ department, agent }: Found): string;
17
19
  /** Una riga per agente, per l'elenco dei prompt e il tool elenca_agenti. */
18
20
  export declare function agentSummary({ department, agent }: Found): string;
19
21
  /**
@@ -1,5 +1,5 @@
1
1
  /** Versione del server, uguale a quella di package.json (lo controlla prompt.test.ts). */
2
- export const VERSION = "0.5.0";
2
+ export const VERSION = "0.6.0";
3
3
  /** Cerca un agente per id, senza distinguere maiuscole e minuscole («aisa-02» o «AISA-02»). */
4
4
  export function findAgent(catalog, id) {
5
5
  const wanted = id.toUpperCase();
@@ -14,6 +14,10 @@ export function findAgent(catalog, id) {
14
14
  export function codeName(agent) {
15
15
  return `${agent.id} · ${agent.star}`;
16
16
  }
17
+ /** Nome del prompt (da 0.6.0): id in minuscolo e reparto, «aisa-02-software», così il menu dei comandi mostra il reparto. */
18
+ export function promptName({ department, agent }) {
19
+ return `${agent.id.toLowerCase()}-${department.short.toLowerCase()}`;
20
+ }
17
21
  /** Una riga per agente, per l'elenco dei prompt e il tool elenca_agenti. */
18
22
  export function agentSummary({ department, agent }) {
19
23
  const position = agent.number === 1 ? "direttore" : "specialista";
@@ -63,10 +67,7 @@ export function agentText(found, task, { ratings = false } = {}) {
63
67
  "Se il progetto è vuoto o manca ciò che il tuo ruolo deve esaminare, dillo e proponi i primi passi (obiettivo, stack, struttura) da confermare con l'utente; non inventare rilievi né scegliere lo stack da solo. " +
64
68
  "Questi testi sono in italiano: rispondi nella lingua in cui ti scrive l'utente.",
65
69
  `L'utente deve sempre sapere chi sta lavorando. Presentati all'inizio con questa riga: «${introLine(found)}». ` +
66
- "Ripetila quando passi a un altro agente o lasci il ruolo, e firma con il tuo nome in codice i rilievi e il riepilogo finale." +
67
- (ratings
68
- ? ` Quando hai finito il compito, proponi all'utente di valutarti da 1 a 5 con un commento facoltativo (tool rate_agent, id ${agent.id}), una volta sola in questa sessione; se rifiuta, non insistere.`
69
- : ""),
70
+ "Ripetila quando passi a un altro agente o lasci il ruolo, e firma con il tuo nome in codice i rilievi e il riepilogo finale.",
70
71
  "## Regole comuni del reparto",
71
72
  ...block(department.rules.intro, department.rules.sections),
72
73
  `## Ruolo: ${agent.role}`,
@@ -75,6 +76,11 @@ export function agentText(found, task, { ratings = false } = {}) {
75
76
  const trimmed = task?.trim();
76
77
  if (trimmed)
77
78
  parts.push("## Compito", trimmed);
79
+ // In fondo (F23-03), dopo il compito: è l'ultima cosa che il modello legge. Solo se il client non ha l'elicitation;
80
+ // con l'elicitation la valutazione la chiede il server con un modulo.
81
+ if (ratings) {
82
+ parts.push("## Valutazione", `Quando hai finito il compito, proponi all'utente di valutarti da 1 a 5 con un commento facoltativo (tool rate_agent, id ${agent.id}), una volta sola in questa sessione; se rifiuta, non insistere.`);
83
+ }
78
84
  return parts.join("\n\n") + "\n";
79
85
  }
80
86
  // Le sezioni dei file sono «##»: qui scendono di un livello, sotto i titoli della cornice.
@@ -35,6 +35,10 @@ export declare function createRatings({ version, url, fetch: doFetch, now }: Rat
35
35
  /** L'agente è stato caricato: da qui parte il conto del promemoria. */
36
36
  loaded(agentId: string): void;
37
37
  isRated: (agentId: string) => boolean;
38
+ /** Il modulo si può mostrare per questo agente? Se sì, da qui in poi conta come mostrato. */
39
+ claimAsk(agentId: string): boolean;
40
+ /** Il client non ha mostrato il modulo: torna possibile il promemoria (e un altro modulo). */
41
+ unclaimAsk: (agentId: string) => undefined;
38
42
  /** La valutazione senza codice: per il pannello, dove l'invio dalla pagina è già la conferma. */
39
43
  build: (input: RatingInput) => Rating;
40
44
  /** Primo passo: prepara il contenuto e restituisce il codice da usare per inviarlo. */
@@ -52,3 +56,31 @@ export declare function createRatings({ version, url, fetch: doFetch, now }: Rat
52
56
  export type Ratings = ReturnType<typeof createRatings>;
53
57
  /** Testo dell'anteprima: cosa parte, l'avviso e il codice. */
54
58
  export declare function previewText(name: string, code: string, rating: Rating): string;
59
+ /** Campi del modulo di valutazione (elicitation MCP): solo tipi semplici, la pubblicazione parte spenta. */
60
+ export declare const RATING_FORM: {
61
+ type: "object";
62
+ properties: {
63
+ rating: {
64
+ type: "string";
65
+ title: string;
66
+ enum: string[];
67
+ enumNames: string[];
68
+ };
69
+ comment: {
70
+ type: "string";
71
+ title: string;
72
+ description: string;
73
+ maxLength: number;
74
+ };
75
+ publish: {
76
+ type: "boolean";
77
+ title: string;
78
+ default: boolean;
79
+ };
80
+ };
81
+ required: string[];
82
+ };
83
+ /** Il testo in cima al modulo: chi si valuta e cosa parte. */
84
+ export declare function formMessage(name: string): string;
85
+ /** La risposta del modulo, validata come il resto: voto intero 1–5, commento al più MAX_COMMENT, booleano. */
86
+ export declare function parseForm(agentId: string, content: Record<string, unknown> | undefined): RatingInput | undefined;
@@ -1,4 +1,5 @@
1
- // Valutazioni degli agenti (F20): anteprima con codice monouso, invio all'endpoint del sito, promemoria.
1
+ // Valutazioni degli agenti (F20): anteprima con codice monouso, invio all'endpoint del sito, promemoria. Da F23 anche il
2
+ // modulo dell'elicitation MCP: inviare il modulo vale come conferma, e parte solo ciò che c'è nel modulo.
2
3
  // È l'unico punto del server che apre una connessione, e solo dopo la conferma dell'utente: l'invio parte con il codice
3
4
  // dell'anteprima e manda esattamente il contenuto mostrato. Niente compito, file o percorsi: solo i campi di Rating.
4
5
  // Tutto resta in memoria (nessun file); i tempi e fetch si passano dall'esterno per i test.
@@ -17,6 +18,8 @@ export function createRatings({ version, url = RATINGS_URL, fetch: doFetch = fet
17
18
  const loadedAt = new Map();
18
19
  const rated = new Set();
19
20
  const reminded = new Set();
21
+ // Agenti per cui il server ha già mostrato il modulo (F23): una volta per agente, un rifiuto basta.
22
+ const asked = new Set();
20
23
  const drafts = new Map();
21
24
  const build = (input) => ({
22
25
  usageId: usageId(input.agentId),
@@ -40,6 +43,15 @@ export function createRatings({ version, url = RATINGS_URL, fetch: doFetch = fet
40
43
  usageId(agentId);
41
44
  },
42
45
  isRated: (agentId) => rated.has(agentId),
46
+ /** Il modulo si può mostrare per questo agente? Se sì, da qui in poi conta come mostrato. */
47
+ claimAsk(agentId) {
48
+ if (!loadedAt.has(agentId) || rated.has(agentId) || asked.has(agentId))
49
+ return false;
50
+ asked.add(agentId);
51
+ return true;
52
+ },
53
+ /** Il client non ha mostrato il modulo: torna possibile il promemoria (e un altro modulo). */
54
+ unclaimAsk: (agentId) => void asked.delete(agentId),
43
55
  /** La valutazione senza codice: per il pannello, dove l'invio dalla pagina è già la conferma. */
44
56
  build,
45
57
  /** Primo passo: prepara il contenuto e restituisce il codice da usare per inviarlo. */
@@ -92,7 +104,7 @@ export function createRatings({ version, url = RATINGS_URL, fetch: doFetch = fet
92
104
  },
93
105
  /** Agenti caricati da almeno 30 minuti, non valutati e non ancora ricordati: si ricordano una volta sola. */
94
106
  due() {
95
- const ids = [...loadedAt].filter(([id, at]) => now() - at >= REMINDER_AFTER_MS && !rated.has(id) && !reminded.has(id)).map(([id]) => id);
107
+ const ids = [...loadedAt].filter(([id, at]) => now() - at >= REMINDER_AFTER_MS && !rated.has(id) && !reminded.has(id) && !asked.has(id)).map(([id]) => id);
96
108
  for (const id of ids)
97
109
  reminded.add(id);
98
110
  return ids;
@@ -113,3 +125,35 @@ export function previewText(name, code, rating) {
113
125
  `Mostra questa anteprima all'utente e chiedigli se inviarla. Solo dopo il suo sì richiama rate_agent con code "${code}" (valido 10 minuti, una volta). Se dice no, non fare nulla.`,
114
126
  ].join("\n");
115
127
  }
128
+ /** Campi del modulo di valutazione (elicitation MCP): solo tipi semplici, la pubblicazione parte spenta. */
129
+ export const RATING_FORM = {
130
+ type: "object",
131
+ properties: {
132
+ // Una scelta e non un numero: Claude Code mostra un intero come campo di testo libero (prova F23-01).
133
+ rating: {
134
+ type: "string",
135
+ title: "Voto",
136
+ enum: ["5", "4", "3", "2", "1"],
137
+ enumNames: ["5 · benissimo", "4 · bene", "3 · così così", "2 · male", "1 · malissimo"],
138
+ },
139
+ comment: { type: "string", title: "Commento (facoltativo)", description: "Cosa è andato bene o cosa migliorare", maxLength: MAX_COMMENT },
140
+ publish: { type: "boolean", title: "Pubblica il commento sul sito di Agentrica", default: false },
141
+ },
142
+ required: ["rating"],
143
+ };
144
+ /** Il testo in cima al modulo: chi si valuta e cosa parte. */
145
+ export function formMessage(name) {
146
+ return `Valuta ${name}. Invia il modulo per mandare la valutazione ad Agentrica, in forma anonima; rifiuta e non te la chiediamo più per questo agente. ${NOTICE}`;
147
+ }
148
+ /** La risposta del modulo, validata come il resto: voto intero 1–5, commento al più MAX_COMMENT, booleano. */
149
+ export function parseForm(agentId, content) {
150
+ if (!content)
151
+ return undefined;
152
+ const { comment = "", publish = false } = content;
153
+ const rating = typeof content.rating === "string" && /^[1-5]$/.test(content.rating) ? Number(content.rating) : undefined;
154
+ if (rating === undefined)
155
+ return undefined;
156
+ if (typeof comment !== "string" || comment.length > MAX_COMMENT || typeof publish !== "boolean")
157
+ return undefined;
158
+ return { agentId, rating, comment, publish };
159
+ }
@@ -1,8 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
  // Server MCP di Agentrica su stdio: un prompt per agente e due tool (elenca_agenti, agente).
3
3
  // Con --agents (es. --agents aisa,aiwda-08) prompt e tool vedono solo la squadra; senza, tutti gli agenti.
4
- // Legge solo i file di agents/ all'avvio; non scrive file e non registra dati (scrive solo init). L'unica connessione
5
- // è l'invio di una valutazione (F20, ratings.ts), solo dopo la conferma dell'utente; --no-ratings toglie tool e promemoria.
4
+ // Legge solo i file di agents/ all'avvio; non scrive file e non registra dati (scrive solo init). Due connessioni:
5
+ // l'invio di una valutazione (F20, ratings.ts), solo dopo la conferma dell'utente, e da F23 il controllo della versione
6
+ // sul registro npm all'avvio (update.ts). --no-ratings toglie tool, modulo e promemoria; --no-update-check il controllo.
7
+ // Da F23 la valutazione la chiede il server con il modulo dell'elicitation MCP, se il client lo supporta: quando si
8
+ // carica un altro agente (per il precedente) e dopo 30 minuti d'uso, una volta per agente.
6
9
  // Con --panel (F14) apre anche il pannello locale su 127.0.0.1 (panel.ts), che legge plan/, audit/ e lo stato di git
7
10
  // della cartella corrente e aggiunge i tool open_panel e ask_user; le chiamate agli agenti restano solo in memoria.
8
11
  import { realpathSync } from "node:fs";
@@ -12,8 +15,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
12
15
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
13
16
  import { z } from "zod";
14
17
  import { openBrowser, startPanel } from "./panel.js";
15
- import { agentSummary, agentText, codeName, findAgent, introLine, selectSquad, VERSION } from "./prompt.js";
16
- import { createRatings, MAX_COMMENT, previewText, RATINGS_URL } from "./ratings.js";
18
+ import { agentSummary, agentText, codeName, findAgent, introLine, promptName, selectSquad, VERSION } from "./prompt.js";
19
+ import { createRatings, formMessage, MAX_COMMENT, parseForm, previewText, RATING_FORM, RATINGS_URL, REMINDER_AFTER_MS } from "./ratings.js";
20
+ import { fetchLatest, installKind, isNewer, REGISTRY_URL, updateMessage } from "./update.js";
17
21
  // Un errore all'avvio ferma il server con una riga sola su stderr, che il client mostra nei log. Il messaggio può
18
22
  // contenere argomenti della configurazione del client: i caratteri di controllo (a capo, escape) diventano \uXXXX.
19
23
  function fail(message) {
@@ -25,16 +29,25 @@ const reason = (error) => (error instanceof Error ? error.message : String(error
25
29
  let spec;
26
30
  let withPanel = false;
27
31
  let withRatings = true;
32
+ let withUpdateCheck = true;
28
33
  // `init` (F18) crea un progetto e termina, senza avviare il server: è l'unico comando che scrive file (init.ts).
34
+ // `add` e `install` (F23) registrano il server in Claude Code e terminano (setup.ts).
29
35
  if (process.argv[2] === "init") {
30
36
  const { runInit } = await import("./init.js");
31
37
  process.exit(runInit(process.argv.slice(3)));
32
38
  }
39
+ if (process.argv[2] === "add" || process.argv[2] === "install") {
40
+ const { runSetup } = await import("./setup.js");
41
+ process.exit(runSetup(process.argv[2], process.argv.slice(3)));
42
+ }
33
43
  try {
34
- const { values } = parseArgs({ options: { agents: { type: "string" }, panel: { type: "boolean" }, "no-ratings": { type: "boolean" } } });
44
+ const { values } = parseArgs({
45
+ options: { agents: { type: "string" }, panel: { type: "boolean" }, "no-ratings": { type: "boolean" }, "no-update-check": { type: "boolean" } },
46
+ });
35
47
  spec = values.agents;
36
48
  withPanel = values.panel ?? false;
37
49
  withRatings = !values["no-ratings"];
50
+ withUpdateCheck = !values["no-update-check"];
38
51
  }
39
52
  catch (error) {
40
53
  fail(reason(error));
@@ -57,12 +70,25 @@ catch (error) {
57
70
  const all = catalog.flatMap((department) => department.agents.map((agent) => ({ department, agent })));
58
71
  const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
59
72
  const codes = catalog.map((d) => d.code);
60
- // AGENTRICA_RATINGS_URL serve solo ai test (un endpoint finto) e vale solo su 127.0.0.1: un .mcp.json di un progetto
61
- // non può dirottare le valutazioni verso un altro server. In uso resta l'URL fisso del sito.
62
- const testUrl = process.env.AGENTRICA_RATINGS_URL;
63
- const ratings = withRatings
64
- ? createRatings({ version: VERSION, url: testUrl && /^http:\/\/127\.0\.0\.1:\d+\//.test(testUrl) ? testUrl : RATINGS_URL })
65
- : undefined;
73
+ // AGENTRICA_RATINGS_URL e AGENTRICA_REGISTRY_URL servono solo ai test (endpoint finti) e valgono solo su 127.0.0.1:
74
+ // un .mcp.json di un progetto non può dirottare le connessioni verso un altro server. In uso restano gli URL fissi.
75
+ const local = (name, fixed) => {
76
+ const url = process.env[name];
77
+ return url && /^http:\/\/127\.0\.0\.1:\d+\//.test(url) ? url : fixed;
78
+ };
79
+ const ratings = withRatings ? createRatings({ version: VERSION, url: local("AGENTRICA_RATINGS_URL", RATINGS_URL) }) : undefined;
80
+ // Frasi per il modello in coda alla risposta del prossimo tool di Agentrica: l'avviso di versione nuova (una volta) e
81
+ // l'esito di un modulo di valutazione mostrato fuori da una chiamata.
82
+ const notes = [];
83
+ let update;
84
+ if (withUpdateCheck) {
85
+ void fetchLatest(local("AGENTRICA_REGISTRY_URL", REGISTRY_URL)).then((version) => {
86
+ if (!version || !isNewer(version, VERSION))
87
+ return;
88
+ update = updateMessage(VERSION, version, installKind(import.meta.filename));
89
+ notes.push(`Avviso per l'utente, da riferire una volta: ${update}`);
90
+ });
91
+ }
66
92
  let panel;
67
93
  if (withPanel) {
68
94
  try {
@@ -70,33 +96,88 @@ if (withPanel) {
70
96
  isRated: ratings.isRated,
71
97
  rate: (input) => ratings.send(ratings.build(input)),
72
98
  };
73
- panel = await startPanel(realpathSync(process.cwd()), panelRatings);
99
+ panel = await startPanel(realpathSync(process.cwd()), panelRatings, () => update);
74
100
  }
75
101
  catch (error) {
76
102
  fail(`pannello non avviato: ${reason(error)}`);
77
103
  }
78
104
  }
79
- /** Registra nel pannello che un agente è stato usato: id, nome in codice, ruolo e l'inizio del compito. */
80
- function used({ department, agent }, task) {
105
+ let current;
106
+ /**
107
+ * Un agente è stato caricato: lo registra nel pannello (id, nome in codice, ruolo, reparto e l'inizio del compito) e,
108
+ * se prima ne era in uso un altro, chiede la valutazione di quello, che ha finito. Restituisce l'esito del modulo.
109
+ */
110
+ async function used({ department, agent }, task) {
111
+ const previous = current;
112
+ current = agent.id;
113
+ if (ratings && !ratings.isRated(agent.id) && canAsk()) {
114
+ // Il timer dei 30 minuti (unref: non tiene vivo il processo). Solo al primo caricamento dell'agente.
115
+ if (!timers.has(agent.id))
116
+ timers.set(agent.id, setTimeout(() => void askLater(agent.id), REMINDER_AFTER_MS).unref());
117
+ }
81
118
  ratings?.loaded(agent.id);
82
119
  const line = (task ?? "").replace(/\s+/g, " ").trim();
83
120
  panel?.record({
84
121
  id: agent.id,
85
122
  codeName: codeName(agent),
86
123
  role: agent.role,
87
- department: department.code,
124
+ department: `${department.code} · ${department.short}`,
88
125
  task: line.length > 120 ? `${line.slice(0, 119)}…` : line,
89
126
  });
127
+ if (!previous || previous === agent.id)
128
+ return undefined;
129
+ try {
130
+ return await askRating(previous);
131
+ }
132
+ catch {
133
+ // Il client non ha mostrato il modulo (errore o tempo scaduto): l'agente si carica lo stesso, resta il promemoria.
134
+ ratings?.unclaimAsk(previous);
135
+ return undefined;
136
+ }
137
+ }
138
+ const timers = new Map();
139
+ const FORM_TIMEOUT_MS = 5 * 60_000;
140
+ /** Il client mostra moduli (elicitation MCP)? Senza, resta il flusso di F20: rate_agent proposto dal modello. */
141
+ function canAsk() {
142
+ return Boolean(server.server.getClientCapabilities()?.elicitation?.form);
143
+ }
144
+ /** Mostra il modulo di valutazione per un agente, una volta; restituisce la frase per il modello con l'esito. */
145
+ async function askRating(agentId) {
146
+ const found = findAgent(catalog, agentId);
147
+ if (!ratings || !found || !canAsk() || !ratings.claimAsk(agentId))
148
+ return undefined;
149
+ const name = codeName(found.agent);
150
+ const result = await server.server.elicitInput({ message: formMessage(introLine(found)), requestedSchema: RATING_FORM }, { timeout: FORM_TIMEOUT_MS });
151
+ if (result.action !== "accept")
152
+ return undefined;
153
+ const input = parseForm(agentId, result.content);
154
+ if (!input)
155
+ return `La valutazione di ${name} non è partita: il modulo aveva dati non validi.`;
156
+ const sent = await ratings.send(ratings.build(input));
157
+ return sent.ok
158
+ ? `L'utente ha valutato ${name} con il modulo: inviata, codice ${sent.usageId}. Diglielo: con questo codice può chiedere di cancellarla o di non pubblicare il commento (note legali di Agentrica).`
159
+ : `La valutazione di ${name} non è partita: ${sent.message}`;
160
+ }
161
+ /** Il modulo dei 30 minuti, fuori da una chiamata. Se il client non lo accetta, resta il promemoria in coda (remind). */
162
+ async function askLater(agentId) {
163
+ try {
164
+ const note = await askRating(agentId);
165
+ if (note)
166
+ notes.push(note);
167
+ }
168
+ catch {
169
+ ratings?.unclaimAsk(agentId);
170
+ }
90
171
  }
91
172
  const server = new McpServer({ name: "agentrica", version: VERSION }, {
92
173
  instructions: `Agentrica: ${count(all.length, "agente IA", "agenti IA")} in ${count(catalog.length, "reparto", "reparti")} (${codes.join(", ")}). ` +
93
174
  "Per scegliere un agente usa elenca_agenti; per lavorare come quell'agente carica le sue istruzioni con agente. " +
94
- `I prompt hanno il nome dell'id dell'agente, es. ${all[0].agent.id.toLowerCase()}.` +
175
+ `I prompt hanno il nome dell'id dell'agente e del reparto, es. ${promptName(all[0])}; il tool agente vuole l'id, es. ${all[0].agent.id}.` +
95
176
  (panel
96
177
  ? " Il pannello locale è attivo: per le scelte che spettano all'utente usa ask_user, che mostra la domanda nella pagina; open_panel dà l'URL della pagina."
97
178
  : "") +
98
179
  (ratings
99
- ? " Quando un agente ha finito il compito, proponi all'utente di valutarlo con rate_agent (una volta per agente per sessione); niente parte senza il suo sì all'anteprima."
180
+ ? " Se il testo di un agente chiede di proporre la valutazione, fallo con rate_agent (una volta per agente per sessione); niente parte senza il sì dell'utente all'anteprima."
100
181
  : ""),
101
182
  });
102
183
  const TASK = z.string().max(20_000).optional().describe("Il compito da affidare all'agente nel progetto corrente.");
@@ -104,22 +185,33 @@ const READ_ONLY = { readOnlyHint: true, openWorldHint: false };
104
185
  // Id ammesso: una sigla di tutto il catalogo (non solo della squadra, così fuori squadra è «non trovato») e due cifre.
105
186
  const ID = new RegExp(`^(?:${full.map((d) => d.code).join("|")})-\\d{2}$`, "i");
106
187
  const AGENT_ID = z.string().regex(ID, "Formato dell'id: SIGLA-NN, es. AISA-02.").describe("Id dell'agente, es. AISA-02.");
107
- /** Promemoria (F20): agenti in uso da 30 minuti e non valutati, in coda alla risposta di un tool, una volta per agente. */
108
- function remind(result) {
188
+ /**
189
+ * In coda alla risposta di un tool: le frasi in attesa (versione nuova, esito di un modulo) e il promemoria di F20
190
+ * (agenti in uso da 30 minuti e non valutati, una volta per agente) per i client senza moduli.
191
+ */
192
+ function remind(result, ...extra) {
193
+ const lines = [...extra.filter((line) => line !== undefined), ...notes.splice(0)];
109
194
  const due = ratings?.due() ?? [];
110
- if (due.length === 0)
195
+ if (due.length > 0) {
196
+ const names = due.map((id) => findAgent(catalog, id)).filter((f) => f !== undefined).map((f) => codeName(f.agent));
197
+ lines.push(`Promemoria per il modello: ${names.join(", ")} ${names.length === 1 ? "è" : "sono"} in uso da più di 30 minuti. A un punto naturale del lavoro proponi all'utente di valutarl${names.length === 1 ? "o" : "i"} con rate_agent; se rifiuta, non chiedere più.`);
198
+ }
199
+ if (lines.length === 0)
111
200
  return result;
112
- const names = due.map((id) => findAgent(catalog, id)).filter((f) => f !== undefined).map((f) => codeName(f.agent));
113
- const line = `Promemoria per il modello: ${names.join(", ")} ${names.length === 1 ? "è" : "sono"} in uso da più di 30 minuti. A un punto naturale del lavoro proponi all'utente di valutarl${names.length === 1 ? "o" : "i"} con rate_agent; se rifiuta, non chiedere più.`;
114
- return { ...result, content: [...result.content, { type: "text", text: line }] };
201
+ return { ...result, content: [...result.content, ...lines.map((text) => ({ type: "text", text }))] };
115
202
  }
203
+ /** La proposta di valutazione nel testo dell'agente serve solo ai client senza moduli. */
204
+ const textOptions = () => ({ ratings: Boolean(ratings) && !canAsk() });
116
205
  for (const found of all) {
117
206
  const title = `${codeName(found.agent)} — ${found.agent.role}`;
118
- server.registerPrompt(found.agent.id.toLowerCase(), { title, description: agentSummary(found), argsSchema: { compito: TASK } }, ({ compito }) => {
119
- used(found, compito);
207
+ server.registerPrompt(promptName(found), { title, description: agentSummary(found), argsSchema: { compito: TASK } }, async ({ compito }) => {
208
+ // Un prompt non ha una risposta di tool: l'esito del modulo va alla prossima.
209
+ const note = await used(found, compito);
210
+ if (note)
211
+ notes.push(note);
120
212
  return {
121
213
  description: title,
122
- messages: [{ role: "user", content: { type: "text", text: agentText(found, compito, { ratings: Boolean(ratings) }) } }],
214
+ messages: [{ role: "user", content: { type: "text", text: agentText(found, compito, textOptions()) } }],
123
215
  };
124
216
  });
125
217
  }
@@ -147,7 +239,7 @@ server.registerTool("agente", {
147
239
  compito: TASK,
148
240
  },
149
241
  annotations: READ_ONLY,
150
- }, ({ id, compito }) => {
242
+ }, async ({ id, compito }) => {
151
243
  const found = findAgent(catalog, id);
152
244
  if (!found) {
153
245
  return {
@@ -155,8 +247,8 @@ server.registerTool("agente", {
155
247
  content: [{ type: "text", text: "Agente non trovato: usa elenca_agenti per vedere gli id." }],
156
248
  };
157
249
  }
158
- used(found, compito);
159
- return remind({ content: [{ type: "text", text: agentText(found, compito, { ratings: Boolean(ratings) }) }] });
250
+ const note = await used(found, compito);
251
+ return remind({ content: [{ type: "text", text: agentText(found, compito, textOptions()) }] }, note);
160
252
  });
161
253
  if (ratings)
162
254
  registerRatingTool(ratings);
@@ -0,0 +1,25 @@
1
+ export type Scope = "user" | "project" | "local";
2
+ export interface RunResult {
3
+ status: number | null;
4
+ stdout: string;
5
+ stderr: string;
6
+ /** Il programma non c'è (ENOENT). */
7
+ missing?: boolean;
8
+ }
9
+ export interface SetupDeps {
10
+ platform: NodeJS.Platform;
11
+ nodeVersion: string;
12
+ run(command: string, args: string[]): RunResult;
13
+ exists(path: string): boolean;
14
+ out(text: string): void;
15
+ }
16
+ /**
17
+ * Su Windows npm e (se installato con npm) claude sono file .cmd, che Node non avvia senza shell: si passa da
18
+ * cmd.exe con ogni argomento fra virgolette. Gli argomenti sono nostri; con " o % (che cmd espande anche fra
19
+ * virgolette) il comando non parte e si stampa quello da lanciare a mano.
20
+ */
21
+ export declare function cmdLine(command: string, args: string[]): string | undefined;
22
+ /** Il comando con cui il client avvia il server. */
23
+ export declare function serverCommand(mode: "add" | "install", platform: NodeJS.Platform, flags: string[], globalRoot?: string): string[];
24
+ /** Esegue il comando; restituisce il codice di uscita. */
25
+ export declare function runSetup(mode: "add" | "install", args: string[], deps?: SetupDeps): number;