typeclaw 0.51.0 → 0.52.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.
- package/dist/types/agent/bash-sandbox-env.d.ts +2 -0
- package/dist/types/agent/bash-sandbox.d.ts +4 -0
- package/dist/types/agent/index.d.ts +5 -0
- package/dist/types/agent/multimodal/look-at.d.ts +1 -1
- package/dist/types/agent/plugin-tools.d.ts +4 -0
- package/dist/types/agent/prompt-cache-key.d.ts +1 -0
- package/dist/types/agent/session-tail.d.ts +12 -0
- package/dist/types/agent/subagents.d.ts +5 -0
- package/dist/types/agent/system-prompt-composition.d.ts +1 -0
- package/dist/types/agent/system-prompt.d.ts +2 -0
- package/dist/types/agent/tools/channel-disengage.d.ts +1 -1
- package/dist/types/agent/tools/channel-edit.d.ts +1 -1
- package/dist/types/agent/tools/channel-fetch-attachment.d.ts +1 -1
- package/dist/types/agent/tools/channel-handoff.d.ts +1 -1
- package/dist/types/agent/tools/channel-history.d.ts +1 -1
- package/dist/types/agent/tools/channel-react.d.ts +1 -1
- package/dist/types/agent/tools/channel-read.d.ts +10 -2
- package/dist/types/agent/tools/channel-reply.d.ts +1 -1
- package/dist/types/agent/tools/channel-send.d.ts +1 -1
- package/dist/types/agent/tools/channel-session-search.d.ts +1 -1
- package/dist/types/agent/tools/grant-role.d.ts +1 -1
- package/dist/types/agent/tools/post-github-review.d.ts +1 -1
- package/dist/types/agent/tools/restart.d.ts +1 -1
- package/dist/types/agent/tools/skip-response.d.ts +1 -1
- package/dist/types/agent/tools/spawn-subagent.d.ts +2 -1
- package/dist/types/agent/tools/stream-snapshot.d.ts +1 -1
- package/dist/types/agent/tools/subagent-cancel.d.ts +1 -1
- package/dist/types/agent/tools/subagent-output.d.ts +1 -1
- package/dist/types/agent/tools/todo/index.d.ts +1 -1
- package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +3 -3
- package/dist/types/agent/tools/webfetch/strategies/readability-process.d.ts +48 -0
- package/dist/types/agent/tools/webfetch/tool.d.ts +2 -2
- package/dist/types/agent/tools/websearch.d.ts +1 -1
- package/dist/types/channels/adapters/github/auth-app.d.ts +25 -0
- package/dist/types/channels/adapters/github/auth-pat.d.ts +17 -0
- package/dist/types/channels/adapters/github/auth.d.ts +24 -0
- package/dist/types/channels/github-token-bridge.d.ts +4 -0
- package/dist/types/channels/lost-background-context.d.ts +2 -0
- package/dist/types/channels/persistence.d.ts +1 -0
- package/dist/types/channels/router.d.ts +5 -1
- package/dist/types/channels/types.d.ts +1 -0
- package/dist/types/coding-agent/tool.d.ts +1 -1
- package/dist/types/config/config.d.ts +20 -11
- package/dist/types/config/providers.d.ts +47 -0
- package/dist/types/eval/sandbox.d.ts +2 -0
- package/dist/types/git/resolve-identity.d.ts +2 -0
- package/dist/types/init/dockerfile.d.ts +1 -0
- package/dist/types/init/gitignore.d.ts +1 -1
- package/dist/types/permissions/builtins.d.ts +1 -0
- package/dist/types/plugin/types.d.ts +3 -0
- package/dist/types/sandbox/canonical-secrets.d.ts +2 -2
- package/dist/types/sandbox/coding-agent.d.ts +1 -1
- package/dist/types/sandbox/dependency-bins.d.ts +1 -0
- package/dist/types/sandbox/dev-source.d.ts +2 -2
- package/dist/types/sandbox/hidden-paths.d.ts +1 -0
- package/dist/types/sandbox/index.d.ts +1 -1
- package/dist/types/sandbox/policy.d.ts +3 -0
- package/dist/types/typevault/cli-path.d.ts +2 -0
- package/dist/types/typevault/envelope-store.d.ts +11 -0
- package/dist/types/typevault/lifecycle.d.ts +13 -0
- package/dist/types/typevault/vault.d.ts +27 -0
- package/package.json +8 -7
- package/scripts/test.ts +252 -0
- package/src/agent/bash-sandbox-env.ts +33 -1
- package/src/agent/bash-sandbox.ts +20 -6
- package/src/agent/index.ts +120 -31
- package/src/agent/multimodal/look-at.ts +1 -1
- package/src/agent/plugin-tools.ts +35 -1
- package/src/agent/prompt-cache-key.ts +26 -3
- package/src/agent/session-origin.ts +39 -18
- package/src/agent/session-tail.ts +28 -0
- package/src/agent/subagents.ts +21 -2
- package/src/agent/system-prompt-composition.ts +18 -0
- package/src/agent/system-prompt.ts +39 -1
- package/src/agent/tool-error-remediation.ts +18 -3
- package/src/agent/tools/channel-disengage.ts +1 -1
- package/src/agent/tools/channel-edit.ts +1 -1
- package/src/agent/tools/channel-fetch-attachment.ts +1 -1
- package/src/agent/tools/channel-handoff.ts +3 -2
- package/src/agent/tools/channel-history.ts +2 -1
- package/src/agent/tools/channel-react.ts +1 -1
- package/src/agent/tools/channel-read.ts +36 -3
- package/src/agent/tools/channel-reply.ts +1 -1
- package/src/agent/tools/channel-send.ts +4 -3
- package/src/agent/tools/channel-session-search.ts +13 -4
- package/src/agent/tools/grant-role.ts +1 -1
- package/src/agent/tools/post-github-review.ts +1 -1
- package/src/agent/tools/restart.ts +1 -1
- package/src/agent/tools/skip-response.ts +1 -1
- package/src/agent/tools/spawn-subagent.ts +15 -1
- package/src/agent/tools/stream-snapshot.ts +1 -1
- package/src/agent/tools/subagent-cancel.ts +1 -1
- package/src/agent/tools/subagent-output.ts +1 -1
- package/src/agent/tools/todo/index.ts +1 -1
- package/src/agent/tools/webfetch/adaptive-html.ts +6 -4
- package/src/agent/tools/webfetch/strategies/readability-child.ts +25 -0
- package/src/agent/tools/webfetch/strategies/readability-process.ts +185 -0
- package/src/agent/tools/webfetch/tool.ts +6 -5
- package/src/agent/tools/websearch.ts +1 -1
- package/src/browser/dockerfile.ts +1 -1
- package/src/browser/fill-secret.ts +92 -35
- package/src/browser/registry.ts +6 -6
- package/src/bundled-plugins/agent-messenger-cli-auth/command.ts +211 -0
- package/src/bundled-plugins/agent-messenger-cli-auth/index.ts +186 -0
- package/src/bundled-plugins/backup/index.ts +17 -2
- package/src/bundled-plugins/backup/runner.ts +37 -2
- package/src/bundled-plugins/browser-agent/browser-agent.ts +51 -14
- package/src/bundled-plugins/browser-agent/index.ts +12 -5
- package/src/bundled-plugins/managed-browser/index.ts +25 -2
- package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +13 -5
- package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +56 -5
- package/src/bundled-plugins/memory/README.md +23 -2
- package/src/bundled-plugins/memory/append-fragment.ts +133 -0
- package/src/bundled-plugins/memory/append-tool.ts +80 -149
- package/src/bundled-plugins/memory/dreaming.ts +2 -0
- package/src/bundled-plugins/memory/index.ts +33 -6
- package/src/bundled-plugins/memory/memory-logger.ts +133 -11
- package/src/bundled-plugins/memory/references/store-reference-tool.ts +56 -32
- package/src/bundled-plugins/memory/remember-tool.ts +81 -0
- package/src/bundled-plugins/memory/search-tool-hybrid.ts +91 -0
- package/src/bundled-plugins/memory/search-tool.ts +58 -12
- package/src/bundled-plugins/memory/stream-events.ts +2 -0
- package/src/bundled-plugins/memory/transcript-cursor.ts +30 -0
- package/src/bundled-plugins/memory/transcript-preload.ts +131 -26
- package/src/bundled-plugins/memory/transcript-view.ts +36 -0
- package/src/bundled-plugins/memory/watermark.ts +19 -10
- package/src/bundled-plugins/reviewer/reviewer.ts +20 -0
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +3 -6
- package/src/bundled-plugins/security/policies/outbound-text.ts +20 -0
- package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -7
- package/src/bundled-plugins/typevault/grants.ts +119 -0
- package/src/bundled-plugins/typevault/index.ts +152 -0
- package/src/bundled-plugins/typevault/request.ts +87 -0
- package/src/bundled-plugins/typevault/runtime.ts +45 -0
- package/src/bundled-plugins/typevault/skills/typevault/SKILL.md +65 -0
- package/src/channels/adapter-halt.ts +17 -0
- package/src/channels/adapters/github/history.ts +23 -2
- package/src/channels/adapters/github/inbound.ts +60 -1
- package/src/channels/adapters/github/index.ts +27 -5
- package/src/channels/adapters/github/reconcile-open-prs.ts +7 -1
- package/src/channels/adapters/kakaotalk-author-resolver.ts +7 -5
- package/src/channels/adapters/kakaotalk-channel-resolver.ts +45 -15
- package/src/channels/adapters/kakaotalk-classify.ts +7 -9
- package/src/channels/adapters/kakaotalk-list.ts +62 -0
- package/src/channels/adapters/kakaotalk-member-cache.ts +67 -0
- package/src/channels/adapters/kakaotalk-membership.ts +27 -10
- package/src/channels/adapters/kakaotalk-mention.ts +61 -0
- package/src/channels/adapters/kakaotalk.ts +159 -125
- package/src/channels/adapters/teams-classify.ts +18 -8
- package/src/channels/github-token-bridge.ts +13 -0
- package/src/channels/lost-background-context.ts +46 -0
- package/src/channels/manager.ts +52 -3
- package/src/channels/persistence.ts +5 -0
- package/src/channels/router.ts +120 -21
- package/src/channels/schema.ts +1 -1
- package/src/channels/types.ts +3 -0
- package/src/coding-agent/tool.ts +1 -1
- package/src/config/config.ts +20 -1
- package/src/config/providers.ts +65 -0
- package/src/container/start.ts +15 -2
- package/src/doctor/channel-checks.ts +33 -0
- package/src/doctor/checks.ts +12 -2
- package/src/eval/sandbox.ts +3 -0
- package/src/eval/tool.ts +1 -0
- package/src/git/resolve-identity.ts +67 -2
- package/src/git/system-commit.ts +7 -0
- package/src/init/dockerfile.ts +5 -1
- package/src/init/gitignore.ts +3 -3
- package/src/init/index.ts +1 -0
- package/src/init/models-dev.ts +2 -0
- package/src/init/validate-api-key.ts +5 -0
- package/src/migrations/secrets-v1-to-v2.ts +2 -0
- package/src/permissions/builtins.ts +8 -0
- package/src/plugin/types.ts +6 -0
- package/src/run/bundled-plugins.ts +12 -0
- package/src/run/channel-session-factory.ts +3 -0
- package/src/run/index.ts +13 -2
- package/src/sandbox/build.ts +1 -0
- package/src/sandbox/canonical-secrets.ts +6 -0
- package/src/sandbox/dependency-bins.ts +13 -1
- package/src/sandbox/dev-source.ts +21 -12
- package/src/sandbox/hidden-paths.ts +1 -1
- package/src/sandbox/index.ts +1 -0
- package/src/sandbox/policy.ts +5 -0
- package/src/secrets/hydrate.ts +4 -1
- package/src/secrets/storage.ts +10 -1
- package/src/server/command-runner.ts +4 -0
- package/src/server/index.ts +8 -1
- package/src/skills/typeclaw-config/SKILL.md +16 -0
- package/src/skills/typeclaw-memory/SKILL.md +3 -1
- package/src/skills/typeclaw-permissions/SKILL.md +8 -8
- package/src/skills/typeclaw-troubleshooting/SKILL.md +18 -1
- package/src/tunnels/active.ts +14 -0
- package/src/typevault/bash-cli.ts +18 -0
- package/src/typevault/cli-path.ts +11 -0
- package/src/typevault/envelope-helper.ts +17 -0
- package/src/typevault/envelope-store.ts +98 -0
- package/src/typevault/lifecycle.ts +132 -0
- package/src/typevault/prompt-tunnel.ts +33 -0
- package/src/typevault/redaction.ts +37 -0
- package/src/typevault/vault.ts +283 -0
- package/typeclaw.schema.json +40 -10
|
@@ -1,12 +1,19 @@
|
|
|
1
|
+
import { join } from 'node:path'
|
|
2
|
+
|
|
1
3
|
import { getConfig } from '@/config'
|
|
2
4
|
import { definePlugin } from '@/plugin'
|
|
5
|
+
import { isTypevaultMarkerFile } from '@/typevault/envelope-store'
|
|
3
6
|
|
|
4
7
|
import { createBrowserSubagent } from './browser-agent'
|
|
5
8
|
|
|
6
9
|
export default definePlugin({
|
|
7
|
-
plugin: async () =>
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
10
|
+
plugin: async (ctx) => {
|
|
11
|
+
const config = getConfig()
|
|
12
|
+
const typevault = config.typevault.enabled && isTypevaultMarkerFile(join(ctx.agentDir, 'secrets.json'))
|
|
13
|
+
return {
|
|
14
|
+
subagents: {
|
|
15
|
+
browser: createBrowserSubagent(config.browser, { typevault }),
|
|
16
|
+
},
|
|
17
|
+
}
|
|
18
|
+
},
|
|
12
19
|
})
|
|
@@ -6,6 +6,7 @@ import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
|
|
|
6
6
|
import { fillSecretIntoFocusedField, type FillSecretOutcome } from '@/browser/fill-secret'
|
|
7
7
|
import { type ManagedBrowser, startManagedBrowser } from '@/browser/managed-browser'
|
|
8
8
|
import { BROWSER_ENGINES, type BrowserConfig, needsManagedBrowser } from '@/browser/registry'
|
|
9
|
+
import { readVaultValue } from '@/bundled-plugins/typevault/runtime'
|
|
9
10
|
import { getConfig } from '@/config'
|
|
10
11
|
import { readEnvFile } from '@/init/env-file'
|
|
11
12
|
import type { PermissionService } from '@/permissions'
|
|
@@ -62,6 +63,7 @@ export function sharedBrowserBashHook(
|
|
|
62
63
|
}
|
|
63
64
|
|
|
64
65
|
export const FILL_SECRET_TOOL = 'browser_fill_secret'
|
|
66
|
+
const VAULT_REF_PREFIX = 'typevault://'
|
|
65
67
|
|
|
66
68
|
// The tool drives the shared browser, so it needs `browser.shared` like bash's
|
|
67
69
|
// CDP URL does. Typing the withheld TYPECLAW_SECRET_* tier is runtime-owned
|
|
@@ -76,6 +78,11 @@ export function fillSecretGuardHook(permissions: PermissionService): NonNullable
|
|
|
76
78
|
return { block: true, reason: `${FILL_SECRET_TOOL} needs the ${CORE_PERMISSIONS.browserShared} permission` }
|
|
77
79
|
}
|
|
78
80
|
const name = event.args['name']
|
|
81
|
+
if (typeof name === 'string' && name.startsWith(VAULT_REF_PREFIX)) {
|
|
82
|
+
return permissions.has(event.origin, CORE_PERMISSIONS.vaultUse)
|
|
83
|
+
? undefined
|
|
84
|
+
: { block: true, reason: `${VAULT_REF_PREFIX} values need the ${CORE_PERMISSIONS.vaultUse} permission` }
|
|
85
|
+
}
|
|
79
86
|
if (
|
|
80
87
|
typeof name === 'string' &&
|
|
81
88
|
name.startsWith(SECRET_ENV_PREFIX) &&
|
|
@@ -98,16 +105,32 @@ export function createFillSecretTool(
|
|
|
98
105
|
'Type the value of a .env variable into the focused field of a shared-browser tab without the value ever entering your context.',
|
|
99
106
|
'Focus the field first with your browser engine (click it), then call this. Pass `url` (exact or prefix) when several tabs are open.',
|
|
100
107
|
`Accepts any ordinary .env variable and the ${SECRET_ENV_PREFIX}* tier, which is hidden from bash and reachable only through this tool.`,
|
|
101
|
-
|
|
108
|
+
`With TypeVault enabled, \`name\` can also be a vault reference such as ${VAULT_REF_PREFIX}github/bot#password, read through this session's grant.`,
|
|
109
|
+
'With `submit: true` it presses Enter (submitting the form directly only if Enter did nothing) and waits for the page to navigate; if it does not, the field is cleared so the value is not left on the page.',
|
|
102
110
|
'The result names the tab and field, never the value. Never read the field back, screenshot a non-password field after filling, or echo the variable.',
|
|
103
111
|
].join(' '),
|
|
104
112
|
parameters: z.object({
|
|
105
|
-
name: z
|
|
113
|
+
name: z
|
|
114
|
+
.string()
|
|
115
|
+
.describe(
|
|
116
|
+
'The .env variable name, e.g. TYPECLAW_SECRET_GITHUB_PASSWORD, or a vault reference like typevault://github/bot#password',
|
|
117
|
+
),
|
|
106
118
|
url: z.string().optional().describe('Exact URL or prefix of the target tab'),
|
|
107
119
|
submit: z.boolean().default(false),
|
|
108
120
|
}),
|
|
109
121
|
fileOperands: { nonFile: ['name', 'url'] },
|
|
110
122
|
execute: async (args, ctx) => {
|
|
123
|
+
if (args.name.startsWith(VAULT_REF_PREFIX)) {
|
|
124
|
+
const read = await readVaultValue(ctx.sessionId, args.name, 'fill a browser field')
|
|
125
|
+
if (!read.ok) return text(`Not filled: ${read.reason}.`)
|
|
126
|
+
const outcome = await fill({
|
|
127
|
+
cdpUrl,
|
|
128
|
+
value: read.value,
|
|
129
|
+
submit: args.submit,
|
|
130
|
+
...(args.url === undefined ? {} : { url: args.url }),
|
|
131
|
+
})
|
|
132
|
+
return text(describeOutcome(args.name, outcome))
|
|
133
|
+
}
|
|
111
134
|
const fillable = new Set(resolveFillableEnvNames(readEnvFile(ctx.agentDir), process.env))
|
|
112
135
|
if (!fillable.has(args.name)) {
|
|
113
136
|
return text(
|
|
@@ -9,13 +9,21 @@ The `bsk` CLI talks to a daemon TypeClaw runs next to the shared browser; the Br
|
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
11
|
bsk status --json # a connected browser must be listed
|
|
12
|
-
SID=$(bsk session start --json | jq -r .session_id)
|
|
13
|
-
bsk navigate https://example.com --session "$SID"
|
|
14
|
-
bsk
|
|
15
|
-
|
|
12
|
+
SID=$(bsk session start --agent-name TypeClaw --json | jq -r .session_id)
|
|
13
|
+
bsk navigate https://example.com/signup --session "$SID" # the first navigation of the blank tab needs no context
|
|
14
|
+
SYNC=$(bsk cooperate sync --session "$SID" --json)
|
|
15
|
+
CTX=$(jq -r .context_id <<<"$SYNC"); OBS=$(jq -r .observation_id <<<"$SYNC")
|
|
16
|
+
bsk snapshot --session "$SID" # @eN refs; use the ones your snapshot shows
|
|
17
|
+
bsk fill @e2 --value Alice --session "$SID" --context "$CTX"
|
|
18
|
+
bsk press Enter --ref @e2 --session "$SID" --context "$CTX"
|
|
16
19
|
bsk session stop "$SID" # always stop, success or failure
|
|
17
20
|
```
|
|
18
21
|
|
|
22
|
+
- Targeted page actions (`click`, `fill`, `select`, `press --ref`, `hover`, `scroll-to`, ...) need `--context` from `bsk cooperate sync`. One context covers reads and completed DOM actions until the document changes (a navigation, a form submit); then sync again and take fresh refs. Reads (`snapshot`, `get-html`, `screenshot`) need none.
|
|
23
|
+
- `navigate` (after the first one), `evaluate`, `wheel`, a `press` without `--ref`, and screenshot-coordinate clicks also need `--observation` with the top-level `observation_id` from a sync (not the nested `observation.observation_id`). Each observation is single-use: sync again before the next such action.
|
|
24
|
+
- `--expect '[{"target":"@e4","field":"text","equals":"Save"}]'` makes an action fail with `precondition_failed` instead of acting when the fact you decided on changed.
|
|
25
|
+
- A `permission_denied` refusal names why in `data.reason`: `control_context_invalid` (missing or stale `--context`), `observation_required` (add a fresh `--observation`), `cooperation_sync_required`. Each means sync, read the page again, and decide afresh; never replay the refused action blindly. If `effect_state` is `unknown`, check the page for the result before retrying.
|
|
26
|
+
- Redirect large output to a file (`bsk get-html --session "$SID" --json > /tmp/page.json`); piping it straight into another command can crash `bsk` with `failed printing to stdout`.
|
|
19
27
|
- Sessions open their own Agent Window. Never borrow an existing tab: borrowing asks a human to confirm, and nobody can click it here.
|
|
20
28
|
- `bsk --help` and `bsk <command> --help` list everything (`extract`, `observe`, `record`, `debug`).
|
|
21
29
|
- Never run `bsk update`, `bsk daemon stop`, or `bsk daemon restart`; TypeClaw owns the daemon and its version.
|
|
@@ -24,5 +32,5 @@ bsk session stop "$SID" # always stop, success or failure
|
|
|
24
32
|
|
|
25
33
|
- One TypeClaw-managed Chrome serves every engine and every session that has `browser.shared`. Logins and tabs persist across bash calls and sessions.
|
|
26
34
|
- Work only in tabs you opened. Never navigate or close a tab another engine or session is using.
|
|
27
|
-
- Files: downloads land in `$TYPECLAW_BROWSER_FILES
|
|
35
|
+
- Files: Chrome's own downloads land in `$TYPECLAW_BROWSER_FILES`, and Chrome cannot see other paths. `bsk upload --file <path>` and `bsk download --out <path>` move files through the CLI, so they accept any path your bash can read or write.
|
|
28
36
|
- The browser runs in its own sandbox with no view of the agent folder, so `file://` URLs outside `$TYPECLAW_BROWSER_FILES` fail by design.
|
|
@@ -5,7 +5,7 @@ description: Playwright-shaped browser automation library (OmOWright) for the sh
|
|
|
5
5
|
|
|
6
6
|
# omowright
|
|
7
7
|
|
|
8
|
-
OmOWright is a JavaScript library with the Playwright API shape (`page.goto`, `page.locator(ref).click()`, `page.mouse.wheel`, `page.keyboard.type`, `page.screenshot`). Write a short Bun script and run it with `bun`. Each script connects to the shared browser, so
|
|
8
|
+
OmOWright is a JavaScript library with the Playwright API shape (`page.goto`, `page.locator(ref).click()`, `page.mouse.wheel`, `page.keyboard.type`, `page.screenshot`). Write a short Bun script and run it with `bun`. Each script connects to the shared browser, so tabs, logins, and cookies survive between scripts. Snapshot refs do not.
|
|
9
9
|
|
|
10
10
|
`$OMOWRIGHT_CDP_URL` holds the connection URL. If the variable is unset, this session's role cannot use the shared browser (it needs the `browser.shared` permission) or the browser failed to start; the operator log (`typeclaw logs`) names which. Do not try to start Chrome yourself.
|
|
11
11
|
|
|
@@ -17,20 +17,71 @@ const url = process.env.OMOWRIGHT_CDP_URL
|
|
|
17
17
|
// The relay requires the token on every request; omowright drops the URL query
|
|
18
18
|
// for HTTP discovery (listTargets), so pass it as an Authorization header too.
|
|
19
19
|
const token = new URL(url).searchParams.get('token')
|
|
20
|
-
|
|
20
|
+
// `await using` closes this script's connection when the script ends, so the
|
|
21
|
+
// script exits on its own; the tab and the browser keep running.
|
|
22
|
+
await using browser = await connect(url, {
|
|
21
23
|
client: { authorizer: { resolveAuthorization: async () => `Bearer ${token}` } },
|
|
22
24
|
})
|
|
23
25
|
const tabs = createAgentTabs(browser) // background tabs that never steal focus
|
|
24
|
-
const page = await tabs.
|
|
26
|
+
const { targetId, page } = await tabs.create('https://example.com')
|
|
27
|
+
console.log(targetId) // keep it: later scripts reattach with browser.attachPage(targetId)
|
|
25
28
|
console.log(compactSnapshot(await page.snapshot())) // refs like [ref=e1]
|
|
26
29
|
await page.locator('e1').click()
|
|
27
|
-
process.exit(0) // leaves the tab and browser running
|
|
28
30
|
```
|
|
29
31
|
|
|
32
|
+
Always connect with `await using browser = await connect(...)`, as above. With a plain `const`, the open connection keeps Bun running, so the script prints its output and then hangs until the bash timeout kills it. `await using` also closes the connection when the script throws. Tabs made with `createAgentTabs` stay open for the next script; a popup tab the script attached (from `window.open`) closes with the connection, so do work that must continue later in an agent tab.
|
|
33
|
+
|
|
34
|
+
A "Command timed out" result after the script printed output means the script did not exit, not that the browser or the site failed. Do not report a browser timeout and do not blindly rerun it: its actions (a click, a submit) may already have gone through. Reattach to the tab with `attachPage`, snapshot it, and continue from what the page shows; repeat a step only if the page shows it did not happen.
|
|
35
|
+
|
|
36
|
+
A later script continues in the same tab with `const page = await browser.attachPage(targetId)`. `browser.listTargets()` lists open tabs when the id is lost.
|
|
37
|
+
|
|
38
|
+
Refs like `e14` belong to the script that took the snapshot. A new script has none, so `page.locator('e14')` from an earlier run always throws `RefStaleError`. In every script that acts on refs, call `page.snapshot()` first and use the refs from that snapshot in the same script. A page change (a click that navigates, a modal opening) also invalidates refs: snapshot again in the same script before the next ref action. When a ref stays stale, use a semantic locator instead, such as `page.getByRole('link', { name: '로그인' })` or `page.locator('#userId')`.
|
|
39
|
+
|
|
40
|
+
Reuse your tab across retries with `attachPage` instead of opening another `tabs.create` for the same site, and close tabs you no longer need (`await page.close()`). Duplicate tabs of one site make it unclear which tab later steps (and `browser_fill_secret`) act on.
|
|
41
|
+
|
|
30
42
|
- Prefer `compactSnapshot(await page.snapshot())` over screenshots; re-snapshots come back as a diff.
|
|
31
43
|
- Long lists: `createNetworkSnoop` + `collectWhileScrolling` read the page's JSON instead of scraping rows.
|
|
32
44
|
- Canvas or custom widgets: `createCua(page)` gives coordinate-level clicks and scrolls.
|
|
33
|
-
- `connectPipe()
|
|
45
|
+
- `connectBrowser()`, `connectPipe()`, and `connectBrowserSkill()` launch or find other browsers; do not use them here.
|
|
46
|
+
|
|
47
|
+
## Sites with anti-macro checks
|
|
48
|
+
|
|
49
|
+
Some sites (ticketing and banking sites such as Korail, often behind DynaPath) score how input arrives and reject requests that look scripted. On Korail the rejection is a dialog like "매크로, 개발자도구 등 미허가 도구 사용 시 이용이 제한될 수 있습니다" or a `CODE : -8002`. That dialog is a block of the request, not a notice to click away; the login or search did not go through.
|
|
50
|
+
|
|
51
|
+
`locator(ref).click()` jumps the pointer straight to the element and `keyboard.type(text)` types with no delay between keys, which these checks reject. Both a moving pointer and a typing delay are needed; either alone is still rejected. On such sites, click and type like this instead:
|
|
52
|
+
|
|
53
|
+
```js
|
|
54
|
+
const rand = (min, max) => min + Math.random() * (max - min)
|
|
55
|
+
const pause = (min, max) => new Promise((resolve) => setTimeout(resolve, rand(min, max)))
|
|
56
|
+
|
|
57
|
+
async function humanClick(page, ref, [fromX, toX] = [0.3, 0.7]) {
|
|
58
|
+
await page.locator(ref).scrollIntoViewIfNeeded()
|
|
59
|
+
const box = await page.locator(ref).boundingBox()
|
|
60
|
+
const x = box.x + box.width * rand(fromX, toX)
|
|
61
|
+
const y = box.y + box.height * rand(0.3, 0.7)
|
|
62
|
+
await page.mouse.move(x, y, { steps: Math.round(rand(12, 25)) })
|
|
63
|
+
await pause(80, 250)
|
|
64
|
+
await page.mouse.down()
|
|
65
|
+
await pause(40, 110)
|
|
66
|
+
await page.mouse.up()
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
async function humanType(page, ref, text) {
|
|
70
|
+
// Aim at the left of the field: the right edge often holds an overlay
|
|
71
|
+
// (password reveal, virtual-keypad toggle) that swallows the keystrokes.
|
|
72
|
+
await humanClick(page, ref, [0.1, 0.35])
|
|
73
|
+
await pause(300, 700)
|
|
74
|
+
// Clear what a previous attempt left in the field so a retry does not append.
|
|
75
|
+
await page.keyboard.press('Control+A')
|
|
76
|
+
await page.keyboard.press('Backspace')
|
|
77
|
+
await pause(150, 400)
|
|
78
|
+
await page.keyboard.type(text, { delay: 120 })
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
- Before submitting, take a fresh snapshot and check every field holds what you typed; if one is empty, a click hit an overlay instead of the field.
|
|
83
|
+
- After a block, dismiss the dialog and redo the same step with `humanClick`/`humanType`. Do not report the site as unusable until that retry also fails.
|
|
84
|
+
- Do not call the site's endpoints yourself with `page.evaluate(() => fetch(...))`. The check signs the page's own requests, so a hand-made request is rejected even when the UI flow would pass. Drive the UI.
|
|
34
85
|
|
|
35
86
|
## Shared browser rules
|
|
36
87
|
|
|
@@ -4,6 +4,16 @@ The bundled memory plugin. Owns `memory/topics/` (sharded long-term memory) and
|
|
|
4
4
|
|
|
5
5
|
Auto-loaded by every TypeClaw agent. No `plugins[]` entry to add and no opt-out. Configure via the `memory` block in `typeclaw.json`.
|
|
6
6
|
|
|
7
|
+
## Extractor pages
|
|
8
|
+
|
|
9
|
+
`memory-logger` receives a projected, bounded transcript view rather than provider bookkeeping and opaque replay signatures. Message content, timestamps, attribution, source IDs, parent/tool-call links, errors, and unknown evidence fields remain available; canonical transcripts stay unchanged.
|
|
10
|
+
|
|
11
|
+
Large projected records are supplied as lossless `entry-part` segments. The runtime persists a starting checkpoint before each page, defers progress while fragments are being written, and accepts page completion only for the issued checkpoint and source. An interruption replays the unfinished page. Explicit checkpoints remain authoritative across daily streams; fragments alone cannot advance an unfinished page.
|
|
12
|
+
|
|
13
|
+
Each continuation includes bounded read-only `precedingText` from the same record, charged to the page budget, so split instructions can be interpreted with their preceding context. Only new `text` contributes to checkpoint progress. If a partial cursor cannot be preloaded because limits are unavailable or insufficient, it remains pending with an operator warning; the legacy reader never receives it.
|
|
14
|
+
|
|
15
|
+
Partial-entry checkpoints use versioned `memory-page:` cursors. Changed source records restart at their beginning, and legacy complete-entry watermarks remain supported. Drain pending pages before downgrading to a version without cursor support. No scheduling, idle-delta, or buffer-ceiling settings change.
|
|
16
|
+
|
|
7
17
|
## Config
|
|
8
18
|
|
|
9
19
|
```json
|
|
@@ -34,13 +44,20 @@ All fields are **restart-required** — the plugin reads them once at boot. The
|
|
|
34
44
|
| -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
35
45
|
| Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`. |
|
|
36
46
|
| Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run. |
|
|
37
|
-
| Tool | `memory_search` | Main-agent tool. Pass `query` for
|
|
47
|
+
| Tool | `memory_search` | Main-agent tool. Pass `query` for semantic+keyword hybrid search (default `mode: "hybrid"`), or `topic` for exact topic/reference slug lookup (not both). Use `mode: "lexical"` for the existing phrase-first/token-fallback behavior; `asRegex: true` and `topic` always stay lexical. Searches topics, active cited-child provenance, undreamed streams, and references. `maxResults` caps hybrid top-K; `full: true` loads complete bodies. Missing indexes or semantic errors produce a reported lexical fallback and an operator log. Optional `workspace`, `chat`, and `thread` scopes apply to both modes; legacy `where` aliases `chat`. See [Provenance-aware recall](#provenance-aware-recall). |
|
|
48
|
+
| Tool | `memory_remember` | Main-agent tool for immediate deliberate capture: `topic`, `body`, optional `who` and `verbatim`. Writes one explicit fragment with runtime provenance; optional exact reference; shared vector hooks; no logger progress or topic-shard writes. |
|
|
38
49
|
| Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded. |
|
|
39
50
|
| Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`. |
|
|
40
51
|
| Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip. |
|
|
41
52
|
| Hook | `session.end` | Spawns `memory-logger` immediately and clears per-session retrieval de-dup state. |
|
|
42
53
|
| Hook | `session.turn.start` | Renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). |
|
|
43
54
|
|
|
55
|
+
## Deliberate capture
|
|
56
|
+
|
|
57
|
+
`memory_remember({ topic, body, who?, verbatim? })` lets the agent immediately save a durable fact, decision, preference, or correction in every role and standard origin. It appends one `kind: "explicit"` fragment to today's stream. The runtime stamps the session id as `source`, the transcript leaf at invocation as `entry`, and channel coordinates from the live origin. Direct calls without a transcript use an empty `entry`. It never writes topic shards or advances the memory-logger watermark, including the legacy fragment-derived fallback.
|
|
58
|
+
|
|
59
|
+
With `verbatim: true`, the existing reference writer also stores the exact body and links its returned slug from `references`. Credential checks run before either write. Fragment and reference writes use memory-logger's vector hooks for immediate retrieval. Dreaming gives deliberate capture weight while retaining its normal consolidation, deduplication, citation-superset, and runtime-owned frontmatter rules. Memory-logger skips facts already saved by successful `memory_remember` calls in the transcript.
|
|
60
|
+
|
|
44
61
|
## Provenance-aware recall
|
|
45
62
|
|
|
46
63
|
Fragments can carry runtime-stamped `where` coordinates (`adapter`, workspace/chat/thread IDs, captured names, and Discord parent-room metadata) plus an attributed `who`. A topic derives searchable provenance only from its **active** `fragments:` children. `superseded:` evidence is excluded, and unresolved citations remain explicit rather than receiving invented metadata. The same eligible children determine scope eligibility, lexical matching, and returned `provenance`, so a multi-workspace topic cannot return another workspace's child details through a scoped result.
|
|
@@ -67,6 +84,10 @@ Each stripped topic is injected with its `slug:` line so the agent can re-fetch
|
|
|
67
84
|
|
|
68
85
|
The system prompt never contains long-term memory, so a session cannot double-carry memory in both the system prompt and the user turn.
|
|
69
86
|
|
|
87
|
+
### Blank-prompt turns skip retrieval
|
|
88
|
+
|
|
89
|
+
A runtime wakeup (a subagent completion or review-state reminder in a channel) has no inbound text, so its `userPrompt` is blank. An empty query embeds to a vector that scores every topic alike, and the slug tie-break used to inject the same first ten headings on every such turn. A blank prompt now injects nothing; the human turn that started the work already carried its own memory, and `memory_search` stays available.
|
|
90
|
+
|
|
70
91
|
### Internal-infrastructure turns skip retrieval
|
|
71
92
|
|
|
72
93
|
The `session.turn.start` per-turn injection runs for user-delegated subagents (researcher, reviewer) but is skipped entirely for **TypeClaw-owned infrastructure turns**. Their `userPrompt` is a fixed instruction block (`buildInitialPrompt`), not a user message — feeding it into `hybridSearch` keyword-mines the subagent's own framing prose ("Read the transcript past the watermark…"), retrieves nothing useful, and embeds a ~560-token query that trips the 512-token bound warning on every spawn. None of these subagents consume injected long-term memory the way a conversational turn does, so retrieval there is pure waste.
|
|
@@ -187,7 +208,7 @@ The `session.idle` hook fires after every prompt completion. A chatty channel se
|
|
|
187
208
|
|
|
188
209
|
### Byte-equality skip (session.end)
|
|
189
210
|
|
|
190
|
-
When `session.end` arrives
|
|
211
|
+
When `session.end` arrives, the final sweep is skipped only when an earlier spawn recorded the same byte size **and** its durable watermark matches the transcript's complete final entry. Returning from a logger spawn does not itself prove the evidence was drained. Missing checkpoints, partial-entry cursors, malformed tails, and failed coverage checks retain the final sweep. The skip is logged as `memory-logger session-end skip ses_X (no new bytes since last spawn at N)`. Sessions that ended before any spawn ran still fire on close.
|
|
191
212
|
|
|
192
213
|
### Daily-stream cursor (memory-logger payload)
|
|
193
214
|
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { mkdir } from 'node:fs/promises'
|
|
2
|
+
import { dirname } from 'node:path'
|
|
3
|
+
|
|
4
|
+
import type { ToolContext } from '@/plugin'
|
|
5
|
+
|
|
6
|
+
import { fragmentContentHash } from './fragment-parser'
|
|
7
|
+
import { sanitizeProvenanceName } from './provenance-sanitize'
|
|
8
|
+
import { detectSecrets } from './secret-detector'
|
|
9
|
+
import { newEventId, timestampFromId, type FragmentEvent, type FragmentProvenance } from './stream-events'
|
|
10
|
+
import { appendEvents, readEvents, type FragmentsAppendedContext } from './stream-io'
|
|
11
|
+
|
|
12
|
+
export type FragmentsAppendedHook = (fragments: FragmentEvent[], context: FragmentsAppendedContext) => Promise<void>
|
|
13
|
+
export type ReferenceSlugResolver = (agentDir: string) => Promise<Iterable<string>>
|
|
14
|
+
|
|
15
|
+
type FragmentInput = {
|
|
16
|
+
readonly topic: string
|
|
17
|
+
readonly body: string
|
|
18
|
+
readonly source: string
|
|
19
|
+
readonly entry: string
|
|
20
|
+
readonly references?: string[] | undefined
|
|
21
|
+
readonly who?: string | undefined
|
|
22
|
+
readonly kind?: 'explicit'
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
type AppendFragmentOptions = {
|
|
26
|
+
readonly path: string
|
|
27
|
+
readonly where?: FragmentProvenance | undefined
|
|
28
|
+
readonly watermarkEntry?: string | undefined
|
|
29
|
+
readonly onFragmentsAppended?: FragmentsAppendedHook | undefined
|
|
30
|
+
readonly referenceSlugResolver?: ReferenceSlugResolver | undefined
|
|
31
|
+
// Runs only after credential and duplicate checks, before the fragment write.
|
|
32
|
+
readonly storeReference?: () => Promise<string>
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export async function appendFragment(input: FragmentInput, ctx: ToolContext, options: AppendFragmentOptions) {
|
|
36
|
+
const { topic, body, source, entry, references, who } = input
|
|
37
|
+
const { path, where, onFragmentsAppended, referenceSlugResolver } = options
|
|
38
|
+
assertNoSecrets([topic, body, who])
|
|
39
|
+
|
|
40
|
+
const hash = fragmentContentHash({ topic, body })
|
|
41
|
+
const events = await readEvents(path)
|
|
42
|
+
const duplicate = events
|
|
43
|
+
.filter((event) => event.type === 'fragment')
|
|
44
|
+
.find((event) => fragmentContentHash(event) === hash)
|
|
45
|
+
if (duplicate !== undefined) {
|
|
46
|
+
throw new Error(
|
|
47
|
+
`Refusing to append: fragment "${duplicate.topic}" already exists in ${path} with byte-equivalent content. ` +
|
|
48
|
+
`The dreaming subagent will see the existing fragment; do not write it again. If the new occurrence ` +
|
|
49
|
+
`is genuinely informative, write a fragment that says so explicitly rather than restating the original.`,
|
|
50
|
+
)
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const fragmentId = newEventId()
|
|
54
|
+
const watermarkId = newEventId()
|
|
55
|
+
const fragment: FragmentEvent = {
|
|
56
|
+
type: 'fragment',
|
|
57
|
+
id: fragmentId,
|
|
58
|
+
ts: timestampFromId(fragmentId),
|
|
59
|
+
source,
|
|
60
|
+
entry,
|
|
61
|
+
topic,
|
|
62
|
+
body,
|
|
63
|
+
}
|
|
64
|
+
const storedReference = await options.storeReference?.()
|
|
65
|
+
const validReferences = await resolveValidReferences(
|
|
66
|
+
storedReference === undefined ? references : [...(references ?? []), storedReference],
|
|
67
|
+
referenceSlugResolver,
|
|
68
|
+
ctx,
|
|
69
|
+
)
|
|
70
|
+
if (validReferences.length > 0) fragment.references = validReferences
|
|
71
|
+
const safeWho = sanitizeProvenanceName(who)
|
|
72
|
+
if (safeWho !== undefined) fragment.who = safeWho
|
|
73
|
+
if (where !== undefined) fragment.where = where
|
|
74
|
+
if (input.kind !== undefined) fragment.kind = input.kind
|
|
75
|
+
const watermark = {
|
|
76
|
+
type: 'watermark' as const,
|
|
77
|
+
id: watermarkId,
|
|
78
|
+
ts: timestampFromId(watermarkId),
|
|
79
|
+
source,
|
|
80
|
+
entry: options.watermarkEntry ?? entry,
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
await mkdir(dirname(path), { recursive: true })
|
|
84
|
+
await appendEvents(
|
|
85
|
+
path,
|
|
86
|
+
options.watermarkEntry === undefined ? [fragment] : [fragment, watermark],
|
|
87
|
+
onFragmentsAppended,
|
|
88
|
+
onFragmentsAppended
|
|
89
|
+
? (err) => {
|
|
90
|
+
ctx.logger?.warn(
|
|
91
|
+
`[memory] post-append vector hook failed: ${err instanceof Error ? err.message : String(err)}`,
|
|
92
|
+
)
|
|
93
|
+
}
|
|
94
|
+
: undefined,
|
|
95
|
+
)
|
|
96
|
+
return { fragment, watermark }
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// Normalize every citation; when wired to the reference subsystem, retain only
|
|
100
|
+
// slugs backed by a stored artifact, never a label invented by the model.
|
|
101
|
+
async function resolveValidReferences(
|
|
102
|
+
references: string[] | undefined,
|
|
103
|
+
resolver: ReferenceSlugResolver | undefined,
|
|
104
|
+
ctx: { agentDir: string; logger?: { warn(message: string): void } },
|
|
105
|
+
): Promise<string[]> {
|
|
106
|
+
if (references === undefined || references.length === 0) return []
|
|
107
|
+
const requested = [...new Set(references.map((slug) => slug.trim()).filter((slug) => slug.length > 0))]
|
|
108
|
+
if (resolver === undefined) return requested
|
|
109
|
+
|
|
110
|
+
const known = new Set(await resolver(ctx.agentDir))
|
|
111
|
+
const valid = requested.filter((slug) => known.has(slug))
|
|
112
|
+
const dropped = requested.filter((slug) => !known.has(slug))
|
|
113
|
+
if (dropped.length > 0) {
|
|
114
|
+
ctx.logger?.warn(
|
|
115
|
+
`[memory] dropped ${dropped.length} unknown reference slug(s) from fragment: ${dropped.join(', ')}. ` +
|
|
116
|
+
`references[] may only cite slugs returned by store_reference.`,
|
|
117
|
+
)
|
|
118
|
+
}
|
|
119
|
+
return valid
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function assertNoSecrets(parts: ReadonlyArray<string | undefined>): void {
|
|
123
|
+
const content = parts.filter((part): part is string => part !== undefined).join('\n')
|
|
124
|
+
const secrets = detectSecrets(content)
|
|
125
|
+
if (secrets.length === 0) return
|
|
126
|
+
|
|
127
|
+
const ruleNames = [...new Set(secrets.map((s) => s.rule))].join(', ')
|
|
128
|
+
throw new Error(
|
|
129
|
+
`Refusing to append: content contains a recognized credential pattern (${ruleNames}). ` +
|
|
130
|
+
`Memory fragments must never quote secret values verbatim. Record the env var name and how it ` +
|
|
131
|
+
`was discovered, not the value itself.`,
|
|
132
|
+
)
|
|
133
|
+
}
|