@tellagen/mcp-server 0.4.1 → 0.5.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.
Files changed (180) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +335 -102
  3. package/SKILL.md +183 -27
  4. package/contracts/mcp-protocol.json +155 -0
  5. package/contracts/runbooks/manifest.json +26 -6
  6. package/contracts/runbooks/v2/cause-lead.guidance.json +37 -0
  7. package/contracts/runbooks/v2/client-protocol.json +926 -0
  8. package/contracts/runbooks/v2/client-writes.guidance.json +42 -0
  9. package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +30 -5
  10. package/contracts/runbooks/v2/result-summary.guidance.json +21 -0
  11. package/contracts/runbooks/v2/timeline-event-blocks.schema.json +18 -11
  12. package/contracts/tellagen-runbook-contracts.json +4 -4
  13. package/dist/active-run.d.ts +29 -0
  14. package/dist/active-run.js +67 -0
  15. package/dist/active-run.js.map +1 -0
  16. package/dist/bootstrap.d.ts +20 -0
  17. package/dist/bootstrap.js +29 -0
  18. package/dist/bootstrap.js.map +1 -0
  19. package/dist/cause-lead.d.ts +25 -0
  20. package/dist/cause-lead.js +145 -0
  21. package/dist/cause-lead.js.map +1 -0
  22. package/dist/cli/auth.d.ts +22 -0
  23. package/dist/cli/auth.js +207 -0
  24. package/dist/cli/auth.js.map +1 -0
  25. package/dist/cli/io.d.ts +16 -0
  26. package/dist/cli/io.js +53 -0
  27. package/dist/cli/io.js.map +1 -0
  28. package/dist/cli/listen-guard.d.ts +12 -0
  29. package/dist/cli/listen-guard.js +50 -0
  30. package/dist/cli/listen-guard.js.map +1 -0
  31. package/dist/cli/listen.d.ts +28 -0
  32. package/dist/cli/listen.js +205 -0
  33. package/dist/cli/listen.js.map +1 -0
  34. package/dist/cli/main.d.ts +3 -0
  35. package/dist/cli/main.js +53 -0
  36. package/dist/cli/main.js.map +1 -0
  37. package/dist/cli/trace-hook.d.ts +23 -0
  38. package/dist/cli/trace-hook.js +99 -0
  39. package/dist/cli/trace-hook.js.map +1 -0
  40. package/dist/client.d.ts +92 -6
  41. package/dist/client.js +300 -23
  42. package/dist/client.js.map +1 -1
  43. package/dist/config.d.ts +17 -0
  44. package/dist/config.js +38 -0
  45. package/dist/config.js.map +1 -0
  46. package/dist/credentials.d.ts +120 -0
  47. package/dist/credentials.js +363 -0
  48. package/dist/credentials.js.map +1 -0
  49. package/dist/diagnosis-structure.d.ts +207 -147
  50. package/dist/diagnosis-structure.js +143 -2
  51. package/dist/diagnosis-structure.js.map +1 -1
  52. package/dist/diff-figure.d.ts +56 -0
  53. package/dist/diff-figure.js +276 -0
  54. package/dist/diff-figure.js.map +1 -0
  55. package/dist/errors.d.ts +21 -0
  56. package/dist/errors.js +60 -0
  57. package/dist/errors.js.map +1 -1
  58. package/dist/figures.d.ts +281 -201
  59. package/dist/figures.js +189 -47
  60. package/dist/figures.js.map +1 -1
  61. package/dist/guide-resources.d.ts +28 -0
  62. package/dist/guide-resources.js +81 -0
  63. package/dist/guide-resources.js.map +1 -0
  64. package/dist/heartbeat.d.ts +24 -0
  65. package/dist/heartbeat.js +94 -0
  66. package/dist/heartbeat.js.map +1 -0
  67. package/dist/home.d.ts +8 -0
  68. package/dist/home.js +14 -0
  69. package/dist/home.js.map +1 -0
  70. package/dist/identity.d.ts +32 -0
  71. package/dist/identity.js +83 -0
  72. package/dist/identity.js.map +1 -0
  73. package/dist/index.js +46 -14
  74. package/dist/index.js.map +1 -1
  75. package/dist/listen-config.d.ts +67 -0
  76. package/dist/listen-config.js +83 -0
  77. package/dist/listen-config.js.map +1 -0
  78. package/dist/listen-probe.d.ts +57 -0
  79. package/dist/listen-probe.js +158 -0
  80. package/dist/listen-probe.js.map +1 -0
  81. package/dist/listen-rules.d.ts +88 -0
  82. package/dist/listen-rules.js +252 -0
  83. package/dist/listen-rules.js.map +1 -0
  84. package/dist/listen-settings.d.ts +18 -0
  85. package/dist/listen-settings.js +50 -0
  86. package/dist/listen-settings.js.map +1 -0
  87. package/dist/listen-wrap.d.ts +21 -0
  88. package/dist/listen-wrap.js +52 -0
  89. package/dist/listen-wrap.js.map +1 -0
  90. package/dist/listener.d.ts +195 -0
  91. package/dist/listener.js +600 -0
  92. package/dist/listener.js.map +1 -0
  93. package/dist/open-run.d.ts +2 -0
  94. package/dist/open-run.js +5 -0
  95. package/dist/open-run.js.map +1 -0
  96. package/dist/prompts.d.ts +12 -0
  97. package/dist/prompts.js +37 -0
  98. package/dist/prompts.js.map +1 -0
  99. package/dist/redact.d.ts +13 -0
  100. package/dist/redact.js +76 -0
  101. package/dist/redact.js.map +1 -0
  102. package/dist/run-events.d.ts +54 -0
  103. package/dist/run-events.js +210 -0
  104. package/dist/run-events.js.map +1 -0
  105. package/dist/run-state.d.ts +184 -0
  106. package/dist/run-state.js +207 -0
  107. package/dist/run-state.js.map +1 -0
  108. package/dist/server.d.ts +22 -2
  109. package/dist/server.js +137 -29
  110. package/dist/server.js.map +1 -1
  111. package/dist/session.d.ts +86 -0
  112. package/dist/session.js +155 -0
  113. package/dist/session.js.map +1 -0
  114. package/dist/shell-rules.d.ts +49 -0
  115. package/dist/shell-rules.js +335 -0
  116. package/dist/shell-rules.js.map +1 -0
  117. package/dist/signin-index.d.ts +164 -0
  118. package/dist/signin-index.js +116 -0
  119. package/dist/signin-index.js.map +1 -0
  120. package/dist/signin.d.ts +169 -0
  121. package/dist/signin.js +541 -0
  122. package/dist/signin.js.map +1 -0
  123. package/dist/start.d.ts +7 -6
  124. package/dist/start.js +14 -7
  125. package/dist/start.js.map +1 -1
  126. package/dist/tools/catalog.d.ts +44 -0
  127. package/dist/tools/catalog.js +105 -0
  128. package/dist/tools/catalog.js.map +1 -0
  129. package/dist/tools/causes.d.ts +6 -6
  130. package/dist/tools/causes.js +4 -5
  131. package/dist/tools/causes.js.map +1 -1
  132. package/dist/tools/context.js +5 -5
  133. package/dist/tools/context.js.map +1 -1
  134. package/dist/tools/datasources.js +1 -1
  135. package/dist/tools/datasources.js.map +1 -1
  136. package/dist/tools/diagnostics.js +2 -2
  137. package/dist/tools/diagnostics.js.map +1 -1
  138. package/dist/tools/figures.d.ts +3 -2
  139. package/dist/tools/figures.js +38 -13
  140. package/dist/tools/figures.js.map +1 -1
  141. package/dist/tools/findings.d.ts +28 -0
  142. package/dist/tools/findings.js +88 -24
  143. package/dist/tools/findings.js.map +1 -1
  144. package/dist/tools/incidents.js +5 -5
  145. package/dist/tools/incidents.js.map +1 -1
  146. package/dist/tools/index.d.ts +19 -2
  147. package/dist/tools/index.js +115 -14
  148. package/dist/tools/index.js.map +1 -1
  149. package/dist/tools/investigations.d.ts +54 -0
  150. package/dist/tools/investigations.js +370 -69
  151. package/dist/tools/investigations.js.map +1 -1
  152. package/dist/tools/next.d.ts +20 -0
  153. package/dist/tools/next.js +136 -0
  154. package/dist/tools/next.js.map +1 -0
  155. package/dist/tools/postmortem-runbooks.d.ts +52 -52
  156. package/dist/tools/postmortem-runbooks.js +3 -10
  157. package/dist/tools/postmortem-runbooks.js.map +1 -1
  158. package/dist/tools/resume.d.ts +5 -0
  159. package/dist/tools/resume.js +136 -0
  160. package/dist/tools/resume.js.map +1 -0
  161. package/dist/tools/signin.d.ts +12 -0
  162. package/dist/tools/signin.js +54 -0
  163. package/dist/tools/signin.js.map +1 -0
  164. package/dist/tools/source-links.js +5 -3
  165. package/dist/tools/source-links.js.map +1 -1
  166. package/dist/tools/timeline.js +57 -11
  167. package/dist/tools/timeline.js.map +1 -1
  168. package/dist/trace-record.d.ts +36 -0
  169. package/dist/trace-record.js +283 -0
  170. package/dist/trace-record.js.map +1 -0
  171. package/dist/version.d.ts +10 -2
  172. package/dist/version.js +20 -1
  173. package/dist/version.js.map +1 -1
  174. package/package.json +23 -3
  175. package/server.json +5 -5
  176. package/contracts/runbooks/v1/fixtures/global-runbook.json +0 -7
  177. package/contracts/runbooks/v1/runbook-definition.schema.json +0 -25
  178. package/dist/auth.d.ts +0 -7
  179. package/dist/auth.js +0 -19
  180. package/dist/auth.js.map +0 -1
@@ -0,0 +1,53 @@
1
+ import { MCP_SERVER_VERSION } from "../version.js";
2
+ import { loginCommand, logoutCommand, statusCommand } from "./auth.js";
3
+ import { realIo } from "./io.js";
4
+ const HELP = `Tellagen MCP server ${MCP_SERVER_VERSION}
5
+
6
+ With no command it runs as an MCP server on standard input and output.
7
+
8
+ Commands
9
+ login Sign in with your browser. The key goes to the system keychain.
10
+ logout Remove the stored key from this computer.
11
+ status Show the sign-in. With --line: one sentence for a client hook, or nothing.
12
+ listen Take diagnosis runs that wait in Tellagen and run them with your AI client, with no window.
13
+ trace-hook Record one tool call of a client hook as a step of the open run (reads the hook event on standard input).
14
+
15
+ Settings: TELLAGEN_API_KEY and TELLAGEN_API_URL win over a stored sign-in. TELLAGEN_HOME moves the folder ~/.tellagen.
16
+ `;
17
+ /** Runs a command and returns the exit code. */
18
+ export async function runCli(command, args, io = realIo) {
19
+ switch (command) {
20
+ case "login":
21
+ return loginCommand(args, io);
22
+ case "logout":
23
+ return logoutCommand(args, io);
24
+ case "status":
25
+ return statusCommand(args, io);
26
+ case "listen": {
27
+ const { listenCommand } = await import("./listen.js");
28
+ return listenCommand(args, io);
29
+ }
30
+ case "listen-guard": {
31
+ const { listenGuardCommand } = await import("./listen-guard.js");
32
+ return listenGuardCommand(args, io);
33
+ }
34
+ case "listen-wrap": {
35
+ // Internal: the listener starts every client through it.
36
+ const { parseWrapArgs, runWrapped } = await import("../listen-wrap.js");
37
+ const parsed = parseWrapArgs(args);
38
+ if (!parsed) {
39
+ io.stderr("listen-wrap is started by the listener.\n");
40
+ return 2;
41
+ }
42
+ return runWrapped(parsed);
43
+ }
44
+ case "trace-hook": {
45
+ const { traceHookCommand } = await import("./trace-hook.js");
46
+ return traceHookCommand(args, io);
47
+ }
48
+ default:
49
+ io.stdout(HELP);
50
+ return 0;
51
+ }
52
+ }
53
+ //# sourceMappingURL=main.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAc,MAAM,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,IAAI,GAAG,uBAAuB,kBAAkB;;;;;;;;;;;;CAYrD,CAAC;AAEF,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAe,EAAE,IAAuB,EAAE,KAAY,MAAM;IACvF,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAChC,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACjC,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACjC,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;YACtD,OAAO,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACjC,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;YACjE,OAAO,kBAAkB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,yDAAyD;YACzD,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;YACxE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,EAAE,CAAC,MAAM,CAAC,2CAA2C,CAAC,CAAC;gBACvD,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YAC7D,OAAO,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACpC,CAAC;QACD;YACE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}
@@ -0,0 +1,23 @@
1
+ import { type CredentialVault } from "../credentials.js";
2
+ import { SignInIndex } from "../signin-index.js";
3
+ import type { CliIo } from "./io.js";
4
+ /** How long the whole hook may take. A tool call is never held longer. */
5
+ export declare const HOOK_TIMEOUT_MS = 2000;
6
+ export interface TraceHookDeps {
7
+ vault?: CredentialVault;
8
+ index?: SignInIndex;
9
+ now?: () => Date;
10
+ timeoutMs?: number;
11
+ }
12
+ /** Whether step recording was turned off: by the plugin option or by TELLAGEN_RECORD_STEPS. */
13
+ export declare function recordingOff(env: Record<string, string | undefined>): boolean;
14
+ /**
15
+ * `trace-hook`: reads the event of a client hook on standard input and
16
+ * records the tool call as one step of the open run.
17
+ *
18
+ * It does nothing, and says nothing, when there is no open run, the tool is
19
+ * not one a diagnosis records, recording is off, the server does not accept
20
+ * recorded steps, or Tellagen cannot be reached within two seconds. It always
21
+ * exits with 0, so it never blocks or fails the tool call it watches.
22
+ */
23
+ export declare function traceHookCommand(_args: readonly string[], io: CliIo, deps?: TraceHookDeps): Promise<number>;
@@ -0,0 +1,99 @@
1
+ import { TellagenClient } from "../client.js";
2
+ import { openVault } from "../credentials.js";
3
+ import { TellagenAPIError } from "../errors.js";
4
+ import { defaultStateDir, RunStateStore, workspaceKey } from "../run-state.js";
5
+ import { pendingNotesOf } from "../run-events.js";
6
+ import { SignInIndex } from "../signin-index.js";
7
+ import { resolveCredentials } from "../signin.js";
8
+ import { mapToolCall, MAX_HOOK_EVENT_BYTES, parseHookEvent, RECORDED_STEPS_CAPABILITY } from "../trace-record.js";
9
+ /** How long the whole hook may take. A tool call is never held longer. */
10
+ export const HOOK_TIMEOUT_MS = 2_000;
11
+ const OFF = new Set(["0", "false", "off", "no", "none"]);
12
+ /** Whether step recording was turned off: by the plugin option or by TELLAGEN_RECORD_STEPS. */
13
+ export function recordingOff(env) {
14
+ for (const name of ["TELLAGEN_RECORD_STEPS", "CLAUDE_PLUGIN_OPTION_RECORD_STEPS"]) {
15
+ const value = (env[name] ?? "").trim().toLowerCase();
16
+ if (value && OFF.has(value))
17
+ return true;
18
+ }
19
+ return false;
20
+ }
21
+ function isRecord(value) {
22
+ return typeof value === "object" && value !== null && !Array.isArray(value);
23
+ }
24
+ function noteText(value, max) {
25
+ return typeof value === "string" ? value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, max) : "";
26
+ }
27
+ /**
28
+ * `trace-hook`: reads the event of a client hook on standard input and
29
+ * records the tool call as one step of the open run.
30
+ *
31
+ * It does nothing, and says nothing, when there is no open run, the tool is
32
+ * not one a diagnosis records, recording is off, the server does not accept
33
+ * recorded steps, or Tellagen cannot be reached within two seconds. It always
34
+ * exits with 0, so it never blocks or fails the tool call it watches.
35
+ */
36
+ export async function traceHookCommand(_args, io, deps = {}) {
37
+ const timeoutMs = deps.timeoutMs ?? HOOK_TIMEOUT_MS;
38
+ const deadline = Date.now() + timeoutMs;
39
+ try {
40
+ if (recordingOff(io.env))
41
+ return 0;
42
+ const env = io.env;
43
+ const index = deps.index ?? new SignInIndex();
44
+ // Find the run without the keychain: most hook calls have no open run.
45
+ const envUrl = (env.TELLAGEN_API_URL ?? "").trim();
46
+ const apiUrl = envUrl || index.find()?.entry.api_url || "";
47
+ if (!apiUrl)
48
+ return 0;
49
+ const stateDir = (env.TELLAGEN_STATE_DIR ?? "").trim() || defaultStateDir();
50
+ const store = new RunStateStore(stateDir, workspaceKey(apiUrl));
51
+ const state = store.read();
52
+ if (!state)
53
+ return 0;
54
+ if (!state.server_capabilities.includes(RECORDED_STEPS_CAPABILITY))
55
+ return 0;
56
+ const event = parseHookEvent(await io.readStdin(MAX_HOOK_EVENT_BYTES + 1));
57
+ if (!event)
58
+ return 0;
59
+ const step = mapToolCall(event, deps.now?.() ?? new Date());
60
+ if (!step)
61
+ return 0;
62
+ const credentials = await resolveCredentials(env, deps.vault ?? openVault(), index);
63
+ if (!credentials.apiKey || !credentials.apiUrl)
64
+ return 0;
65
+ const client = new TellagenClient({ apiUrl: credentials.apiUrl, apiKey: credentials.apiKey });
66
+ // Speak as the server that holds the run.
67
+ client.session.adoptSession(state.session_id, state.client_id);
68
+ const left = deadline - Date.now();
69
+ if (left < 100)
70
+ return 0;
71
+ let answer;
72
+ try {
73
+ answer = await client.post(`/api/v1/investigation-runs/${encodeURIComponent(state.run_id)}/trace`, step.body,
74
+ // A repeat is the model's business. The hook tries once.
75
+ { safeToRepeat: false, timeoutMs: left });
76
+ }
77
+ catch (err) {
78
+ if (err instanceof TellagenAPIError && (err.code === "run_taken_over" || err.code === "investigation_run_ended")) {
79
+ const reason = err.code === "run_taken_over" ? "another client took it over" : noteText(err.payload?.details?.reason, 60) || "it ended";
80
+ store.setStop(state.run_id, reason);
81
+ }
82
+ return 0;
83
+ }
84
+ store.addPendingNotes(state.run_id, pendingNotesOf(answer));
85
+ // Tell the model's side which step this is, unless Tellagen stored nothing.
86
+ const note = isRecord(answer) && isRecord(answer.note) ? answer.note.code : undefined;
87
+ if (note !== "recorded_step_limit" && note !== "step_already_posted") {
88
+ store.addRecordedStep(state.run_id, { step_id: String(step.body.step_id), title: String(step.body.title ?? "") });
89
+ }
90
+ if (isRecord(answer) && answer.run_state === "cancel_requested") {
91
+ store.setStop(state.run_id, "a responder cancelled it in Tellagen");
92
+ }
93
+ }
94
+ catch {
95
+ // The hook must never fail a tool call.
96
+ }
97
+ return 0;
98
+ }
99
+ //# sourceMappingURL=trace-hook.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trace-hook.js","sourceRoot":"","sources":["../../src/cli/trace-hook.ts"],"names":[],"mappings":"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"}
package/dist/client.d.ts CHANGED
@@ -1,7 +1,55 @@
1
+ import { TellagenSetupError } from "./errors.js";
2
+ import { Session } from "./session.js";
1
3
  export interface ClientConfig {
4
+ /** The API address. Empty when the person has not set it yet. */
2
5
  apiUrl: string;
6
+ /** The API key. Empty when the person has not set it yet. */
3
7
  apiKey: string;
8
+ /**
9
+ * The folder of the remembered-run file. Left out, nothing is written to
10
+ * disk; the command-line entry point passes `~/.tellagen/state`.
11
+ */
12
+ stateDir?: string;
4
13
  }
14
+ /**
15
+ * Timeouts and retries of every Tellagen call. One object, so a test can
16
+ * shorten the delays without a setting that a person could see.
17
+ */
18
+ export declare const httpDefaults: {
19
+ /** How long one attempt may take. */
20
+ timeoutMs: number;
21
+ /** How long an attempt that sends screenshots may take. */
22
+ uploadTimeoutMs: number;
23
+ /** How long one call may take with all its repeats and waits. */
24
+ totalMs: number;
25
+ /** The same for a call that sends screenshots. */
26
+ uploadTotalMs: number;
27
+ /** Repeats after the first attempt. */
28
+ retries: number;
29
+ /** The first delay; each repeat doubles it. */
30
+ baseDelayMs: number;
31
+ /** The longest delay, also for a Retry-After header. */
32
+ maxDelayMs: number;
33
+ /** How long a refused key is trusted to be still refused. */
34
+ authRecheckMs: number;
35
+ };
36
+ export interface RequestOptions {
37
+ /** One attempt's limit in milliseconds. Defaults to 30 seconds. */
38
+ timeoutMs?: number;
39
+ /**
40
+ * Whether a repeat cannot create a second record. GET and PUT are; a POST
41
+ * or PATCH is only when the caller says so (a trace step by step_id, a
42
+ * heartbeat) or sends an idempotency key.
43
+ */
44
+ safeToRepeat?: boolean;
45
+ /** Sent as the Idempotency-Key header; makes the call safe to repeat. */
46
+ idempotencyKey?: string;
47
+ /** Extra request headers. */
48
+ headers?: Record<string, string>;
49
+ }
50
+ export type AuthStatus = "missing" | "unknown" | "ok" | "rejected";
51
+ /** The setup error for a missing key or address. It names no value. */
52
+ export declare function missingSetupError(missing: readonly string[]): TellagenSetupError;
5
53
  export interface BinaryFetchOptions {
6
54
  /** The most bytes read; a larger response is refused. */
7
55
  maxBytes: number;
@@ -17,10 +65,47 @@ export interface BinaryResponse {
17
65
  }
18
66
  /** Thin HTTP wrapper for the Tellagen public API. */
19
67
  export declare class TellagenClient {
20
- private readonly baseUrl;
21
- private readonly apiKey;
68
+ #private;
69
+ private baseUrl;
70
+ /** What this process knows about its client and its run. */
71
+ readonly session: Session;
72
+ private authStatus;
73
+ private authProblem;
74
+ private authCheckedAt;
22
75
  constructor(config: ClientConfig);
76
+ /**
77
+ * Replaces the key and the address, after a sign-in or a sign-out. The
78
+ * remembered-run file follows the address. The new key has not been tried
79
+ * yet, so the answer about the old one is dropped.
80
+ */
81
+ setCredentials(config: {
82
+ apiUrl: string;
83
+ apiKey: string;
84
+ }): void;
85
+ /** The API address in use; it holds no secret. */
86
+ apiUrl(): string;
87
+ /** Whether Tellagen accepted the key: not set, not asked yet, yes or no. */
88
+ auth(): AuthStatus;
89
+ private missingSetup;
90
+ /**
91
+ * Asks Tellagen once whether it accepts the key. It never throws: a
92
+ * network error leaves the answer open, and the tools report it later.
93
+ */
94
+ checkAuth(): Promise<AuthStatus>;
95
+ /**
96
+ * The reason no tool can work right now, or nothing. A refused key is asked
97
+ * about again after a short while, so a restored seat needs no restart.
98
+ */
99
+ accessProblem(): Promise<Error | undefined>;
23
100
  private headers;
101
+ /**
102
+ * One fetch with a time limit, repeated on a network error, a timeout and
103
+ * on 429, 502, 503 and 504 when the call is safe to repeat. The response
104
+ * is returned with its timer still running; the caller ends it with done().
105
+ */
106
+ private send;
107
+ /** Records a refusal of the key or the seat and returns the clear error. */
108
+ private noteAccess;
24
109
  private request;
25
110
  /**
26
111
  * GET the bytes at an API path with the API key, for images and other
@@ -28,8 +113,9 @@ export declare class TellagenClient {
28
113
  * full, and an error status is reported like any other API error.
29
114
  */
30
115
  getBinary(path: string, options: BinaryFetchOptions): Promise<BinaryResponse>;
31
- get<T>(path: string): Promise<T>;
32
- post<T>(path: string, body: unknown): Promise<T>;
33
- put<T>(path: string, body: unknown): Promise<T>;
34
- patch<T>(path: string, body: unknown): Promise<T>;
116
+ private readBinary;
117
+ get<T>(path: string, options?: RequestOptions): Promise<T>;
118
+ post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
119
+ put<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
120
+ patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
35
121
  }