@picassohq/cli 0.0.0-stage → 1.0.2
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/agents/browser_agent.yaml +53 -0
- package/agents/code_reviewer.yaml +49 -0
- package/agents/codebase_investigator.yaml +70 -0
- package/agents/design_auditor.yaml +50 -0
- package/agents/devex_auditor.yaml +50 -0
- package/agents/doc_writer.yaml +54 -0
- package/agents/engineering_architect.yaml +51 -0
- package/agents/generalist.yaml +55 -0
- package/agents/migration_planner.yaml +51 -0
- package/agents/product_reviewer.yaml +48 -0
- package/agents/qa_operator.yaml +52 -0
- package/agents/release_engineer.yaml +50 -0
- package/agents/security_auditor.yaml +62 -0
- package/agents/test_writer.yaml +52 -0
- package/assets/first-light-lockup.png +0 -0
- package/assets/first-light-tagline.png +0 -0
- package/assets/house/README.md +26 -0
- package/assets/house/auraone-banner.png +0 -0
- package/assets/house/auraone-logo.png +0 -0
- package/assets/house/kiro-prism-banner.png +0 -0
- package/assets/house/kiro-prism-logo.png +0 -0
- package/assets/house/picasso-banner.png +0 -0
- package/assets/house/picasso-logo.png +0 -0
- package/assets/wordmark-app.png +0 -0
- package/assets/wordmark-tight.png +0 -0
- package/assets/wordmark.png +0 -0
- package/design/styles.css +1042 -0
- package/dist/build-info.json +37 -0
- package/dist/index.js +3062 -0
- package/goals/cli-hardening.yaml +40 -0
- package/goals/repo-maintenance.yaml +40 -0
- package/package.json +49 -4
- package/runtime/dsh/picasso-ecosystem.community.amendments.yml +24 -0
- package/runtime/dsh/picasso-ecosystem.community.json +185 -0
- package/runtime/dsh/picasso-ecosystem.community.patch.yml +40 -0
- package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +143 -0
- package/runtime/dsh/picasso-isolation.patch.yml +25 -0
- package/runtime/dsh/picasso-providers.patch.yml +373 -0
- package/runtime/dsh/picasso-runtime.cordis.yml +738 -0
- package/runtime/dsh/picasso-sdk.patch.yml +204 -0
- package/runtime/engine-manifest.json +215 -0
- package/runtime/package.json +6 -0
- package/runtime/packages/picasso-cache-probe/cordis.patch.yml +5 -0
- package/runtime/packages/picasso-cache-probe/index.js +477 -0
- package/runtime/packages/picasso-cache-probe/package.json +38 -0
- package/runtime/packages/picasso-commands/cordis.patch.yml +4 -0
- package/runtime/packages/picasso-commands/fresh-review.js +573 -0
- package/runtime/packages/picasso-commands/index.js +497 -0
- package/runtime/packages/picasso-commands/package.json +28 -0
- package/runtime/packages/picasso-instructions/conflicts.js +115 -0
- package/runtime/packages/picasso-instructions/formats.js +145 -0
- package/runtime/packages/picasso-instructions/frontmatter.js +175 -0
- package/runtime/packages/picasso-instructions/glob.js +114 -0
- package/runtime/packages/picasso-instructions/globals.js +90 -0
- package/runtime/packages/picasso-instructions/imports.js +123 -0
- package/runtime/packages/picasso-instructions/index.js +326 -0
- package/runtime/packages/picasso-instructions/modes.js +64 -0
- package/runtime/packages/picasso-instructions/package.json +30 -0
- package/runtime/packages/picasso-instructions/parse.js +134 -0
- package/runtime/packages/picasso-instructions/report.js +161 -0
- package/runtime/packages/picasso-instructions/resolve.js +939 -0
- package/runtime/packages/picasso-instructions/scan.js +181 -0
- package/runtime/packages/picasso-instructions/settings.js +150 -0
- package/runtime/packages/picasso-instructions/skills.js +345 -0
- package/runtime/packages/picasso-lean-context/cordis.patch.yml +13 -0
- package/runtime/packages/picasso-lean-context/index.js +6280 -0
- package/runtime/packages/picasso-lean-context/package.json +26 -0
- package/runtime/packages/picasso-lean-context/read-image-recovery.js +306 -0
- package/runtime/packages/picasso-lean-context/timeline.js +418 -0
- package/runtime/packages/picasso-librarian/classify.js +146 -0
- package/runtime/packages/picasso-librarian/cordis.patch.yml +10 -0
- package/runtime/packages/picasso-librarian/index.js +878 -0
- package/runtime/packages/picasso-librarian/notes.js +159 -0
- package/runtime/packages/picasso-librarian/package.json +34 -0
- package/runtime/packages/picasso-librarian/state.js +478 -0
- package/runtime/packages/picasso-memory/index.js +1184 -0
- package/runtime/packages/picasso-memory/package.json +21 -0
- package/runtime/packages/picasso-model-router/connections.js +912 -0
- package/runtime/packages/picasso-model-router/cordis.patch.yml +17 -0
- package/runtime/packages/picasso-model-router/index.js +1083 -0
- package/runtime/packages/picasso-model-router/package.json +30 -0
- package/runtime/packages/picasso-options/cordis.patch.yml +4 -0
- package/runtime/packages/picasso-options/index.js +263 -0
- package/runtime/packages/picasso-options/package.json +28 -0
- package/runtime/packages/picasso-progress-reports/cordis.patch.yml +10 -0
- package/runtime/packages/picasso-progress-reports/index.js +267 -0
- package/runtime/packages/picasso-progress-reports/package.json +30 -0
- package/runtime/packages/picasso-progress-reports/report.js +235 -0
- package/runtime/packages/picasso-sdk-server/aside.js +142 -0
- package/runtime/packages/picasso-sdk-server/connections.js +38 -0
- package/runtime/packages/picasso-sdk-server/context-timeline.js +27 -0
- package/runtime/packages/picasso-sdk-server/egress-gate.js +520 -0
- package/runtime/packages/picasso-sdk-server/failure-policy.js +246 -0
- package/runtime/packages/picasso-sdk-server/file-input.js +169 -0
- package/runtime/packages/picasso-sdk-server/goal.js +131 -0
- package/runtime/packages/picasso-sdk-server/ignore-file.js +458 -0
- package/runtime/packages/picasso-sdk-server/ignore-plugin.js +12 -0
- package/runtime/packages/picasso-sdk-server/ignore-sandbox.js +122 -0
- package/runtime/packages/picasso-sdk-server/ignore-snapshot.js +131 -0
- package/runtime/packages/picasso-sdk-server/image-input.js +44 -0
- package/runtime/packages/picasso-sdk-server/index.js +891 -0
- package/runtime/packages/picasso-sdk-server/instructions.js +34 -0
- package/runtime/packages/picasso-sdk-server/jobs.js +113 -0
- package/runtime/packages/picasso-sdk-server/mcp-gate.js +51 -0
- package/runtime/packages/picasso-sdk-server/model-selection.js +162 -0
- package/runtime/packages/picasso-sdk-server/package.json +50 -0
- package/runtime/packages/picasso-sdk-server/picasso-records.js +50 -0
- package/runtime/packages/picasso-sdk-server/provider-reload.js +84 -0
- package/runtime/packages/picasso-sdk-server/queue.js +322 -0
- package/runtime/packages/picasso-sdk-server/requester.js +43 -0
- package/runtime/packages/picasso-sdk-server/rewind.js +108 -0
- package/runtime/packages/picasso-sdk-server/schedule.js +187 -0
- package/runtime/packages/picasso-sdk-server/session-grants.js +35 -0
- package/runtime/packages/picasso-sdk-server/session-state.js +118 -0
- package/runtime/packages/picasso-sdk-server/shell-paths.js +869 -0
- package/runtime/packages/picasso-sdk-server/stream-deltas.js +211 -0
- package/runtime/packages/picasso-sdk-server/team-tasks.js +451 -0
- package/runtime/packages/picasso-sdk-server/tool-output.js +128 -0
- package/runtime/packages/picasso-sdk-server/tools-list.js +51 -0
- package/runtime/packages/picasso-sdk-server/wave2-hooks.js +612 -0
- package/runtime/packages/picasso-sdk-server/workspace-archive.js +170 -0
- package/runtime/packages/picasso-sdk-server/workspace-restore.js +180 -0
- package/runtime/packages/picasso-web-search/backends.js +412 -0
- package/runtime/packages/picasso-web-search/config.js +121 -0
- package/runtime/packages/picasso-web-search/cordis.patch.yml +7 -0
- package/runtime/packages/picasso-web-search/failure.js +116 -0
- package/runtime/packages/picasso-web-search/format.js +42 -0
- package/runtime/packages/picasso-web-search/index.js +71 -0
- package/runtime/packages/picasso-web-search/package.json +38 -0
- package/runtime/packages/picasso-web-search/router.js +156 -0
- package/runtime/packages/picasso-x-reader/circle.js +324 -0
- package/runtime/packages/picasso-x-reader/command.js +169 -0
- package/runtime/packages/picasso-x-reader/cordis.patch.yml +8 -0
- package/runtime/packages/picasso-x-reader/index.js +170 -0
- package/runtime/packages/picasso-x-reader/package.json +39 -0
- package/runtime/packages/picasso-x-reader/read.js +370 -0
- package/runtime/packages/picasso-x-reader/rewrite.js +38 -0
- package/runtime/packages/picasso-x-reader/settings.js +131 -0
- package/runtime/packages/picasso-x-reader/urls.js +154 -0
- package/runtime/packages/picasso-x-reader/xmd.js +512 -0
- package/runtime/plugins/picasso-auth-bridge/index.js +380 -0
- package/runtime/plugins/picasso-auth-bridge/package.json +28 -0
- package/runtime/plugins/picasso-auto-approve/index.js +1003 -0
- package/runtime/plugins/picasso-auto-approve/package.json +28 -0
- package/runtime/plugins/picasso-browser/index.js +424 -0
- package/runtime/plugins/picasso-browser/package.json +28 -0
- package/runtime/plugins/picasso-checkpoints/evidence.js +210 -0
- package/runtime/plugins/picasso-checkpoints/index.js +885 -0
- package/runtime/plugins/picasso-checkpoints/package.json +29 -0
- package/runtime/plugins/picasso-commands/fresh-review.js +573 -0
- package/runtime/plugins/picasso-commands/index.js +497 -0
- package/runtime/plugins/picasso-commands/package.json +28 -0
- package/runtime/plugins/picasso-instructions/conflicts.js +115 -0
- package/runtime/plugins/picasso-instructions/formats.js +145 -0
- package/runtime/plugins/picasso-instructions/frontmatter.js +175 -0
- package/runtime/plugins/picasso-instructions/glob.js +114 -0
- package/runtime/plugins/picasso-instructions/globals.js +90 -0
- package/runtime/plugins/picasso-instructions/imports.js +123 -0
- package/runtime/plugins/picasso-instructions/index.js +326 -0
- package/runtime/plugins/picasso-instructions/modes.js +64 -0
- package/runtime/plugins/picasso-instructions/package.json +30 -0
- package/runtime/plugins/picasso-instructions/parse.js +134 -0
- package/runtime/plugins/picasso-instructions/report.js +161 -0
- package/runtime/plugins/picasso-instructions/resolve.js +939 -0
- package/runtime/plugins/picasso-instructions/scan.js +181 -0
- package/runtime/plugins/picasso-instructions/settings.js +150 -0
- package/runtime/plugins/picasso-instructions/skills.js +345 -0
- package/runtime/plugins/picasso-lean-context/index.js +6280 -0
- package/runtime/plugins/picasso-lean-context/package.json +26 -0
- package/runtime/plugins/picasso-lean-context/read-image-recovery.js +306 -0
- package/runtime/plugins/picasso-lean-context/timeline.js +418 -0
- package/runtime/plugins/picasso-librarian/classify.js +146 -0
- package/runtime/plugins/picasso-librarian/index.js +878 -0
- package/runtime/plugins/picasso-librarian/notes.js +159 -0
- package/runtime/plugins/picasso-librarian/package.json +34 -0
- package/runtime/plugins/picasso-librarian/state.js +478 -0
- package/runtime/plugins/picasso-lifecycle-hooks/index.js +186 -0
- package/runtime/plugins/picasso-lifecycle-hooks/package.json +25 -0
- package/runtime/plugins/picasso-mail/inbox.js +207 -0
- package/runtime/plugins/picasso-mail/index.js +293 -0
- package/runtime/plugins/picasso-mail/package.json +22 -0
- package/runtime/plugins/picasso-memory/index.js +1184 -0
- package/runtime/plugins/picasso-memory/package.json +21 -0
- package/runtime/plugins/picasso-model-router/connections.js +912 -0
- package/runtime/plugins/picasso-model-router/index.js +1083 -0
- package/runtime/plugins/picasso-model-router/package.json +30 -0
- package/runtime/plugins/picasso-options/index.js +263 -0
- package/runtime/plugins/picasso-options/package.json +28 -0
- package/runtime/plugins/picasso-progress-reports/index.js +267 -0
- package/runtime/plugins/picasso-progress-reports/package.json +30 -0
- package/runtime/plugins/picasso-progress-reports/report.js +235 -0
- package/runtime/plugins/picasso-provider-models/index.js +436 -0
- package/runtime/plugins/picasso-provider-models/package.json +28 -0
- package/runtime/plugins/picasso-repo-index/index.js +1850 -0
- package/runtime/plugins/picasso-repo-index/package.json +28 -0
- package/runtime/plugins/picasso-schedule-pause/index.js +344 -0
- package/runtime/plugins/picasso-schedule-pause/package.json +28 -0
- package/runtime/plugins/picasso-session-lifecycle/index.js +796 -0
- package/runtime/plugins/picasso-session-lifecycle/package.json +28 -0
- package/runtime/plugins/picasso-trackers/index.js +895 -0
- package/runtime/plugins/picasso-trackers/package.json +28 -0
- package/runtime/plugins/picasso-web-search/backends.js +412 -0
- package/runtime/plugins/picasso-web-search/config.js +121 -0
- package/runtime/plugins/picasso-web-search/failure.js +116 -0
- package/runtime/plugins/picasso-web-search/format.js +42 -0
- package/runtime/plugins/picasso-web-search/index.js +71 -0
- package/runtime/plugins/picasso-web-search/package.json +38 -0
- package/runtime/plugins/picasso-web-search/router.js +156 -0
- package/runtime/plugins/picasso-x-reader/circle.js +324 -0
- package/runtime/plugins/picasso-x-reader/command.js +169 -0
- package/runtime/plugins/picasso-x-reader/index.js +170 -0
- package/runtime/plugins/picasso-x-reader/package.json +39 -0
- package/runtime/plugins/picasso-x-reader/read.js +370 -0
- package/runtime/plugins/picasso-x-reader/rewrite.js +38 -0
- package/runtime/plugins/picasso-x-reader/settings.js +131 -0
- package/runtime/plugins/picasso-x-reader/urls.js +154 -0
- package/runtime/plugins/picasso-x-reader/xmd.js +512 -0
- package/runtime/relay/attachment-text.mjs +737 -0
- package/runtime/relay/companion/companion.css +126 -0
- package/runtime/relay/companion/companion.js +648 -0
- package/runtime/relay/companion/icon.svg +5 -0
- package/runtime/relay/companion/index.html +25 -0
- package/runtime/relay/companion/manifest.json +13 -0
- package/runtime/relay/companion/sw.js +41 -0
- package/runtime/relay/main.mjs +38580 -0
- package/runtime/relay/model-listing.mjs +614 -0
- package/runtime/relay/versions-routes.mjs +1400 -0
- package/runtime/verify-plugins.mjs +205 -0
- package/runtime-lock/package-lock.json +10779 -0
- package/runtime-lock/package.json +7 -0
- package/scripts/install-runtime.mjs +400 -0
- package/README.md +0 -3
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
// The text contract the surfaces read. The plugin writes these two shapes into the tool result; the Mac and the
|
|
2
|
+
// TUI parse them back (`packages/shared/src/search-backend.ts` and its Swift twin) from the shared fixture
|
|
3
|
+
// `packages/shared/test/fixtures/search-backend/cases.json`, so a change here is a change there.
|
|
4
|
+
//
|
|
5
|
+
// fallback answered -> the result's `content` starts with one line: Search backend: <Name> (fallback)
|
|
6
|
+
// nothing answered -> the tool error is
|
|
7
|
+
// Web search is unavailable right now.
|
|
8
|
+
// Backends tried:
|
|
9
|
+
// - <Name>: <reason>
|
|
10
|
+
// ...
|
|
11
|
+
// <instruction to the model>
|
|
12
|
+
//
|
|
13
|
+
// Names come from a closed table and reasons from a closed vocabulary (failure.js): no provider response body, URL,
|
|
14
|
+
// key or request id ever reaches this text.
|
|
15
|
+
|
|
16
|
+
export const BACKEND_MARKER_PREFIX = 'Search backend: ';
|
|
17
|
+
export const BACKEND_MARKER_SUFFIX = ' (fallback)';
|
|
18
|
+
export const UNAVAILABLE_HEADLINE = 'Web search is unavailable right now.';
|
|
19
|
+
export const BACKENDS_TRIED_LABEL = 'Backends tried:';
|
|
20
|
+
export const UNAVAILABLE_INSTRUCTION =
|
|
21
|
+
'Tell the user that web search is unavailable right now and why. Do not substitute scraping search engines (DuckDuckGo, Bing, Google) from the shell or by fetching search result pages, and do not make up results.';
|
|
22
|
+
|
|
23
|
+
/** The one line a fallback backend's answer starts with. */
|
|
24
|
+
export function formatBackendMarker(name) {
|
|
25
|
+
return `${BACKEND_MARKER_PREFIX}${name}${BACKEND_MARKER_SUFFIX}`;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** The line for a route with nothing to try: it names the route and what web search needs there. */
|
|
29
|
+
export function formatNothingConfigured(route) {
|
|
30
|
+
const id = typeof route === 'string' && /^[A-Za-z0-9._-]{1,64}$/u.test(route) ? route : undefined;
|
|
31
|
+
if (id === undefined) return '- none: this model route has no native web search and no fallback is configured';
|
|
32
|
+
return `- none: the ${id} route has no native web search and no fallback is configured (web search needs a fallback in settings.webSearch.fallbacks or PICASSO_WEB_SEARCH_FALLBACKS, e.g. anthropic or openai)`;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* `attempts`: `[{ name, reason }]` in the order tried. An empty list says no backend is configured for this route;
|
|
37
|
+
* `route` (the thread's route id, a config key) is named in that line when given.
|
|
38
|
+
*/
|
|
39
|
+
export function formatUnavailable(attempts, { route } = {}) {
|
|
40
|
+
const lines = attempts.length === 0 ? [formatNothingConfigured(route)] : attempts.map((attempt) => `- ${attempt.name}: ${attempt.reason}`);
|
|
41
|
+
return [UNAVAILABLE_HEADLINE, BACKENDS_TRIED_LABEL, ...lines, UNAVAILABLE_INSTRUCTION].join('\n');
|
|
42
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
// @picasso/web-search — the web seam's search provider that follows the model the thread runs on.
|
|
2
|
+
//
|
|
3
|
+
// dsh's `ctx.web` selects ONE search provider by id (`web.searchProvider`), and the shipped composition pins a DeepSeek
|
|
4
|
+
// one, so every thread's `web_search` went to the DeepSeek API with the DeepSeek key whatever model it ran. This plugin
|
|
5
|
+
// registers `picasso-web-search` (the CLI patch and the Mac relay pin it) and chooses per call, from the thread's own
|
|
6
|
+
// route: its native search with its own credentials, then the configured fallbacks (PICASSO_WEB_SEARCH_FALLBACKS,
|
|
7
|
+
// `settings.webSearch`), then a structured error that names every backend tried. See router.js and README.md.
|
|
8
|
+
//
|
|
9
|
+
// The tool's schema and description belong to the engine's tool-web and are untouched, so the wire tool list (Tier 1)
|
|
10
|
+
// is byte-identical: `ready` is always true, so the model is never told `unknown tool "web_search"` (see createSearchProvider).
|
|
11
|
+
import { createBackends, credentialsFrom, routeProfileFrom } from './backends.js';
|
|
12
|
+
import { configReader } from './config.js';
|
|
13
|
+
import { createRouter } from './router.js';
|
|
14
|
+
|
|
15
|
+
export * from './format.js';
|
|
16
|
+
export * from './failure.js';
|
|
17
|
+
export * from './config.js';
|
|
18
|
+
export { BACKEND_NAMES, DEFAULT_BASE_URLS, DEFAULT_MODELS, DEFAULT_PRISM_URL, KEY_REFS, NATIVE_ROUTES, createBackends, credentialsFrom, messagesBase, parseGeminiSearch, parseMessagesSearch, parseOpenAiSearch, routeProfileFrom } from './backends.js';
|
|
19
|
+
export { DEFAULT_RETRY_DELAY_MS, MAX_RETRY_WAIT_MS, UNAVAILABLE_CODE, createRouter } from './router.js';
|
|
20
|
+
|
|
21
|
+
export const name = 'picasso-web-search';
|
|
22
|
+
/** The dsh release this plugin is written and tested against. */
|
|
23
|
+
export const dshTarget = '0.2.2-rc.3';
|
|
24
|
+
/** The id the web seam's `searchProvider` pin names. */
|
|
25
|
+
export const PROVIDER_ID = 'picasso-web-search';
|
|
26
|
+
|
|
27
|
+
const DESCRIPTION = Object.freeze({
|
|
28
|
+
en: "Searches with the model you are chatting with (its own web search and key), then any fallback you configured. Reports a failure instead of guessing.",
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
/** The search provider over a web seam (`web.registerSearchProvider`), for tests and for `apply`. */
|
|
32
|
+
export function createSearchProvider({ ctx, getWeb, fetch: fetchImpl, readConfig, sleep, maxRetryWaitMs, routeProfile } = {}) {
|
|
33
|
+
const creds = credentialsFrom(ctx);
|
|
34
|
+
const backends = createBackends({
|
|
35
|
+
creds,
|
|
36
|
+
...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),
|
|
37
|
+
getWeb: getWeb ?? (() => undefined),
|
|
38
|
+
routeProfile: routeProfile ?? routeProfileFrom(ctx),
|
|
39
|
+
});
|
|
40
|
+
const router = createRouter({ ctx, readConfig: readConfig ?? configReader(), backends, ...(sleep === undefined ? {} : { sleep }), ...(maxRetryWaitMs === undefined ? {} : { maxRetryWaitMs }) });
|
|
41
|
+
return {
|
|
42
|
+
id: PROVIDER_ID,
|
|
43
|
+
title: 'Follows your model',
|
|
44
|
+
description: DESCRIPTION,
|
|
45
|
+
available: () => true,
|
|
46
|
+
// Always ready. dsh-tool-web withholds `web_search` from a route whose provider is not ready, and the model then gets
|
|
47
|
+
// `unknown tool "web_search"` and improvises (it scraped search engines from the shell). Offering the tool and
|
|
48
|
+
// answering with the structured failure says why instead. The tool is deferred (off the wire), so this moves no
|
|
49
|
+
// Tier-1 byte (packages/picasso-cache-probe hygiene lanes; test/engine.test.mjs).
|
|
50
|
+
ready: async () => true,
|
|
51
|
+
search: (request, signal) => router.search(request, signal),
|
|
52
|
+
router,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function apply(ctx, config = {}) {
|
|
57
|
+
ctx.inject?.(['web'], (inner) => {
|
|
58
|
+
const provider = createSearchProvider({
|
|
59
|
+
ctx,
|
|
60
|
+
getWeb: () => inner.web,
|
|
61
|
+
readConfig: configReader({ settingsFile: typeof config?.settingsFile === 'string' ? config.settingsFile : undefined }),
|
|
62
|
+
});
|
|
63
|
+
const { router: _router, ...registration } = provider;
|
|
64
|
+
const dispose = inner.web.registerSearchProvider(registration);
|
|
65
|
+
try {
|
|
66
|
+
inner.on?.('dispose', dispose);
|
|
67
|
+
} catch {
|
|
68
|
+
// Older cordis: the registration lives as long as the engine process.
|
|
69
|
+
}
|
|
70
|
+
});
|
|
71
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@picasso/web-search",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"private": true,
|
|
5
|
+
"description": "dsh cordis plugin: the web seam's search provider that follows the model route the thread runs on (native search of that route, with that route's own credentials), then an ordered list of configured fallbacks, and a structured error when every backend fails. Zero runtime dependencies.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "index.js",
|
|
8
|
+
"types": "index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./index.d.ts",
|
|
12
|
+
"default": "./index.js"
|
|
13
|
+
},
|
|
14
|
+
"./cordis.patch.yml": "./cordis.patch.yml",
|
|
15
|
+
"./package.json": "./package.json"
|
|
16
|
+
},
|
|
17
|
+
"dshTarget": "0.2.2-rc.3",
|
|
18
|
+
"dsh": {
|
|
19
|
+
"bundle": {
|
|
20
|
+
"patch": "./cordis.patch.yml"
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"test": "node --import ../../test/setup/hermetic-preload.mjs --test test/*.test.mjs"
|
|
25
|
+
},
|
|
26
|
+
"files": [
|
|
27
|
+
"index.js",
|
|
28
|
+
"index.d.ts",
|
|
29
|
+
"format.js",
|
|
30
|
+
"failure.js",
|
|
31
|
+
"config.js",
|
|
32
|
+
"backends.js",
|
|
33
|
+
"router.js",
|
|
34
|
+
"cordis.patch.yml",
|
|
35
|
+
"README.md"
|
|
36
|
+
],
|
|
37
|
+
"license": "UNLICENSED"
|
|
38
|
+
}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
// One search, in a fixed order:
|
|
2
|
+
//
|
|
3
|
+
// 1. NATIVE the route the thread runs on (NATIVE_ROUTES), with that route's own credentials. A route with no
|
|
4
|
+
// native search (a gateway, an OpenAI-compatible host, ...) has no first step.
|
|
5
|
+
// 2. FALLBACKS the configured list, in order (config.js). A fallback whose endpoint or key is absent is left out
|
|
6
|
+
// silently, so a Mac without the owner's Prism service never sees it.
|
|
7
|
+
// 3. FAILURE every backend failed: one structured error naming each backend and why, telling the model web search
|
|
8
|
+
// is unavailable and not to substitute scraping from the shell (zero fallback: a failure is reported).
|
|
9
|
+
//
|
|
10
|
+
// Billing and authorisation errors (402/401/403 and "insufficient balance" bodies) mark the backend dead for the rest of
|
|
11
|
+
// the session; 429/5xx get one bounded retry that honours Retry-After; everything else is tried once.
|
|
12
|
+
import { NATIVE_ROUTES } from './backends.js';
|
|
13
|
+
import { BackendFailure } from './failure.js';
|
|
14
|
+
import { formatBackendMarker, formatUnavailable } from './format.js';
|
|
15
|
+
|
|
16
|
+
export const DEFAULT_RETRY_DELAY_MS = 500;
|
|
17
|
+
export const MAX_RETRY_WAIT_MS = 5000;
|
|
18
|
+
export const UNAVAILABLE_CODE = 'WEB_SEARCH_UNAVAILABLE';
|
|
19
|
+
|
|
20
|
+
const NO_SESSION = Object.freeze({});
|
|
21
|
+
|
|
22
|
+
const abortError = (signal) => Object.assign(new Error('web search aborted', { cause: signal?.reason }), { code: 'WEB_ABORTED' });
|
|
23
|
+
|
|
24
|
+
function defaultSleep(ms, signal) {
|
|
25
|
+
return new Promise((resolve, reject) => {
|
|
26
|
+
if (signal?.aborted === true) return reject(abortError(signal));
|
|
27
|
+
const timer = setTimeout(() => {
|
|
28
|
+
signal?.removeEventListener?.('abort', onAbort);
|
|
29
|
+
resolve();
|
|
30
|
+
}, ms);
|
|
31
|
+
const onAbort = () => {
|
|
32
|
+
clearTimeout(timer);
|
|
33
|
+
reject(abortError(signal));
|
|
34
|
+
};
|
|
35
|
+
signal?.addEventListener?.('abort', onAbort, { once: true });
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* `deps`: `{ ctx, readConfig, backends, sleep?, maxRetryWaitMs? }`. `readConfig()` is the live configuration; `ctx`
|
|
41
|
+
* supplies the initiating session (`ctx.get('agents').currentInitiator().session.requestContext()`).
|
|
42
|
+
*/
|
|
43
|
+
export function createRouter({ ctx, readConfig, backends, sleep = defaultSleep, maxRetryWaitMs = MAX_RETRY_WAIT_MS }) {
|
|
44
|
+
const sessions = new WeakMap();
|
|
45
|
+
|
|
46
|
+
function current() {
|
|
47
|
+
try {
|
|
48
|
+
const session = ctx?.get?.('agents')?.currentInitiator?.()?.session;
|
|
49
|
+
const context = session?.requestContext?.();
|
|
50
|
+
return { session: session !== null && typeof session === 'object' ? session : NO_SESSION, route: context?.provider, model: context?.model };
|
|
51
|
+
} catch {
|
|
52
|
+
return { session: NO_SESSION, route: undefined, model: undefined };
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function stateOf(session) {
|
|
57
|
+
let state = sessions.get(session);
|
|
58
|
+
if (state === undefined) {
|
|
59
|
+
state = { dead: new Map() };
|
|
60
|
+
sessions.set(session, state);
|
|
61
|
+
}
|
|
62
|
+
return state;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
async function runOnce(backend, request, call, parent) {
|
|
66
|
+
const timeout = AbortSignal.timeout(call.config.timeoutMs);
|
|
67
|
+
const signal = parent === undefined ? timeout : AbortSignal.any([parent, timeout]);
|
|
68
|
+
try {
|
|
69
|
+
return await backend.search(request, { ...call, signal });
|
|
70
|
+
} catch (error) {
|
|
71
|
+
// A real abort (the engine's signal) stops the search. The plugin's own time limit aborts the same combined signal,
|
|
72
|
+
// so a backend then rejects with an abort too: that is this backend timing out, and the fallbacks still run.
|
|
73
|
+
if (parent?.aborted === true) throw abortError(parent);
|
|
74
|
+
if (timeout.aborted) throw new BackendFailure('timeout');
|
|
75
|
+
if (error?.code === 'WEB_ABORTED') throw abortError(parent);
|
|
76
|
+
if (error instanceof BackendFailure) throw error;
|
|
77
|
+
throw new BackendFailure('network');
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** One backend with at most one retry, and only for a transient failure whose Retry-After fits the bound. */
|
|
82
|
+
async function attempt(backend, request, call, parent) {
|
|
83
|
+
for (let tries = 0; ; tries += 1) {
|
|
84
|
+
try {
|
|
85
|
+
return await runOnce(backend, request, call, parent);
|
|
86
|
+
} catch (error) {
|
|
87
|
+
if (!(error instanceof BackendFailure) || !error.transient || tries >= 1) throw error;
|
|
88
|
+
const wait = error.retryAfterMs ?? DEFAULT_RETRY_DELAY_MS;
|
|
89
|
+
if (wait > maxRetryWaitMs) throw error;
|
|
90
|
+
await sleep(wait, parent);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
async function plan(config, route, model) {
|
|
96
|
+
const nativeId = NATIVE_ROUTES[route];
|
|
97
|
+
const base = { config, route, model };
|
|
98
|
+
const steps = [];
|
|
99
|
+
if (nativeId !== undefined) steps.push({ id: nativeId, role: 'native' });
|
|
100
|
+
for (const id of config.fallbacks) {
|
|
101
|
+
if (id === nativeId) continue;
|
|
102
|
+
if (backends[id] !== undefined && (await backends[id].configured({ ...base, role: 'fallback' }))) steps.push({ id, role: 'fallback' });
|
|
103
|
+
}
|
|
104
|
+
return steps;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
return {
|
|
108
|
+
/** `ctx.web` search provider entry point. */
|
|
109
|
+
async search(request, signal) {
|
|
110
|
+
const config = readConfig();
|
|
111
|
+
const { session, route, model } = current();
|
|
112
|
+
const state = stateOf(session);
|
|
113
|
+
const attempts = [];
|
|
114
|
+
for (const step of await plan(config, route, model)) {
|
|
115
|
+
const backend = backends[step.id];
|
|
116
|
+
const call = { config, route, model, role: step.role };
|
|
117
|
+
if (signal?.aborted === true) throw abortError(signal);
|
|
118
|
+
const dead = state.dead.get(step.id);
|
|
119
|
+
if (dead !== undefined) {
|
|
120
|
+
attempts.push({ name: backend.name, reason: `${dead}; not retried this session` });
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
if (step.role === 'native' && !(await backend.configured(call))) {
|
|
124
|
+
const ref = await backend.keyRef?.(call);
|
|
125
|
+
attempts.push({ name: backend.name, reason: new BackendFailure('credentials', { ref }).reason });
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
try {
|
|
129
|
+
const result = await attempt(backend, request, call, signal);
|
|
130
|
+
if (step.role === 'native') return result;
|
|
131
|
+
return { ...result, content: formatBackendMarker(backend.name) };
|
|
132
|
+
} catch (error) {
|
|
133
|
+
if (!(error instanceof BackendFailure)) throw error;
|
|
134
|
+
attempts.push({ name: backend.name, reason: error.reason });
|
|
135
|
+
if (error.permanent) state.dead.set(step.id, error.reason);
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
throw Object.assign(new Error(formatUnavailable(attempts, { route })), { code: UNAVAILABLE_CODE, attempts });
|
|
139
|
+
},
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Whether a search on `route` has anything to try: the route's native search has credentials, or a configured
|
|
143
|
+
* fallback is active. Configuration only (no network, no per-session state). The seam's `ready` does NOT use this
|
|
144
|
+
* (see index.js): the tool stays offered so a route with nothing configured gets the structured failure.
|
|
145
|
+
*/
|
|
146
|
+
async configured(route) {
|
|
147
|
+
const config = readConfig();
|
|
148
|
+
const nativeId = NATIVE_ROUTES[route];
|
|
149
|
+
if (nativeId !== undefined && (await backends[nativeId].configured({ config, route, role: 'native' }))) return true;
|
|
150
|
+
for (const id of config.fallbacks) {
|
|
151
|
+
if (id !== nativeId && backends[id] !== undefined && (await backends[id].configured({ config, route, role: 'fallback' }))) return true;
|
|
152
|
+
}
|
|
153
|
+
return false;
|
|
154
|
+
},
|
|
155
|
+
};
|
|
156
|
+
}
|
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
// "X circle" (5c): who an account interacts with most, built on the documented x-circle recipe
|
|
2
|
+
// (https://mdfromx.com/docs/x-circle).
|
|
3
|
+
//
|
|
4
|
+
// Steps: (1) identity, `include_posts=false`; (2) own posts, replies and reposts through the bulk import over a frozen
|
|
5
|
+
// window (`until` fixed once, `since = until − 120 d`); (3) incoming mentions through
|
|
6
|
+
// `search q=(@h OR to:h) feed=latest require_live=true`, every cursor followed (2 and 3 run concurrently); (4) the
|
|
7
|
+
// direct-replies fallback for a bounded set of the owner's posts with replies; (5) parent context
|
|
8
|
+
// (`post context=full replies=recent`) for replies whose target handle is not in the data; (6) missing avatars, at
|
|
9
|
+
// most 4 concurrent identity lookups.
|
|
10
|
+
//
|
|
11
|
+
// Scoring: reply 3, quote 2.5, mention 1.5, repost 1; weights halve every 30 days; per other account the outgoing score
|
|
12
|
+
// `a` and incoming score `b` combine as `a + b + 2·√(a·b)`. Interactions are deduplicated on
|
|
13
|
+
// (post id, other handle, direction, kind); self-interactions are excluded; degraded web snippets are never scored.
|
|
14
|
+
import { failureLine, statusLines, warningText } from './xmd.js';
|
|
15
|
+
|
|
16
|
+
export const CIRCLE_WEIGHTS = Object.freeze({ reply: 3, quote: 2.5, mention: 1.5, repost: 1 });
|
|
17
|
+
export const HALF_LIFE_DAYS = 30;
|
|
18
|
+
export const DEFAULT_CIRCLE_DAYS = 120;
|
|
19
|
+
export const MAX_AVATAR_CONCURRENCY = 4;
|
|
20
|
+
/** Own posts whose replies are sampled through the direct-replies route. */
|
|
21
|
+
export const REPLY_SAMPLE_POSTS = 10;
|
|
22
|
+
/** Replies whose target is looked up through parent context. */
|
|
23
|
+
export const PARENT_CONTEXT_LOOKUPS = 10;
|
|
24
|
+
/** Members shown in the ranked table. */
|
|
25
|
+
export const CIRCLE_TOP = 25;
|
|
26
|
+
const DAY_MS = 86_400_000;
|
|
27
|
+
|
|
28
|
+
const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
29
|
+
const lower = (value) => (typeof value === 'string' ? value.replace(/^@/, '').toLowerCase() : undefined);
|
|
30
|
+
|
|
31
|
+
function postTime(post) {
|
|
32
|
+
const parsed = Date.parse(post?.created_at ?? '');
|
|
33
|
+
return Number.isFinite(parsed) ? parsed : undefined;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Reply targets: the object form `{screen_name, status}` or the legacy array of handles (kept distinct). */
|
|
37
|
+
export function replyTargets(post) {
|
|
38
|
+
const to = post?.replying_to;
|
|
39
|
+
if (isRecord(to)) return typeof to.screen_name === 'string' ? [to.screen_name] : [];
|
|
40
|
+
if (Array.isArray(to)) return to.map((entry) => (typeof entry === 'string' ? entry : entry?.screen_name)).filter((handle) => typeof handle === 'string');
|
|
41
|
+
return [];
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** The replied-to status id, from either form (`replying_to.status` or legacy `replying_to_status`). */
|
|
45
|
+
export function replyStatus(post) {
|
|
46
|
+
if (isRecord(post?.replying_to) && post.replying_to.status !== undefined) return String(post.replying_to.status);
|
|
47
|
+
if (post?.replying_to_status !== undefined && post.replying_to_status !== null) return String(post.replying_to_status);
|
|
48
|
+
return undefined;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Visible mentions: `raw_text.facets` of `type: "mention"` whose start index is at or after
|
|
53
|
+
* `raw_text.display_text_range[0]` (implicit reply prefixes are not mentions). `undefined` when the entity data is
|
|
54
|
+
* absent (unknown coverage, never guessed from text).
|
|
55
|
+
*/
|
|
56
|
+
export function visibleMentions(post) {
|
|
57
|
+
const raw = post?.raw_text;
|
|
58
|
+
if (!isRecord(raw) || !Array.isArray(raw.facets)) return undefined;
|
|
59
|
+
const start = Array.isArray(raw.display_text_range) && typeof raw.display_text_range[0] === 'number' ? raw.display_text_range[0] : 0;
|
|
60
|
+
const out = [];
|
|
61
|
+
for (const facet of raw.facets) {
|
|
62
|
+
if (!isRecord(facet) || facet.type !== 'mention') continue;
|
|
63
|
+
const index = Array.isArray(facet.indices) ? facet.indices[0] : typeof facet.start === 'number' ? facet.start : undefined;
|
|
64
|
+
if (typeof index !== 'number' || index < start) continue;
|
|
65
|
+
const handle = typeof facet.original === 'string' ? facet.original.replace(/^@/, '') : typeof facet.screen_name === 'string' ? facet.screen_name : typeof facet.text === 'string' ? facet.text.replace(/^@/, '') : undefined;
|
|
66
|
+
if (handle !== undefined && handle !== '') out.push(handle);
|
|
67
|
+
}
|
|
68
|
+
return out;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Every interaction one post records relative to `owner`: `{postId, other, direction, kind, at}` where `direction` is
|
|
73
|
+
* `out` (the owner acted) or `in` (someone acted on the owner). Self-interactions are dropped.
|
|
74
|
+
*/
|
|
75
|
+
export function classifyPost(post, owner, { replyTargetOverride } = {}) {
|
|
76
|
+
const me = lower(owner);
|
|
77
|
+
const out = [];
|
|
78
|
+
if (!isRecord(post) || me === undefined) return { interactions: out, mentionsUnknown: false };
|
|
79
|
+
const postId = String(post.id ?? '');
|
|
80
|
+
const at = postTime(post);
|
|
81
|
+
const author = lower(post.author?.screen_name);
|
|
82
|
+
const reposter = lower(post.reposted_by?.screen_name);
|
|
83
|
+
const add = (other, direction, kind) => {
|
|
84
|
+
const handle = lower(other);
|
|
85
|
+
if (handle === undefined || handle === '' || handle === me) return;
|
|
86
|
+
out.push({ postId, other: handle, direction, kind, at });
|
|
87
|
+
};
|
|
88
|
+
// Reposts: the original post with `reposted_by` set; its time is the original's (exact repost times are unknown).
|
|
89
|
+
if (reposter !== undefined) {
|
|
90
|
+
if (reposter === me) add(author, 'out', 'repost');
|
|
91
|
+
else if (author === me) add(reposter, 'in', 'repost');
|
|
92
|
+
return { interactions: out, mentionsUnknown: false };
|
|
93
|
+
}
|
|
94
|
+
const targets = replyTargetOverride !== undefined ? [replyTargetOverride] : replyTargets(post);
|
|
95
|
+
const quoted = lower(post.quote?.author?.screen_name);
|
|
96
|
+
const mentions = visibleMentions(post);
|
|
97
|
+
if (author === me) {
|
|
98
|
+
for (const target of targets) add(target, 'out', 'reply');
|
|
99
|
+
if (quoted !== undefined) add(quoted, 'out', 'quote');
|
|
100
|
+
for (const handle of mentions ?? []) add(handle, 'out', 'mention');
|
|
101
|
+
} else if (author !== undefined) {
|
|
102
|
+
if (targets.some((target) => lower(target) === me)) add(author, 'in', 'reply');
|
|
103
|
+
if (quoted === me) add(author, 'in', 'quote');
|
|
104
|
+
if ((mentions ?? []).some((handle) => lower(handle) === me)) add(author, 'in', 'mention');
|
|
105
|
+
}
|
|
106
|
+
return { interactions: out, mentionsUnknown: mentions === undefined };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Deduplicate on (post id, other handle, direction, kind). */
|
|
110
|
+
export function dedupeInteractions(list) {
|
|
111
|
+
const seen = new Set();
|
|
112
|
+
const out = [];
|
|
113
|
+
for (const item of list) {
|
|
114
|
+
const key = `${item.postId}\u0000${item.other}\u0000${item.direction}\u0000${item.kind}`;
|
|
115
|
+
if (seen.has(key)) continue;
|
|
116
|
+
seen.add(key);
|
|
117
|
+
out.push(item);
|
|
118
|
+
}
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** Weight of one interaction at `asOf`: the kind weight halved every 30 days of age. */
|
|
123
|
+
export function interactionWeight(item, asOf) {
|
|
124
|
+
const base = CIRCLE_WEIGHTS[item.kind] ?? 0;
|
|
125
|
+
if (item.at === undefined) return base;
|
|
126
|
+
const ageDays = Math.max(0, (asOf - item.at) / DAY_MS);
|
|
127
|
+
return base * 0.5 ** (ageDays / HALF_LIFE_DAYS);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** `a + b + 2·√(a·b)` with `a` = outgoing, `b` = incoming. */
|
|
131
|
+
export function combinedScore(a, b) {
|
|
132
|
+
return a + b + 2 * Math.sqrt(a * b);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** Rank the circle: per other handle the outgoing/incoming scores, the combined score and the evidence counts. */
|
|
136
|
+
export function scoreCircle(interactions, asOf) {
|
|
137
|
+
const members = new Map();
|
|
138
|
+
for (const item of dedupeInteractions(interactions)) {
|
|
139
|
+
let member = members.get(item.other);
|
|
140
|
+
if (member === undefined) {
|
|
141
|
+
member = { handle: item.other, a: 0, b: 0, out: { reply: 0, quote: 0, mention: 0, repost: 0 }, in: { reply: 0, quote: 0, mention: 0, repost: 0 } };
|
|
142
|
+
members.set(item.other, member);
|
|
143
|
+
}
|
|
144
|
+
const weight = interactionWeight(item, asOf);
|
|
145
|
+
if (item.direction === 'out') {
|
|
146
|
+
member.a += weight;
|
|
147
|
+
member.out[item.kind] += 1;
|
|
148
|
+
} else {
|
|
149
|
+
member.b += weight;
|
|
150
|
+
member.in[item.kind] += 1;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
return [...members.values()]
|
|
154
|
+
.map((member) => ({ ...member, score: combinedScore(member.a, member.b) }))
|
|
155
|
+
.sort((x, y) => y.score - x.score || x.handle.localeCompare(y.handle));
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
const counts = (c) => `${c.reply}/${c.quote}/${c.mention}/${c.repost}`;
|
|
159
|
+
|
|
160
|
+
/** The ranked table (Markdown) with evidence counts (replies/quotes/mentions/reposts per direction). */
|
|
161
|
+
export function circleTable(ranked, { top = CIRCLE_TOP, avatars = new Map() } = {}) {
|
|
162
|
+
const lines = ['| # | Account | Score | Out (a) | In (b) | Out r/q/m/rt | In r/q/m/rt |', '| --- | --- | --- | --- | --- | --- | --- |'];
|
|
163
|
+
ranked.slice(0, top).forEach((member, index) => {
|
|
164
|
+
const avatar = avatars.get(member.handle);
|
|
165
|
+
lines.push(`| ${index + 1} | @${member.handle}${avatar ? ` ([avatar](${avatar}))` : ''} | ${member.score.toFixed(2)} | ${member.a.toFixed(2)} | ${member.b.toFixed(2)} | ${counts(member.out)} | ${counts(member.in)} |`);
|
|
166
|
+
});
|
|
167
|
+
return lines.join('\n');
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
async function mapLimit(items, limit, fn) {
|
|
171
|
+
const results = new Array(items.length);
|
|
172
|
+
let next = 0;
|
|
173
|
+
const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
|
|
174
|
+
while (next < items.length) {
|
|
175
|
+
const index = next++;
|
|
176
|
+
results[index] = await fn(items[index], index);
|
|
177
|
+
}
|
|
178
|
+
});
|
|
179
|
+
await Promise.all(workers);
|
|
180
|
+
return results;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Build the circle for `args.handle`. `args.until` (default now, frozen once), `args.days` (default 120),
|
|
185
|
+
* `args.pages` (search page budget, default 5). Resolves `{isError, text, value}`.
|
|
186
|
+
*/
|
|
187
|
+
export async function circle(client, args, deps = {}) {
|
|
188
|
+
const handle = typeof args.handle === 'string' ? args.handle.trim().replace(/^@/, '') : '';
|
|
189
|
+
if (handle === '') return { isError: true, text: 'x_read circle: needs handle', value: { ok: false } };
|
|
190
|
+
const now = deps.now ?? Date.now;
|
|
191
|
+
const untilMs = typeof args.until === 'string' && Number.isFinite(Date.parse(args.until)) ? Date.parse(args.until) : now();
|
|
192
|
+
const days = Math.max(1, Math.min(365, Math.floor(Number(args.days) || DEFAULT_CIRCLE_DAYS)));
|
|
193
|
+
const until = new Date(untilMs).toISOString();
|
|
194
|
+
const since = new Date(untilMs - days * DAY_MS).toISOString();
|
|
195
|
+
const signal = deps.signal;
|
|
196
|
+
const fresh = args.fresh === true;
|
|
197
|
+
const coverage = { stages: {}, missingProfiles: [], mentionsUnknownPosts: 0 };
|
|
198
|
+
const avatars = new Map();
|
|
199
|
+
const noteAvatar = (user) => {
|
|
200
|
+
const key = lower(user?.screen_name);
|
|
201
|
+
if (key !== undefined && typeof user.avatar_url === 'string' && user.avatar_url !== '' && !avatars.has(key)) avatars.set(key, user.avatar_url);
|
|
202
|
+
};
|
|
203
|
+
|
|
204
|
+
// (1) identity
|
|
205
|
+
const identity = await client.request(`/api/v1/profiles/${encodeURIComponent(handle)}`, { include_posts: false, format: 'json', nocache: fresh || undefined }, { signal });
|
|
206
|
+
if (!identity.ok) {
|
|
207
|
+
return { isError: true, text: [`x_read circle @${handle}: identity lookup failed.`, failureLine(identity), ...statusLines(identity)].join('\n'), value: { ok: false, stage: 'identity' } };
|
|
208
|
+
}
|
|
209
|
+
const profile = identity.json?.profile;
|
|
210
|
+
if (profile?.protected === true) return { isError: true, text: `x_read circle @${handle}: the account is protected; x.md never reads protected content.`, value: { ok: false, stage: 'identity' } };
|
|
211
|
+
noteAvatar(profile);
|
|
212
|
+
|
|
213
|
+
// (2) own posts and (3) incoming mentions, concurrently, over the same frozen window.
|
|
214
|
+
const [own, incoming] = await Promise.all([
|
|
215
|
+
client.history(handle, { since, until, max_posts: 1000, format: 'json', refresh: fresh || undefined }, { pageBudget: args.pages ?? 5, signal }),
|
|
216
|
+
client.paginate('/api/v1/search', { q: `(@${handle} OR to:${handle})`, feed: 'latest', since, until, limit: 100, require_live: true, format: 'json', nocache: fresh || undefined }, { itemsKey: 'posts', pageBudget: args.pages ?? 5, signal }),
|
|
217
|
+
]);
|
|
218
|
+
coverage.stages.own = { posts: own.posts.length, stop: own.stop, truncated: own.truncated, floorReached: own.floorReached, warnings: own.warnings.map(warningText), ...(own.stop === 'error' ? { error: failureLine(own.res) } : {}) };
|
|
219
|
+
if (own.profile !== undefined) noteAvatar(own.profile);
|
|
220
|
+
let searchUsable = incoming.pages.length > 0 && !incoming.degraded;
|
|
221
|
+
coverage.stages.search = {
|
|
222
|
+
posts: incoming.degraded ? 0 : incoming.items.length,
|
|
223
|
+
pages: incoming.pages.length,
|
|
224
|
+
stop: incoming.stop,
|
|
225
|
+
warnings: incoming.warnings.map(warningText),
|
|
226
|
+
...(incoming.resumeCursor === undefined ? {} : { resumeCursor: incoming.resumeCursor }),
|
|
227
|
+
...(incoming.stop === 'error' ? { error: failureLine(incoming.last) } : {}),
|
|
228
|
+
...(incoming.last?.deferred ? { searchResume: incoming.resumeCursor ?? null, searchRetryAt: incoming.last.retryAt } : {}),
|
|
229
|
+
...(incoming.degraded ? { degraded: true } : {}),
|
|
230
|
+
};
|
|
231
|
+
const interactions = [];
|
|
232
|
+
const collect = (posts, override) => {
|
|
233
|
+
for (const post of posts) {
|
|
234
|
+
if (isRecord(post?.author)) noteAvatar(post.author);
|
|
235
|
+
const { interactions: found, mentionsUnknown } = classifyPost(post, handle, override?.(post));
|
|
236
|
+
if (mentionsUnknown) coverage.mentionsUnknownPosts += 1;
|
|
237
|
+
interactions.push(...found);
|
|
238
|
+
}
|
|
239
|
+
};
|
|
240
|
+
|
|
241
|
+
// (5) parent context: own replies with a status id but no target handle in the data.
|
|
242
|
+
const unknownTargets = own.posts.filter((post) => lower(post?.author?.screen_name) === lower(handle) && !post?.reposted_by && replyTargets(post).length === 0 && replyStatus(post) !== undefined);
|
|
243
|
+
const parentHandles = new Map();
|
|
244
|
+
const parentLookups = unknownTargets.slice(0, PARENT_CONTEXT_LOOKUPS);
|
|
245
|
+
let parentFailures = 0;
|
|
246
|
+
await mapLimit(parentLookups, MAX_AVATAR_CONCURRENCY, async (post) => {
|
|
247
|
+
const status = replyStatus(post);
|
|
248
|
+
const res = await client.request('/api/v1/posts', { url: `https://x.com/i/status/${status}`, context: 'full', replies: 'recent', format: 'json' }, { signal });
|
|
249
|
+
if (!res.ok) {
|
|
250
|
+
parentFailures += 1;
|
|
251
|
+
return;
|
|
252
|
+
}
|
|
253
|
+
const posts = Array.isArray(res.json?.posts) ? res.json.posts : [];
|
|
254
|
+
const parent = posts.find((entry) => String(entry?.id ?? '') === status) ?? posts.find((entry) => entry?.context === 'post');
|
|
255
|
+
if (parent?.author?.screen_name) parentHandles.set(String(post.id), parent.author.screen_name);
|
|
256
|
+
});
|
|
257
|
+
coverage.stages.parentContext = { lookups: parentLookups.length, resolved: parentHandles.size, failed: parentFailures, skipped: Math.max(0, unknownTargets.length - parentLookups.length) };
|
|
258
|
+
collect(own.posts, (post) => (parentHandles.has(String(post?.id)) ? { replyTargetOverride: parentHandles.get(String(post.id)) } : undefined));
|
|
259
|
+
if (searchUsable) collect(incoming.items);
|
|
260
|
+
|
|
261
|
+
// (4) direct-replies fallback: a bounded selection of the owner's own (non-repost) posts with replies.
|
|
262
|
+
const replyCandidates = [...new Map(own.posts
|
|
263
|
+
.filter((post) => lower(post?.author?.screen_name) === lower(handle) && !post?.reposted_by && Number(post?.replies) > 0)
|
|
264
|
+
.map((post) => [String(post.id), post])).values()]
|
|
265
|
+
.sort((x, y) => Number(y.replies) - Number(x.replies))
|
|
266
|
+
.slice(0, REPLY_SAMPLE_POSTS);
|
|
267
|
+
let sampled = 0;
|
|
268
|
+
let sampleFailures = 0;
|
|
269
|
+
for (const post of replyCandidates) {
|
|
270
|
+
const res = await client.request(`/api/v1/posts/${post.id}/replies`, { limit: 100, format: 'json', nocache: fresh || undefined }, { signal });
|
|
271
|
+
if (!res.ok) {
|
|
272
|
+
sampleFailures += 1;
|
|
273
|
+
continue;
|
|
274
|
+
}
|
|
275
|
+
const replies = Array.isArray(res.json?.posts) ? res.json.posts : [];
|
|
276
|
+
sampled += replies.length;
|
|
277
|
+
// A direct reply to the owner's post is an incoming reply even when its `replying_to` is absent.
|
|
278
|
+
collect(replies, (reply) => (replyTargets(reply).length === 0 ? { replyTargetOverride: handle } : undefined));
|
|
279
|
+
}
|
|
280
|
+
coverage.stages.replySample = { posts: replyCandidates.length, replies: sampled, failed: sampleFailures };
|
|
281
|
+
|
|
282
|
+
const ranked = scoreCircle(interactions, untilMs);
|
|
283
|
+
|
|
284
|
+
// (6) missing avatars for the members shown, at most 4 concurrent identity lookups.
|
|
285
|
+
const shown = ranked.slice(0, CIRCLE_TOP).filter((member) => !avatars.has(member.handle));
|
|
286
|
+
await mapLimit(shown, MAX_AVATAR_CONCURRENCY, async (member) => {
|
|
287
|
+
const res = await client.request(`/api/v1/profiles/${encodeURIComponent(member.handle)}`, { include_posts: false, format: 'json' }, { signal });
|
|
288
|
+
if (res.ok && isRecord(res.json?.profile)) noteAvatar(res.json.profile);
|
|
289
|
+
if (!avatars.has(member.handle)) coverage.missingProfiles.push(member.handle);
|
|
290
|
+
});
|
|
291
|
+
|
|
292
|
+
const source = searchUsable ? (sampled > 0 ? 'search + reply sample' : 'search') : sampled > 0 ? 'reply sample' : 'own posts only';
|
|
293
|
+
const partial = own.stop !== 'complete' || !searchUsable || incoming.stop !== 'complete' || sampleFailures > 0 || parentFailures > 0;
|
|
294
|
+
const lines = [
|
|
295
|
+
`x_read circle @${handle} · ${ranked.length} accounts · ${days}-day window ${since} → ${until} (frozen)`,
|
|
296
|
+
`Source: ${source}${partial ? ' · PARTIAL' : ''} — a sample, never "mentions complete".`,
|
|
297
|
+
`Own posts read: ${own.posts.length} (${own.stop}${own.truncated ? ', truncated' : ''}${own.floorReached ? ', floor reached' : ''})`,
|
|
298
|
+
`Incoming read: ${searchUsable ? incoming.items.length : 0} from search (${incoming.pages.length} page${incoming.pages.length === 1 ? '' : 's'}, ${incoming.stop}${incoming.degraded ? ', degraded snippets not scored' : ''}) + ${sampled} replies sampled from ${replyCandidates.length} posts`,
|
|
299
|
+
incoming.stop === 'error' ? `Search failed: ${failureLine(incoming.last)}${incoming.last?.deferred ? ` search_resume: ${incoming.resumeCursor ?? '(first page)'} · search_retry_at: ${incoming.last.retryAt}` : ''}` : '',
|
|
300
|
+
incoming.resumeCursor !== undefined ? `Search resume cursor: ${incoming.resumeCursor}` : '',
|
|
301
|
+
own.stop === 'error' ? `Own-post import failed: ${failureLine(own.res)}` : '',
|
|
302
|
+
coverage.mentionsUnknownPosts > 0 ? `Mention coverage unknown for ${coverage.mentionsUnknownPosts} posts (no raw_text entities).` : '',
|
|
303
|
+
coverage.missingProfiles.length > 0 ? `Missing profiles: ${coverage.missingProfiles.map((h) => `@${h}`).join(', ')}` : '',
|
|
304
|
+
[...own.warnings, ...incoming.warnings].length > 0 ? `Warnings: ${[...own.warnings, ...incoming.warnings].map(warningText).join('; ')}` : '',
|
|
305
|
+
'Scoring: reply 3, quote 2.5, mention 1.5, repost 1; halved every 30 days; score = a + b + 2·√(a·b) (a outgoing, b incoming).',
|
|
306
|
+
...statusLines(incoming.last ?? identity),
|
|
307
|
+
].filter(Boolean);
|
|
308
|
+
const table = ranked.length === 0 ? '(no interactions found in the data read)' : circleTable(ranked, { avatars });
|
|
309
|
+
return {
|
|
310
|
+
isError: false,
|
|
311
|
+
text: `${lines.join('\n')}\n\n${table}`,
|
|
312
|
+
value: {
|
|
313
|
+
ok: true,
|
|
314
|
+
mode: 'circle',
|
|
315
|
+
handle,
|
|
316
|
+
since,
|
|
317
|
+
until,
|
|
318
|
+
source,
|
|
319
|
+
partial,
|
|
320
|
+
coverage,
|
|
321
|
+
members: ranked.slice(0, CIRCLE_TOP).map((member) => ({ handle: member.handle, score: member.score, a: member.a, b: member.b, out: member.out, in: member.in, avatar: avatars.get(member.handle) })),
|
|
322
|
+
},
|
|
323
|
+
};
|
|
324
|
+
}
|