@giftsofprometheus/cli 0.5.1 → 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.
package/README.md CHANGED
@@ -109,7 +109,7 @@ npx skills add timurkhakhalev/giftsofprometheus-cli
109
109
 
110
110
  ## Команды
111
111
 
112
- С флагом `--json` любая команда печатает компактный JSON. Ошибка тогда выглядит как `{"error":{"message","status"}}`, а код выхода — 1.
112
+ С флагом `--json` любая команда печатает компактный JSON. Ошибка тогда выглядит как `{"error":{"message","status","code","nextStep"}}`, а код выхода — 1: `code` и `nextStep` приходят от сервиса, когда он их знает. После обрыва соединения или ответа 502, 503 или 504 от прокси CLI сам повторяет запрос два раза.
113
113
 
114
114
  | Команда | Что делает | Аккаунт |
115
115
  |---|---|---|
package/dist/index.js CHANGED
@@ -46,11 +46,16 @@ async function stored() {
46
46
  const value = await storedAny();
47
47
  return value !== 'unreadable' && value?.base === base ? value : null;
48
48
  }
49
+ /** `code` and `nextStep` come from the service: the code is stable, the next step says what to do about it */
49
50
  class ApiError extends Error {
50
51
  status;
51
- constructor(message, status = 1) {
52
+ code;
53
+ nextStep;
54
+ constructor(message, status = 1, code, nextStep) {
52
55
  super(message);
53
56
  this.status = status;
57
+ this.code = code;
58
+ this.nextStep = nextStep;
54
59
  }
55
60
  }
56
61
  // Server text reaches a terminal: remove control characters so a response cannot inject ANSI or OSC escape sequences
@@ -96,21 +101,48 @@ async function request(path, method = 'GET', body, authenticated = true) {
96
101
  const headers = new Headers({ 'Content-Type': 'application/json', 'X-Knowledge-Client': 'agent', 'User-Agent': `giftsofprometheus/${version}` });
97
102
  if (credential)
98
103
  headers.set('Authorization', `Bearer ${credential.token}`);
99
- const response = await fetch(target, {
100
- method,
101
- headers,
102
- redirect: 'error',
103
- signal: AbortSignal.timeout(30_000),
104
- ...(body === undefined ? {} : { body: JSON.stringify(body) }),
105
- });
106
- const data = await response.json().catch(() => ({}));
107
- if (!response.ok) {
108
- const failure = z.object({ error_description: z.string().optional(), error: z.string().optional() }).safeParse(data);
104
+ for (let attempt = 1;; attempt++) {
105
+ let response;
106
+ try {
107
+ response = await fetch(target, {
108
+ method,
109
+ headers,
110
+ redirect: 'error',
111
+ signal: AbortSignal.timeout(30_000),
112
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
113
+ });
114
+ }
115
+ catch (e) {
116
+ // A refused or reset connection never reached the service, so any method may repeat. A timeout may have, so it does not
117
+ if (attempt < RETRY_DELAYS_MS.length + 1 && !(e instanceof Error && e.name === 'TimeoutError')) {
118
+ await sleep(RETRY_DELAYS_MS[attempt - 1]);
119
+ continue;
120
+ }
121
+ throw new ApiError(`The service is unreachable: ${e instanceof Error ? e.message : 'network error'}. Try again in a minute.`);
122
+ }
123
+ const data = await response.json().catch(() => ({}));
124
+ if (response.ok)
125
+ return data;
126
+ const failure = z
127
+ .object({ error_description: z.string().optional(), error: z.string().optional(), code: z.string().optional(), nextStep: z.string().optional() })
128
+ .safeParse(data);
129
+ const code = failure.success ? failure.data.code : undefined;
130
+ // 502-504 without a service error code come from the proxy in front of the service: a restart or a dropped connection
131
+ if (GATEWAY_STATUSES.has(response.status) && code === undefined) {
132
+ if (attempt < RETRY_DELAYS_MS.length + 1) {
133
+ await sleep(RETRY_DELAYS_MS[attempt - 1]);
134
+ continue;
135
+ }
136
+ throw new ApiError(`The service is temporarily unavailable (HTTP ${response.status}). Try again in a minute.`, response.status);
137
+ }
109
138
  const message = failure.success ? failure.data.error_description || failure.data.error || `HTTP ${response.status}` : `HTTP ${response.status}`;
110
- throw new ApiError(printable(message).slice(0, 500), response.status);
139
+ const nextStep = failure.success && failure.data.nextStep ? printable(failure.data.nextStep).slice(0, 500) : undefined;
140
+ throw new ApiError(printable(message).slice(0, 500), response.status, code === undefined ? undefined : printable(code).slice(0, 100), nextStep);
111
141
  }
112
- return data;
113
142
  }
143
+ // Two repeats after a gateway error or a connection failure: a deploy switch or a dropped keep-alive connection passes in seconds
144
+ const RETRY_DELAYS_MS = [500, 1500];
145
+ const GATEWAY_STATUSES = new Set([502, 503, 504]);
114
146
  function out(value) {
115
147
  console.log(JSON.stringify(value, null, program.opts().json ? 0 : 2));
116
148
  }
@@ -136,10 +168,16 @@ function run(fn) {
136
168
  catch (e) {
137
169
  const message = e instanceof Error ? e.message : 'Unknown error';
138
170
  const status = e instanceof ApiError ? e.status : 1;
171
+ const code = e instanceof ApiError ? e.code : undefined;
172
+ // On 401 the CLI's own steps win: they say how to sign in from an agent, which the service cannot know
173
+ const nextStep = status === 401 ? SIGN_IN_STEPS : e instanceof ApiError ? e.nextStep : undefined;
139
174
  if (program.opts().json)
140
- console.log(JSON.stringify({ error: { message, status, ...(status === 401 ? { nextStep: SIGN_IN_STEPS } : {}) } }));
141
- else
175
+ console.log(JSON.stringify({ error: { message, status, ...(code ? { code } : {}), ...(nextStep ? { nextStep } : {}) } }));
176
+ else {
142
177
  console.error(printable(message));
178
+ if (nextStep)
179
+ console.error(`Next: ${printable(nextStep)}`);
180
+ }
143
181
  process.exitCode = 1;
144
182
  }
145
183
  };
@@ -488,7 +526,12 @@ talks
488
526
  .command('search')
489
527
  .argument('<query>')
490
528
  .option('--page <page>', 'page number', '1')
491
- .action(run((query, options) => request(`/api/knowledge/talks?q=${encodeURIComponent(query)}&page=${encodeURIComponent(options.page)}`)));
529
+ .action(run((query, options) => {
530
+ // The service answers an empty query with the whole catalog, which an agent would take for search results
531
+ if (!query.trim())
532
+ throw new ApiError('Empty search query. To browse the catalog, use: giftsofprometheus talks list');
533
+ return request(`/api/knowledge/talks?q=${encodeURIComponent(query)}&page=${encodeURIComponent(options.page)}`);
534
+ }));
492
535
  // The command a person typed, so a hint can be pasted back as is
493
536
  const launcher = /[\\/]_npx[\\/]/.test(packageRoot) ? 'npx @giftsofprometheus/cli' : 'giftsofprometheus';
494
537
  talks
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giftsofprometheus/cli",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "Search AI conference talks, read transcripts, and manage your Gifts of Prometheus favorites from the shell or an AI agent",
5
5
  "keywords": [
6
6
  "agents",
@@ -43,7 +43,7 @@ giftsofprometheus --json profile get # interests and curre
43
43
 
44
44
  - For questions about what speakers say, use `ask` with 2–3 formulations: English, Chinese and the original language. For names, titles, topics and conferences use `talks search`.
45
45
  - Open a found transcript with `talks content <slug> --rec-id <recId>` from the `ask` response. Summarize positions of different speakers and give the passage `url` links with timecodes.
46
- - If `ask` returns 503, try later or use `talks search`.
46
+ - If `ask` fails with code `passages_unavailable`, use `talks search`.
47
47
  - Lists are paginated: check `totalPages` and pass `--page`.
48
48
  - Search and use the returned `slug` or `id` for exact reads.
49
49
  - A transcript is in the talk's original language. Segment timecodes are in milliseconds from the start of the talk. When a talk is a part of a longer recording, `sourceRange` gives its bounds in that recording. A talk without a transcript returns an empty array.
@@ -112,4 +112,6 @@ giftsofprometheus --json profile update --interest agents=high --remove-interest
112
112
 
113
113
  ## Errors
114
114
 
115
- With `--json` a failure prints `{"error":{"message","status"}}` and exits with code 1. Status 401 means the session is missing, expired or revoked: sign in as described in Sign in and repeat the command.
115
+ With `--json` a failure prints `{"error":{"message","status","code","nextStep"}}` and exits with code 1. `code` and `nextStep` are present when the service sent them: decide by `code` (for example `talk_not_found`, `unknown_recommendation`, `rate_limited`), follow `nextStep`, and show `message` to the user as it is. Status 401 means the session is missing, expired or revoked: sign in as described in Sign in and repeat the command.
116
+
117
+ The CLI repeats a request twice by itself after a connection failure or a 502, 503 or 504 from the proxy. If it still fails with "The service is temporarily unavailable" or "The service is unreachable", tell the user in one line, wait a minute and try once more before you stop.
@@ -6,12 +6,12 @@
6
6
  },
7
7
  {
8
8
  "version": "0.1.1",
9
- "hash": "02e931c7faedd75f",
9
+ "hash": "593c1ddf1f1e1bd7",
10
10
  "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
11
11
  },
12
12
  {
13
13
  "version": "0.1.2",
14
- "hash": "02e931c7faedd75f",
14
+ "hash": "593c1ddf1f1e1bd7",
15
15
  "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
16
16
  },
17
17
  {
@@ -53,5 +53,10 @@
53
53
  "version": "0.5.1",
54
54
  "hash": "a5decd76f9054068",
55
55
  "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
56
+ },
57
+ {
58
+ "version": "0.6.0",
59
+ "hash": "04c1f4fd0b948e24",
60
+ "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
56
61
  }
57
62
  ]