kimaki 0.4.76 → 0.4.78

package/skills/npm-package/SKILL.md

@@ -140,6 +140,8 @@ Use Node ESM-compatible compiler settings:
 ```json
 {
   "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
     "rootDir": "src",
     "outDir": "dist",
     "module": "nodenext",
@@ -159,7 +161,25 @@ Use Node ESM-compatible compiler settings:
 
 - Always use "rootDir": "src"
 - Add `"DOM"` to `lib` only when browser globals are needed.
-- Keep source imports with `.js` extensions in TypeScript ESM files.
+- Use `.ts` and `.tsx` extensions in source imports. `tsc` rewrites them to
+  `.js` in the emitted `dist/` output automatically via
+  `rewriteRelativeImportExtensions`. This means source code works directly in
+  runtimes like `tsx`, `bun`, and frameworks like Next.js that expect `.ts`
+  extensions, while the published `dist/` has correct `.js` imports that Node.js
+  and other consumers resolve without issues.
+  ```ts
+  // source (src/index.ts) — use .ts/.tsx extensions
+  import { helper } from './utils.ts'
+  import { Button } from './button.tsx'
+
+  // emitted output (dist/index.js) — tsc rewrites to .js
+  // import { helper } from './utils.js'
+  // import { Button } from './button.js'
+  ```
+- Only relative imports are rewritten. Path aliases (`paths` in tsconfig) are
+  not supported by `rewriteRelativeImportExtensions` — this is fine since npm
+  packages should use relative imports anyway.
+- Requires TypeScript 5.7+. Pin the typescript devDependency to at least `5.7.0`.
 - Install `@types/node` as a dev dependency whenever Node APIs are used.
 - If generation is required, keep generators in `scripts/*.ts` and invoke them
   from package scripts before build/publish.
@@ -201,4 +221,3 @@ test files should be close with the associated source files. for example if you
 
 - if you need to use zod always use latest version
 - always install packages as dev dependencies if used only for scripts, testing or types only
--

package/skills/playwriter/SKILL.md

@@ -8,7 +8,7 @@ description: Control the user own Chrome browser via Playwriter extension with P
 **Before using playwriter, you MUST run this command:**
 
 ```bash
-playwriter skill
+playwriter skill # IMPORTANT! do not use | head here. read in full!
 ```
 
 This outputs the complete documentation including:

package/skills/x-articles/SKILL.md

@@ -0,0 +1,554 @@
+---
+name: x-articles
+description: >
+  Edit x.com (Twitter) long-form article drafts reliably. Use this for
+  markdown imports, bulk formatting, code blocks, headings, lists, and
+  repeated inline styling. Inspect and validate with Playwriter, but prefer
+  x.com (Twitter) article GraphQL mutations for deterministic updates.
+version: 0.1.0
+---
+
+<!-- Skill for editing x.com (Twitter) article drafts through Playwriter plus content-state mutations. -->
+
+Use this skill when editing long-form article drafts on `x.com/compose/articles`
+(Twitter Articles).
+
+## Read Playwriter First
+
+Before using this skill, read the `playwriter` skill and run:
+
+```bash
+playwriter skill
+```
+
+This skill assumes Playwriter is already set up and connected to the user's
+existing Chrome session.
+
+Read the full output. Do not pipe it through `head`, `tail`, or other
+truncation commands.
+
+## Core idea
+
+Use Playwriter for three things:
+
+1. connect to the already-open x.com (Twitter) article draft
+2. inspect the editor and capture one real network mutation
+3. validate the final rendered result after updates
+
+For anything bigger than a tiny tweak, do **not** rely on manual typing inside
+the editor. Generate the article `content_state` locally and send the same
+GraphQL mutation x.com (Twitter) already uses.
+
+## Editor model
+
+The article body is represented as a `content_state` object with two main
+parts:
+
+- `blocks`: ordered content blocks
+- `entity_map`: supporting entities, especially code blocks
+
+Important block types:
+
+- `unstyled` — normal paragraph
+- `header-two` — section subheading
+- `ordered-list-item` — numbered list item
+- `atomic` — embedded block like a markdown code block
+
+Important entity type:
+
+- `MARKDOWN` — used for code blocks, with the markdown fence stored in
+  `entity_map[*].value.data.markdown`
+
+Longer example `content_state`:
+
+````json
+{
+  "blocks": [
+    {
+      "key": "k0",
+      "text": "event sourcing for application state",
+      "type": "header-two",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k1",
+      "text": "your clanker loves state",
+      "type": "unstyled",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": [
+        { "offset": 19, "length": 5, "style": "Bold" }
+      ]
+    },
+    {
+      "key": "k2",
+      "text": "doubles your final app state",
+      "type": "ordered-list-item",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k3",
+      "text": "doubles your bugs",
+      "type": "ordered-list-item",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k4",
+      "text": " ",
+      "type": "atomic",
+      "data": {},
+      "entity_ranges": [
+        { "key": 0, "offset": 0, "length": 1 }
+      ],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k5",
+      "text": "if you can derive it, don't store it.",
+      "type": "unstyled",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": [
+        { "offset": 7, "length": 6, "style": "Bold" }
+      ]
+    }
+  ],
+  "entity_map": [
+    {
+      "key": "0",
+      "value": {
+        "type": "MARKDOWN",
+        "mutability": "Mutable",
+        "data": {
+          "markdown": "```typescript\nfunction shouldShowFooter() {\n  return true\n}\n```"
+        }
+      }
+    }
+  ]
+}
+````
+
+This is the minimum mental model:
+
+- `blocks` is the article in order
+- each paragraph, heading, and list item is a separate block
+- code blocks are `atomic` blocks that point into `entity_map`
+- inline bold lives in `inline_style_ranges`
+
+## Recommended workflow
+
+### 1. Open or locate the draft
+
+Find the existing article editor page in the connected browser. The URL format
+is:
+
+```text
+https://x.com/compose/articles/edit/<article_id>
+```
+
+Always parse and keep the numeric `article_id`. The content mutation needs it.
+
+Example Playwriter check:
+
+```bash
+playwriter session new
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+if (!state.page) {
+  throw new Error("No article editor page found")
+}
+console.log(state.page.url())
+'
+```
+
+### 2. Explore with small manual edits first
+
+Use the UI to learn how the editor reacts before doing bulk updates. Good
+exploration tasks:
+
+- add one paragraph
+- convert one block to `Sottotitolo`
+- insert one code block
+- bold one word in one paragraph
+
+After each change, inspect the rendered HTML with `getCleanHTML()`.
+
+Example validation command:
+
+```bash
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+console.log(
+  await getCleanHTML({
+    locator: state.page.locator("[data-testid=\"composer\"]"),
+    showDiffSinceLastCall: false,
+  }),
+)
+'
+```
+
+### 3. Capture real network traffic
+
+Watch GraphQL requests while making one tiny manual change. This gives you the
+exact mutation names and payload shapes used by the current x.com (Twitter)
+editor.
+
+The two important mutations found in this session were:
+
+- `ArticleEntityUpdateTitle`
+- `ArticleEntityUpdateContent`
+
+The content mutation URL looked like:
+
+```text
+https://x.com/i/api/graphql/<queryId>/ArticleEntityUpdateContent
+```
+
+The exact `queryId` can change over time. Do not hardcode it blindly without
+first confirming it from a real request in the current session.
+
+Example request logger:
+
+```bash
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+state.requests = []
+state.page.removeAllListeners("request")
+state.page.on("request", (req) => {
+  if (req.url().includes("ArticleEntity") || req.url().includes("graphql")) {
+    state.requests.push({
+      url: req.url(),
+      method: req.method(),
+      postData: req.postData(),
+    })
+  }
+})
+console.log(
+  "Ready: now make one tiny manual edit in the page, then rerun this command to inspect state.requests",
+)
+'
+```
+
+### 4. Use direct content updates for bulk work
+
+Once you know the current mutation shape, generate the full `content_state`
+locally and send the content update directly.
+
+This is the reliable path for:
+
+- full markdown import
+- replacing large sections
+- converting paragraphs to ordered lists
+- adding one bold keyword per paragraph
+- fixing code block languages
+
+Concrete pattern:
+
+1. build `content_state` in a local JSON file
+2. read `ct0` from `document.cookie`
+3. send `ArticleEntityUpdateContent` with the same `queryId` and feature flags
+4. reload the page
+
+### 5. Reload and validate
+
+After every direct mutation:
+
+1. reload the article editor page
+2. inspect `getCleanHTML()`
+3. search for expected headings, list items, bold splits, and code labels
+
+Do not trust the visual editor alone.
+
+Example reload + search:
+
+```bash
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+await state.page.reload({ waitUntil: "domcontentloaded" })
+await waitForPageLoad({ page: state.page, timeout: 8000 })
+console.log(
+  await getCleanHTML({
+    locator: state.page.locator("[data-testid=\"composer\"]"),
+    search: /debugging with event streams|typescript|ordered-list-item/i,
+    showDiffSinceLastCall: false,
+  }),
+)
+'
+```
+
+## Block type cheatsheet
+
+### Paragraphs
+
+Use:
+
+```json
+{
+  "type": "unstyled",
+  "text": "your paragraph text"
+}
+```
+
+### Subheadings
+
+Use:
+
+```json
+{
+  "type": "header-two",
+  "text": "debugging with event streams"
+}
+```
+
+### Numbered lists
+
+Each item is its own block:
+
+```json
+{
+  "type": "ordered-list-item",
+  "text": "doubles your bug surface"
+}
+```
+
+### Code blocks
+
+Code blocks are not plain text blocks. They are:
+
+1. one `atomic` block in `blocks`
+2. one `MARKDOWN` entity in `entity_map`
+
+The atomic block points to the entity with `entity_ranges`.
+
+The entity markdown should include the full fence, for example:
+
+````text
+```typescript
+const x = 1
+```
+````
+
+If you want the visible language label to say `typescript`, the stored fence
+must be ` ```typescript `, not ` ```ts `.
+
+## Inline styles
+
+Bold text is represented with `inlineStyleRanges` inside a block.
+
+Important session learning:
+
+- the style name is `Bold`
+- not `BOLD`
+
+Example:
+
+```json
+{
+  "text": "your clanker loves state",
+  "inlineStyleRanges": [
+    { "offset": 19, "length": 5, "style": "Bold" }
+  ]
+}
+```
+
+Always calculate offsets against the raw block text exactly as stored.
+
+## Known UI pitfalls
+
+The manual editor flow has several traps:
+
+### Heading inheritance
+
+After creating a heading, pressing `Enter` once can keep the next block in the
+same heading style. To reset to a paragraph, press `Enter` again.
+
+### Post-code-block cursor placement
+
+Typing after a code block is unreliable. The editor can:
+
+- append text to the wrong block
+- split text unexpectedly
+- create stray headings
+- leave part of a sentence in one block and the rest in another
+
+For anything more than a tiny manual tweak, use direct content updates instead.
+
+### Visual feedback is incomplete
+
+The editor can look correct while the underlying block structure is wrong.
+Always inspect the HTML or mutation payload.
+
+### Playwriter sessions can reset
+
+If the relay server restarts or the extension reconnects, Playwriter sessions
+can disappear. If that happens, create a new Playwriter session and reattach to
+the already-open article page.
+
+Recovery command:
+
+```bash
+playwriter session new
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+if (!state.page) {
+  throw new Error("No article editor page found")
+}
+console.log(state.page.url())
+'
+```
+
+## Auth and request details
+
+Direct content updates need proper auth headers. In this session, the direct
+`fetch()` worked only after including:
+
+- the X bearer token
+- `x-csrf-token` from the `ct0` cookie
+- the standard X active-user/auth/client-language headers
+
+If you get `403`, inspect the successful browser request and match its headers.
+
+In this session, the direct fetch succeeded only after matching:
+
+- bearer token
+- `x-csrf-token`
+- `x-twitter-active-user`
+- `x-twitter-auth-type`
+- `x-twitter-client-language`
+
+## Validation checklist
+
+After updating an article, verify all of these:
+
+1. correct title in the title field
+2. headings appear as `header-two`
+3. ordered lists appear as `ordered-list-item`
+4. code blocks render as `markdown-code-block`
+5. code block language labels say what you expect, for example `typescript`
+6. bold keywords are split into separate styled spans in the HTML
+7. no stray empty headings or broken split paragraphs remain
+
+## Useful recipes
+
+### Import a markdown article
+
+1. parse the markdown locally
+2. map paragraphs to `unstyled`
+3. map `##` headings to `header-two`
+4. map numbered list items to `ordered-list-item`
+5. map fenced code blocks to `atomic` + `MARKDOWN` entities
+6. send `ArticleEntityUpdateContent`
+7. reload and validate
+
+The fastest implementation is usually:
+
+1. generate `./tmp/x-article-content-state.json`
+2. read it from a Playwriter command with `fs.readFileSync`
+3. push it with the direct content mutation
+
+### Bold one keyword per paragraph
+
+1. choose one keyword per paragraph
+2. compute exact `offset` and `length`
+3. add `inlineStyleRanges` with style `Bold`
+4. push the updated `content_state`
+5. reload and verify the HTML splits around the bold span
+
+### Fix code language labels
+
+Update the markdown entity fences. Example:
+
+- bad: ` ```ts `
+- good: ` ```typescript `
+
+Then resend the full `content_state` and reload the editor.
+
+## Minimal bulk update example
+
+Use this pattern when you already have the right `queryId` and payload shape:
+
+```bash
+playwriter -s 1 -e '
+const fs = require("node:fs")
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+const articleId = state.page.url().match(/edit\/(\d+)/)?.[1]
+const contentState = JSON.parse(
+  fs.readFileSync("./tmp/x-article-content-state.json", "utf8"),
+)
+const csrfToken = await state.page.evaluate(() => {
+  return document.cookie
+    .split("; ")
+    .find((x) => x.startsWith("ct0="))
+    ?.slice(4) || ""
+})
+const payload = {
+  variables: {
+    content_state: contentState,
+    article_entity: articleId,
+  },
+  features: {
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: false,
+    rweb_tipjar_consumption_enabled: false,
+    verified_phone_label_enabled: false,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+  },
+  queryId: "<capture-from-real-request>",
+}
+const response = await state.page.evaluate(async ({ payload, csrfToken }) => {
+  const res = await fetch(
+    `https://x.com/i/api/graphql/${payload.queryId}/ArticleEntityUpdateContent`,
+    {
+      method: "POST",
+      credentials: "include",
+      headers: {
+        authorization: "<capture-from-real-request>",
+        "content-type": "application/json",
+        "x-csrf-token": csrfToken,
+        "x-twitter-active-user": "yes",
+        "x-twitter-auth-type": "OAuth2Session",
+        "x-twitter-client-language": "it",
+      },
+      body: JSON.stringify(payload),
+    },
+  )
+  return { status: res.status, text: await res.text() }
+}, { payload, csrfToken })
+console.log(response.status)
+console.log(response.text.slice(0, 1000))
+'
+```
+
+Replace the bearer token and `queryId` with values captured from a successful
+browser request in the current session.
+
+## Default strategy
+
+Use this default unless the task is tiny:
+
+1. inspect the current draft in the browser
+2. capture one real content mutation from X
+3. generate the final `content_state` locally
+4. update the draft with the same mutation shape
+5. validate the result in the live editor HTML
+
+That is the fastest path and the most likely to work in one shot.

package/src/agent-model.e2e.test.ts

@@ -11,7 +11,7 @@
 // Poll timeouts: 4s max, 100ms interval.
 
 import fs from 'node:fs'
-import net from 'node:net'
+
 import path from 'node:path'
 import url from 'node:url'
 import {
@@ -44,6 +44,7 @@ import { getPrisma } from './db.js'
 import { startHranaServer, stopHranaServer } from './hrana-server.js'
 import { initializeOpencodeForDirectory, stopOpencodeServer } from './opencode.js'
 import {
+  chooseLockPort,
   cleanupTestSessions,
   waitForBotMessageContaining,
   waitForFooterMessage,
@@ -68,23 +69,7 @@ function createRunDirectories() {
   return { root, dataDir, projectDirectory }
 }
 
-function chooseLockPort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const server = net.createServer()
-    server.listen(0, () => {
-      const address = server.address()
-      if (!address || typeof address === 'string') {
-        server.close()
-        reject(new Error('Failed to resolve lock port'))
-        return
-      }
-      const port = address.port
-      server.close(() => {
-        resolve(port)
-      })
-    })
-  })
-}
+
 
 function createDiscordJsClient({ restUrl }: { restUrl: string }) {
   return new Client({
@@ -200,7 +185,7 @@ describe('agent model resolution', () => {
   beforeAll(async () => {
     testStartTime = Date.now()
     directories = createRunDirectories()
-    const lockPort = await chooseLockPort()
+    const lockPort = chooseLockPort({ key: TEXT_CHANNEL_ID })
 
     process.env['KIMAKI_LOCK_PORT'] = String(lockPort)
     setDataDir(directories.dataDir)