@tpsdev-ai/pi-flair 0.48.0 → 0.49.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 (5) hide show
  1. package/README.md +17 -2
  2. package/dist/index.d.ts +18 -7
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +33 -9
  5. package/package.json +9 -3
package/README.md CHANGED
@@ -43,15 +43,30 @@ pi install -l npm:@tpsdev-ai/pi-flair
43
43
 
44
44
  ### Configure
45
45
 
46
- Add to `~/.pi/agent/settings.json` or `.pi/settings.json`:
46
+ `pi install` writes the package into settings for you. To configure manually,
47
+ add to `~/.pi/agent/settings.json` or `.pi/settings.json`:
47
48
 
48
49
  ```json
49
50
  {
50
- "extensions": ["npm:@tpsdev-ai/pi-flair"],
51
51
  "packages": ["npm:@tpsdev-ai/pi-flair"]
52
52
  }
53
53
  ```
54
54
 
55
+ Package sources (`npm:`, `git:`) belong in `packages`. The `extensions` settings
56
+ key takes local file paths only — an `npm:` spec there is silently ignored by pi.
57
+
58
+ > **Versions <= 0.48.0:** older published builds did not declare pi's package
59
+ > manifest (`pi.extensions` in package.json), so the `npm:` spec installs but
60
+ > registers no tools — silently ([#1346](https://github.com/tpsdev-ai/flair/issues/1346)).
61
+ > Upgrade pi-flair, or as a workaround point `extensions` at the installed file
62
+ > directly:
63
+ >
64
+ > ```json
65
+ > {
66
+ > "extensions": ["~/.pi/agent/npm/node_modules/@tpsdev-ai/pi-flair/dist/index.js"]
67
+ > }
68
+ > ```
69
+
55
70
  Or use environment variables:
56
71
 
57
72
  ```bash
package/dist/index.d.ts CHANGED
@@ -7,7 +7,7 @@
7
7
  * - bootstrap(agentId, maxTokens) — cold-start context
8
8
  *
9
9
  * Configuration:
10
- * - flair_url (default: http://127.0.0.1:9926)
10
+ * - flair_url (default: http://127.0.0.1:19926)
11
11
  * - agentId (required, via FLAIR_AGENT_ID env var)
12
12
  * - max_recall_results (default: 5)
13
13
  * - max_bootstrap_tokens (default: 4000)
@@ -16,18 +16,18 @@
16
16
  *
17
17
  * Usage:
18
18
  * 1. Install: pi install npm:@tpsdev-ai/pi-flair
19
- * 2. Configure in ~/.pi/agent/settings.json or .pi/settings.json:
19
+ * (writes "npm:@tpsdev-ai/pi-flair" into the "packages" settings key; pi
20
+ * discovers the extension via the "pi" manifest in package.json — #1346)
21
+ * 2. Or configure manually in ~/.pi/agent/settings.json or .pi/settings.json:
20
22
  * {
21
- * "extensions": ["npm:@tpsdev-ai/pi-flair"],
22
- * "flair_url": "http://127.0.0.1:9926",
23
- * "agentId": "my-project"
23
+ * "packages": ["npm:@tpsdev-ai/pi-flair"]
24
24
  * }
25
25
  * 3. Or use environment variables:
26
26
  * export FLAIR_AGENT_ID=my-agent
27
- * export FLAIR_URL=http://127.0.0.1:9926
27
+ * export FLAIR_URL=http://127.0.0.1:19926
28
28
  * 4. Restart pi
29
29
  */
30
- import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
30
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
31
31
  import { type FlairClientConfig } from "@tpsdev-ai/flair-client";
32
32
  interface PluginConfig extends FlairClientConfig {
33
33
  max_recall_results?: number;
@@ -35,6 +35,17 @@ interface PluginConfig extends FlairClientConfig {
35
35
  auto_capture?: boolean;
36
36
  auto_recall?: boolean;
37
37
  }
38
+ /**
39
+ * Default Flair base URL when FLAIR_URL is unset.
40
+ *
41
+ * 19926 is Flair's stock local HTTP port — `flair init` on a new instance
42
+ * serves REST there (DEFAULT_PORT in src/cli.ts), and the README documents
43
+ * exactly this value. 9926 is the ORIGINAL default that only long-running
44
+ * early installs still use. This constant shipped as 9926 for a while
45
+ * (flair#1347), so a default install got connection_error on every memory
46
+ * call; the code now matches the docs, not the other way around.
47
+ */
48
+ export declare const DEFAULT_FLAIR_URL = "http://127.0.0.1:19926";
38
49
  /**
39
50
  * Classify an error into a user-friendly message.
40
51
  * @param err - The error to classify
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAEpF,OAAO,EAA2B,KAAK,iBAAiB,EAAwB,MAAM,yBAAyB,CAAC;AAIhH,UAAU,YAAa,SAAQ,iBAAiB;IAC9C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAkFD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBpE;AAQD,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAkNxC;AAID,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,SAAS,SAAO,GACf,OAAO,CAAC,MAAM,CAAC,CAIjB"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AAEtF,OAAO,EAA2B,KAAK,iBAAiB,EAAwB,MAAM,yBAAyB,CAAC;AAIhH,UAAU,YAAa,SAAQ,iBAAiB;IAC9C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAmCD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AA+D1D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBpE;AAQD,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAkNxC;AAID,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,SAAS,SAAO,GACf,OAAO,CAAC,MAAM,CAAC,CAIjB"}
package/dist/index.js CHANGED
@@ -7,7 +7,7 @@
7
7
  * - bootstrap(agentId, maxTokens) — cold-start context
8
8
  *
9
9
  * Configuration:
10
- * - flair_url (default: http://127.0.0.1:9926)
10
+ * - flair_url (default: http://127.0.0.1:19926)
11
11
  * - agentId (required, via FLAIR_AGENT_ID env var)
12
12
  * - max_recall_results (default: 5)
13
13
  * - max_bootstrap_tokens (default: 4000)
@@ -16,15 +16,15 @@
16
16
  *
17
17
  * Usage:
18
18
  * 1. Install: pi install npm:@tpsdev-ai/pi-flair
19
- * 2. Configure in ~/.pi/agent/settings.json or .pi/settings.json:
19
+ * (writes "npm:@tpsdev-ai/pi-flair" into the "packages" settings key; pi
20
+ * discovers the extension via the "pi" manifest in package.json — #1346)
21
+ * 2. Or configure manually in ~/.pi/agent/settings.json or .pi/settings.json:
20
22
  * {
21
- * "extensions": ["npm:@tpsdev-ai/pi-flair"],
22
- * "flair_url": "http://127.0.0.1:9926",
23
- * "agentId": "my-project"
23
+ * "packages": ["npm:@tpsdev-ai/pi-flair"]
24
24
  * }
25
25
  * 3. Or use environment variables:
26
26
  * export FLAIR_AGENT_ID=my-agent
27
- * export FLAIR_URL=http://127.0.0.1:9926
27
+ * export FLAIR_URL=http://127.0.0.1:19926
28
28
  * 4. Restart pi
29
29
  */
30
30
  import { Type } from "@sinclair/typebox";
@@ -44,12 +44,23 @@ function containsSecrets(text) {
44
44
  return SECRET_PATTERNS.some((pattern) => pattern.test(text));
45
45
  }
46
46
  // ─── Config Resolution ───────────────────────────────────────────────────────
47
+ /**
48
+ * Default Flair base URL when FLAIR_URL is unset.
49
+ *
50
+ * 19926 is Flair's stock local HTTP port — `flair init` on a new instance
51
+ * serves REST there (DEFAULT_PORT in src/cli.ts), and the README documents
52
+ * exactly this value. 9926 is the ORIGINAL default that only long-running
53
+ * early installs still use. This constant shipped as 9926 for a while
54
+ * (flair#1347), so a default install got connection_error on every memory
55
+ * call; the code now matches the docs, not the other way around.
56
+ */
57
+ export const DEFAULT_FLAIR_URL = "http://127.0.0.1:19926";
47
58
  function getConfig(pi) {
48
59
  // Try to load from settings
49
60
  // Note: pi doesn't expose settings.json directly in extension API
50
61
  // We rely on environment variables and defaults
51
62
  const flConfig = {
52
- url: process.env.FLAIR_URL || "http://127.0.0.1:9926",
63
+ url: process.env.FLAIR_URL || DEFAULT_FLAIR_URL,
53
64
  agentId: process.env.FLAIR_AGENT_ID,
54
65
  keyPath: process.env.FLAIR_KEY_PATH,
55
66
  };
@@ -83,11 +94,24 @@ function createFlairClient(config) {
83
94
  }
84
95
  return new FlairClient({
85
96
  agentId: config.agentId,
86
- url: config.url || "http://127.0.0.1:9926",
97
+ url: config.url || DEFAULT_FLAIR_URL,
87
98
  keyPath: config.keyPath,
88
99
  });
89
100
  }
90
101
  // ─── Error Classification ─────────────────────────────────────────────────────
102
+ /**
103
+ * flair#1347 — a refused connection on one of the two common local ports
104
+ * should name the OTHER one: 19926 is the stock `flair init` port, 9926 the
105
+ * original default early installs still serve. The pre-fix error named only
106
+ * the dead port, so "is it running?" read as "Flair is down" when Flair was
107
+ * up one port over. Always name FLAIR_URL — it is the knob that fixes it.
108
+ */
109
+ function connectionHint(flairUrl) {
110
+ const other = flairUrl.includes(":19926") ? "9926" : flairUrl.includes(":9926") ? "19926" : undefined;
111
+ return other
112
+ ? ` If your instance serves on :${other} instead, set FLAIR_URL (e.g. export FLAIR_URL=http://127.0.0.1:${other}).`
113
+ : " Check FLAIR_URL — it should point at your Flair instance's HTTP port (stock local default: 19926).";
114
+ }
91
115
  /**
92
116
  * Classify an error into a user-friendly message.
93
117
  * @param err - The error to classify
@@ -113,7 +137,7 @@ export function classifyError(err, flairUrl) {
113
137
  return "timeout — the server took too long. Try shorter content or retry.";
114
138
  }
115
139
  if (err instanceof TypeError && err.message.includes("fetch")) {
116
- return `connection_error (retriable): could not reach Flair at ${flairUrl}. Is it running?`;
140
+ return `connection_error (retriable): could not reach Flair at ${flairUrl}. Is it running?${connectionHint(flairUrl)}`;
117
141
  }
118
142
  return `unexpected_error: ${err.message}`;
119
143
  }
package/package.json CHANGED
@@ -1,10 +1,15 @@
1
1
  {
2
2
  "name": "@tpsdev-ai/pi-flair",
3
- "version": "0.48.0",
3
+ "version": "0.49.0",
4
4
  "description": "Flair memory extension for pi — persistent memory access from within pi sessions",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
8
+ "pi": {
9
+ "extensions": [
10
+ "./dist/index.js"
11
+ ]
12
+ },
8
13
  "files": [
9
14
  "dist/",
10
15
  "LICENSE",
@@ -21,7 +26,7 @@
21
26
  "node": ">=18"
22
27
  },
23
28
  "dependencies": {
24
- "@tpsdev-ai/flair-client": "0.48.0",
29
+ "@tpsdev-ai/flair-client": "0.49.0",
25
30
  "@sinclair/typebox": "0.34.48"
26
31
  },
27
32
  "license": "Apache-2.0",
@@ -34,6 +39,7 @@
34
39
  "keywords": [
35
40
  "pi",
36
41
  "pi-extension",
42
+ "pi-package",
37
43
  "flair",
38
44
  "memory",
39
45
  "semantic-search",
@@ -41,7 +47,7 @@
41
47
  "agent"
42
48
  ],
43
49
  "devDependencies": {
44
- "@mariozechner/pi-coding-agent": "0.73.0",
50
+ "@earendil-works/pi-coding-agent": "0.84.2",
45
51
  "@types/node": "24.11.0",
46
52
  "typescript": "5.9.3"
47
53
  }