@listeningkit/log 0.1.0 → 0.1.3

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 (158) hide show
  1. package/AGENTS.md +84 -0
  2. package/README.md +65 -1683
  3. package/docs/README.md +27 -0
  4. package/docs/accounts.md +63 -0
  5. package/docs/accountsAndListings.md +76 -58
  6. package/docs/adsPower.md +78 -44
  7. package/docs/browserSetup.md +58 -0
  8. package/docs/browsers.md +44 -26
  9. package/docs/commandNaming.md +27 -30
  10. package/docs/conversations.md +30 -41
  11. package/docs/deployment.md +78 -152
  12. package/docs/deviceIsolation/deepResearch.json +1130 -1130
  13. package/docs/deviceIsolation/deepResearch.md +353 -353
  14. package/docs/diagrams/browsers.mmd +1 -1
  15. package/docs/diagrams/commands.mmd +8 -0
  16. package/docs/diagrams/hooks.mmd +2 -2
  17. package/docs/diagrams/platforms.mmd +7 -0
  18. package/docs/diagrams/surface.mmd +3 -3
  19. package/docs/errorCatalog.md +7 -2
  20. package/docs/groupListening.md +55 -52
  21. package/docs/groupMembers.md +47 -34
  22. package/docs/groupRead.md +89 -57
  23. package/docs/guides/facebookBrowser.md +21 -21
  24. package/docs/guides/facebookFlows.md +6 -6
  25. package/docs/guides/facebookMarketplace.md +1 -1
  26. package/docs/guides/knowledgeAndSearch.md +5 -3
  27. package/docs/guides/linkedin.md +50 -0
  28. package/docs/guides/logMcpInstructions.md +37 -24
  29. package/docs/guides/runsAndEvidence.md +5 -5
  30. package/docs/guides/xAccount.md +7 -3
  31. package/docs/guides/xInbox.md +9 -5
  32. package/docs/guides/xSending.md +86 -27
  33. package/docs/howItWorks.md +104 -0
  34. package/docs/infra/apiKeys.md +27 -0
  35. package/docs/infra/node02.md +96 -3
  36. package/docs/install.md +68 -0
  37. package/docs/knowledgeBase.md +35 -34
  38. package/docs/layout.md +53 -0
  39. package/docs/lifecycle.md +92 -66
  40. package/docs/listingMedia.md +25 -46
  41. package/docs/listingMonitor.md +43 -0
  42. package/docs/listingPublish/README.md +21 -39
  43. package/docs/listingPublish/captchaKraken.md +33 -75
  44. package/docs/listingPublish/formFill.md +28 -35
  45. package/docs/listingPublish/imagePipeline.md +55 -95
  46. package/docs/listingPublish/sources.md +60 -79
  47. package/docs/listingPublish/stateMachine.md +45 -79
  48. package/docs/mcp.md +56 -0
  49. package/docs/namingConventions.md +23 -33
  50. package/docs/platformGuides/discord.md +44 -0
  51. package/docs/platformGuides/facebook.md +52 -0
  52. package/docs/platformGuides/linkedin.md +37 -0
  53. package/docs/platformGuides/reddit.md +34 -0
  54. package/docs/platformGuides/x.md +68 -0
  55. package/docs/platforms/facebook/README.md +2 -2
  56. package/docs/platforms/linkedin/README.md +27 -0
  57. package/docs/providerResearch/agentVmHosts.json +1465 -1465
  58. package/docs/providerResearch/agentVmHosts.md +760 -760
  59. package/docs/providerResearch/prompts/agentVmHosts.poll.log +36 -36
  60. package/docs/providerResearch/prompts/agentVmHosts.run.json +8 -8
  61. package/docs/providerResearch/prompts/cloudBrowsersAndAntidetect.poll.log +22 -22
  62. package/docs/providerResearch/prompts/cloudBrowsersAndAntidetect.run.json +8 -8
  63. package/docs/providerResearch/prompts/cloudPhonesAndDevices.poll.log +24 -24
  64. package/docs/providerResearch/prompts/cloudPhonesAndDevices.run.json +8 -8
  65. package/docs/providerResearch/prompts/proxiesAndCaptcha.poll.log +34 -34
  66. package/docs/providerResearch/prompts/proxiesAndCaptcha.run.json +8 -8
  67. package/docs/providerResearch/prompts/selfManagedCompute.poll.log +49 -49
  68. package/docs/providerResearch/prompts/selfManagedCompute.run.json +8 -8
  69. package/docs/providerResearch/proxiesAndCaptcha.json +1189 -1189
  70. package/docs/providerResearch/proxiesAndCaptcha.md +643 -643
  71. package/docs/providerResearch/selfManagedCompute.json +832 -832
  72. package/docs/providerResearch/selfManagedCompute.md +62 -62
  73. package/docs/proxies.md +205 -167
  74. package/docs/proxyVendors/README.md +40 -29
  75. package/docs/proxyVendors/byteful.md +52 -42
  76. package/docs/rea/README.md +36 -68
  77. package/docs/rea/comparison.md +41 -71
  78. package/docs/rea/facebookClient.md +65 -127
  79. package/docs/rea/publicExamples.md +42 -75
  80. package/docs/rea/roadmap.md +23 -70
  81. package/docs/rea/sources.md +25 -67
  82. package/docs/rea/spec.md +44 -76
  83. package/docs/recordToFlow.md +55 -66
  84. package/docs/reference.md +1407 -0
  85. package/docs/signingIn.md +29 -0
  86. package/docs/site.json +62 -0
  87. package/docs/status.md +93 -69
  88. package/docs/twenty.md +84 -0
  89. package/docs/twitterPlatform.md +95 -56
  90. package/docs/useCases/README.md +1 -1
  91. package/docs/useCases/twitter/README.md +1 -1
  92. package/docs/usingLog.md +44 -0
  93. package/docs/vendors/order_33923855504144.txt +10 -0
  94. package/docs/voice/perPersonVoice.md +38 -40
  95. package/package.json +8 -5
  96. package/python/checks/linkedinTransport.py +67 -0
  97. package/python/errors/errorCatalog.json +60 -4
  98. package/python/linkedinApi/__init__.py +0 -0
  99. package/python/linkedinApi/engine.py +80 -0
  100. package/python/twitterApi/engine.py +159 -10
  101. package/python/twitterApi/host.py +221 -0
  102. package/python/twitterApi/inboxSync.py +5 -1
  103. package/scripts/checks/checkAgentHooks.ts +1 -1
  104. package/scripts/checks/checkFacebookClientDocs.mjs +3 -3
  105. package/scripts/checks/checkLinkedinTransport.ts +18 -0
  106. package/scripts/docs/buildDocs.ts +7 -1
  107. package/scripts/docs/syncSiteDocs.mjs +147 -0
  108. package/scripts/hooks/engines.ts +3 -3
  109. package/scripts/twenty/twentySetup.mjs +1 -1
  110. package/skills/accountToDryRun/SKILL.md +1 -1
  111. package/skills/adsPower/SKILL.md +6 -6
  112. package/skills/flow/SKILL.md +6 -6
  113. package/skills/humanMouse/SKILL.md +3 -3
  114. package/skills/inspect/SKILL.md +10 -10
  115. package/skills/logCli/SKILL.md +24 -24
  116. package/skills/profileSetup/SKILL.md +2 -2
  117. package/skills/reaCapture/SKILL.md +5 -5
  118. package/skills/xPosting/SKILL.md +59 -4
  119. package/skills/xchatReplies/SKILL.md +4 -4
  120. package/src/agentHooks/liveLog/index.ts +13 -1
  121. package/src/agentHooks/registry/index.ts +2 -2
  122. package/src/cli/inspect/index.ts +1 -1
  123. package/src/cli/linkedin/helpers/cookies.ts +125 -0
  124. package/src/cli/linkedin/helpers/index.ts +1 -0
  125. package/src/cli/linkedin/index.ts +62 -0
  126. package/src/cli/runner/client.ts +2 -0
  127. package/src/cli/runner/helpers/commandIndex.ts +2 -0
  128. package/src/cli/runner/helpers/platforms.ts +3 -1
  129. package/src/cli/runner/index.ts +3 -0
  130. package/src/cli/runner/types.ts +1 -0
  131. package/src/cli/twitter/helpers/cookies.ts +5 -4
  132. package/src/directApi/engine/client.ts +17 -3
  133. package/src/directApi/engine/types.ts +2 -1
  134. package/src/errors/catalog/types.ts +49 -4
  135. package/src/inbox/watch/client.ts +9 -9
  136. package/src/linkedin/account/index.ts +1 -0
  137. package/src/linkedin/account/session/client.ts +30 -0
  138. package/src/linkedin/account/session/index.ts +1 -0
  139. package/src/mcp/freshness/client.ts +18 -1
  140. package/src/mcp/server/helpers/agentRules.ts +22 -16
  141. package/src/mcp/server/helpers/guides.ts +1 -0
  142. package/src/mcp/server/types.ts +5 -5
  143. package/src/subq/decisions/client.ts +13 -2
  144. package/src/surface/readme/index.ts +1 -1
  145. package/vendor/openLinkedinApi/LICENSE +21 -0
  146. package/vendor/openLinkedinApi/README.md +355 -0
  147. package/vendor/openLinkedinApi/UPSTREAM +1 -0
  148. package/vendor/openLinkedinApi/open_linkedin_api/__init__.py +7 -0
  149. package/vendor/openLinkedinApi/open_linkedin_api/client.py +163 -0
  150. package/vendor/openLinkedinApi/open_linkedin_api/cookie_repository.py +70 -0
  151. package/vendor/openLinkedinApi/open_linkedin_api/linkedin.py +1787 -0
  152. package/vendor/openLinkedinApi/open_linkedin_api/settings.py +7 -0
  153. package/vendor/openLinkedinApi/open_linkedin_api/transport.py +10 -0
  154. package/vendor/openLinkedinApi/open_linkedin_api/utils/__init__.py +0 -0
  155. package/vendor/openLinkedinApi/open_linkedin_api/utils/helpers.py +266 -0
  156. package/vendor/openLinkedinApi/pyproject.toml +25 -0
  157. package/vendor/twikit/tests/test_transaction_cache.py +69 -0
  158. package/vendor/twikit/twikit/x_client_transaction/transaction.py +21 -0
package/AGENTS.md CHANGED
@@ -1231,6 +1231,90 @@ facts, not suggestions. Newest at the bottom. Never delete one without matt.
1231
1231
  decides: a 344 stops the run and nothing more goes out until matt says
1232
1232
  so. Discord keeps 60, every other platform 40.
1233
1233
 
1234
+ 102. 2026-10-30 · mandeep: LinkedIn goes out looking like a browser, the
1235
+ way X does (rule 81). `vendor/openLinkedinApi` reaches LinkedIn only
1236
+ through one curl_cffi `Session` in `open_linkedin_api/transport.py`,
1237
+ pinned to one impersonation target (`IMPERSONATE`, `chrome150`, the
1238
+ closest to the Chrome its cookies come from), sending the target's own
1239
+ user agent, never the library's fixed one or plain `requests`.
1240
+ `python/checks/linkedinTransport.py` refuses anything else (`bun run
1241
+ check:linkedinTransport`, pre-commit and pre-push). Every LinkedIn call
1242
+ runs through the account's governor (`python/platformKit/engine.py`), and
1243
+ a LinkedIn account writes at most 10 times a day (`WRITES_PER_DAY`), not
1244
+ 40 (rule 91).
1245
+
1246
+ 103. 2026-10-31 · matt: log-cli moves into the public log repo, and we work
1247
+ there. log-cli on GitHub is archived. "The readme is specifically for how
1248
+ to set up": why use it, what it's for, how to install and use it, and how
1249
+ we use it, about this project and nothing else of ours. Everything
1250
+ technical lives in `docs/`, a page per subject: the generated reference
1251
+ (`docs/reference.md`, from `bun run docs:build`, which replaces rule 56's
1252
+ README section), the guides, the use cases, the platforms, MCP setup
1253
+ (`docs/mcp.md`) and the Mermaid diagrams (`docs/diagrams`). Rule one stays
1254
+ first in AGENTS.md and the MCP instructions, no longer in the README
1255
+ (this narrows rule 76). The docs site at log.listeningkit.com/docs is
1256
+ Fumadocs, built from `docs/` on every site build
1257
+ (`scripts/docs/syncSiteDocs.mjs`). lefthook's `siteDocs` (`bun run
1258
+ check:siteDocs`, pre-commit and pre-push) refuses a page without a title
1259
+ or a link to a file that doesn't exist, beside `docs`. log is installed
1260
+ as the npm package `@listeningkit/log` and runs as `log` and `logMcp`:
1261
+ docs, skills and messages say `log …`, never `bun bin/log.ts`. "We don't
1262
+ use Convex at all": no Convex, and no dashboard. The site is the landing
1263
+ page plus the docs.
1264
+
1265
+ 104. 2026-11-01 · matt: "the timing stuff there i saw you hand rolled the
1266
+ outbound stuff when it should be queued and it has to have random
1267
+ intervals, but the bundle itself actually reveals more information".
1268
+ On 2026-11-01 matthewsoldit got a soft block, then X's 226 ("looks
1269
+ automated") on a reply. The live log showed 8 thread reads fired in
1270
+ 0.2 s by two parallel helpers while sends went out from a hand-written
1271
+ loop, and every `log twitter` call was a fresh client that loaded
1272
+ x.com's home page and its signer before acting, so a 3-line dm was 3
1273
+ cold starts in 9 s. X's own web client (`sign.o` in its x-web bundle,
1274
+ read 2026-11-01) loads the page once and signs every call from it.
1275
+ From now on: more than one send goes through the queue (`log twitter
1276
+ queue build|plan|run`, random times), never a hand-rolled loop and
1277
+ never helpers reading or sending on one account in parallel. The X
1278
+ engine takes one call per account at a time (`engine.lock`, refused
1279
+ with `accountBusy` after 15 min), waits 4 to 11 s after the last call,
1280
+ and keeps the transaction key in `clientTransaction.json` for 3 hours
1281
+ (`python/twitterApi/engine.py`, `vendor/twikit` `ClientTransaction.state`
1282
+ and `restore`).
1283
+
1284
+ 105. 2026-11-01 · matt: "we cannot be opening multiple sessions there,
1285
+ that defeats the core purpose of what we use this tool for ... it
1286
+ should always be one, and then it needs to loudly create issues". An X
1287
+ account has one session, always. Every X call (CLI, MCP, hooks, the
1288
+ queue, the X Chat watch) goes through the account's one engine host
1289
+ (`python/twitterApi/host.py`, started on the first call, closed after
1290
+ 30 idle minutes or when the engine code changes): one twikit client,
1291
+ one connection, one cookie jar and one transaction key, the way X's
1292
+ own web app keeps one page and signs every call from it (x-web
1293
+ `startup-dynamic`, read with rea 2026-11-01). A second host can't
1294
+ start (`host.lock`); a call that can't reach the host is refused with
1295
+ `xSessionHostDown` and sends nothing, never falls back to a session of
1296
+ its own. The hook's account line shows the open session (pid, since,
1297
+ calls). `LOG_TWITTER_HOST=inline` runs the old way, for tests only.
1298
+
1299
+ 106. 2026-11-01 · matt: "when doing stuff like changing the code or
1300
+ anything, ensure that there hasn't been any changes to it locally, like
1301
+ to the engine ... you're not allowed hand-rolled commands, it always has
1302
+ to be through the MCP basically". Two things, enforced by the hooks:
1303
+ - **Through the MCP only.** Every log action an agent takes goes through
1304
+ the log MCP tools (`mcp__log__…`), never a hand-run `log …` or `bun
1305
+ bin/log.ts …` from a shell. The PreToolUse hook (`liveLogs`,
1306
+ `handRunDenial` in `src/agentHooks/liveLog`) refuses one and names the
1307
+ MCP instead. Only the terminal-only prompts (`TERMINAL_ONLY`: launch,
1308
+ login, mcp, chat pin, cookies save, messenger pin) are run in a
1309
+ terminal, by matt. A stale MCP server is said to matt (restart the
1310
+ app), never worked around.
1311
+ - **Local changes first.** Before changing code, check what is already
1312
+ changed and uncommitted in the checkout. The engines hook says it
1313
+ loudly at session start and whenever it changes (`>>> UNCOMMITTED
1314
+ LOCAL CHANGES`, `localChangesLine` in `src/mcp/freshness`): read each
1315
+ one's diff, and never overwrite, revert, stage, publish or ship
1316
+ someone else's uncommitted work without matt.
1317
+
1234
1318
  ## Checks
1235
1319
 
1236
1320
  - Run `bun run check` before pushing: no comments (rule 70), naming gate, `tsc --noEmit`, `bun test`.