@picassohq/cli 1.0.6 → 1.0.9

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 (42) hide show
  1. package/LICENSE +14 -0
  2. package/README.md +104 -0
  3. package/dist/build-info.json +1 -1
  4. package/dist/index.js +1955 -1530
  5. package/package.json +27 -5
  6. package/runtime/dsh/picasso-providers.patch.yml +49 -61
  7. package/runtime/dsh/picasso-runtime.cordis.yml +49 -61
  8. package/runtime/engine-manifest.json +18 -8
  9. package/runtime/packages/picasso-browser/cordis.patch.yml +4 -0
  10. package/runtime/packages/picasso-browser/index.js +915 -0
  11. package/runtime/packages/picasso-browser/package.json +29 -0
  12. package/runtime/packages/picasso-commands/index.js +51 -1
  13. package/runtime/packages/picasso-compaction/index.js +116 -1
  14. package/runtime/packages/picasso-computer/cordis.patch.yml +5 -0
  15. package/runtime/packages/picasso-computer/index.js +670 -0
  16. package/runtime/packages/picasso-computer/native-anthropic.js +212 -0
  17. package/runtime/packages/picasso-computer/package.json +30 -0
  18. package/runtime/packages/picasso-computer/support.js +95 -0
  19. package/runtime/packages/picasso-lean-context/index.js +751 -15
  20. package/runtime/packages/picasso-lean-context/timeline.js +3 -2
  21. package/runtime/packages/picasso-model-router/connections.js +1 -1
  22. package/runtime/packages/picasso-progress-reports/index.js +121 -3
  23. package/runtime/packages/picasso-sdk-server/browser-host.js +94 -0
  24. package/runtime/packages/picasso-sdk-server/index.js +23 -3
  25. package/runtime/plugins/picasso-browser/index.js +319 -22
  26. package/runtime/plugins/picasso-browser/package.json +1 -1
  27. package/runtime/plugins/picasso-commands/index.js +51 -1
  28. package/runtime/plugins/picasso-compaction/index.js +116 -1
  29. package/runtime/plugins/picasso-computer/index.js +670 -0
  30. package/runtime/plugins/picasso-computer/native-anthropic.js +212 -0
  31. package/runtime/plugins/picasso-computer/package.json +30 -0
  32. package/runtime/plugins/picasso-computer/support.js +95 -0
  33. package/runtime/plugins/picasso-lean-context/index.js +751 -15
  34. package/runtime/plugins/picasso-lean-context/timeline.js +3 -2
  35. package/runtime/plugins/picasso-model-router/connections.js +1 -1
  36. package/runtime/plugins/picasso-progress-reports/index.js +121 -3
  37. package/runtime/relay/main.mjs +5005 -2250
  38. package/runtime/relay/remote/index.html +10 -2
  39. package/runtime/relay/remote/remote.css +8 -1
  40. package/runtime/relay/remote/remote.js +78 -17
  41. package/runtime/relay/versions-routes.mjs +52 -37
  42. package/scripts/install-runtime.mjs +33 -7
@@ -235,7 +235,7 @@ export const SKILL_DESC_MAX_CHARS = 200;
235
235
  // registry: { tier1Tools, deferredTools, mcpGateways, mcpServers[], skills },
236
236
  // snapshot: {at, sessionId?, messageCount, instructions:{before,after,capped},
237
237
  // skillCatalog:{before,after,capped,overflowCount},
238
- // dedupe:{removedBlocks,removedNames[]}, injected:{planMode,runtimePolicy,staleTodos,planNudge}, skillsKnown},
238
+ // dedupe:{removedBlocks,removedNames[]}, injected:{planMode,runtimePolicy,staleTodos,planNudge,planState}, skillsKnown},
239
239
  // counters: {totalSteps, instructionsCapped, skillsOverflowed, dedupeRuns, remindersInjected},
240
240
  // events: [{at, kind, detail}] (newest first, ring-capped),
241
241
  // }.
@@ -430,6 +430,7 @@ export class ContextStats {
430
430
  injected.runtimePolicy === true ? "runtime-policy" : null,
431
431
  injected.staleTodos === true ? "stale-todos" : null,
432
432
  injected.planNudge === true ? "plan-nudge" : null,
433
+ injected.planState === true ? "plan-state" : null,
433
434
  ].filter(Boolean);
434
435
 
435
436
  if (instructions.capped === true) {
@@ -481,6 +482,7 @@ export class ContextStats {
481
482
  runtimePolicy: injected.runtimePolicy === true,
482
483
  staleTodos: injected.staleTodos === true,
483
484
  planNudge: injected.planNudge === true,
485
+ planState: injected.planState === true,
484
486
  },
485
487
  skillsKnown: Number.isSafeInteger(meta.skillsKnown) ? meta.skillsKnown : this.registry.skills,
486
488
  };
@@ -2355,13 +2357,13 @@ export const STATIC_TOOL_CATALOG = Object.freeze([
2355
2357
  name: "read_image",
2356
2358
  group: "session-web",
2357
2359
  wire: false,
2358
- description: "Read a PNG/JPEG/WebP/GIF file and return the image itself. Large images are downscaled automatically; do not install image libraries or create thumbnails to inspect an image.",
2360
+ description: "Read the PNG/JPEG/WebP/GIF file at `file_path` and return the image itself: read_image({ file_path: \"/tmp/shot.png\" }) (`path` is accepted for `file_path`). Large images are downscaled automatically; do not install image libraries or create thumbnails to inspect an image.",
2359
2361
  parameters: {
2360
2362
  "type": "object",
2361
2363
  "properties": {
2362
2364
  "file_path": {
2363
2365
  "type": "string",
2364
- "description": "Path to the image file, resolved by the filesystem backend."
2366
+ "description": "Path to the image file (the argument is `file_path`; `path` is accepted too), resolved by the filesystem backend."
2365
2367
  }
2366
2368
  },
2367
2369
  "required": [
@@ -2892,6 +2894,425 @@ export const STATIC_TOOL_CATALOG = Object.freeze([
2892
2894
  "additionalProperties": false
2893
2895
  },
2894
2896
  },
2897
+ {
2898
+ name: "computer_cursor_position",
2899
+ group: "picasso-extensions",
2900
+ wire: false,
2901
+ description: "Read where the mouse pointer is, in screenshot pixels. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
2902
+ parameters: {
2903
+ "type": "object",
2904
+ "properties": {},
2905
+ "additionalProperties": false
2906
+ },
2907
+ },
2908
+ {
2909
+ name: "computer_double_click",
2910
+ group: "picasso-extensions",
2911
+ wire: false,
2912
+ description: "Double-click at a point (or where the pointer is). This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
2913
+ parameters: {
2914
+ "type": "object",
2915
+ "properties": {
2916
+ "coordinate": {
2917
+ "type": "array",
2918
+ "items": {
2919
+ "type": "integer"
2920
+ },
2921
+ "minItems": 2,
2922
+ "maxItems": 2,
2923
+ "description": "Where to click as [x, y] pixels in the latest screenshot."
2924
+ },
2925
+ "text": {
2926
+ "type": "string",
2927
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
2928
+ }
2929
+ },
2930
+ "additionalProperties": false
2931
+ },
2932
+ },
2933
+ {
2934
+ name: "computer_hold_key",
2935
+ group: "picasso-extensions",
2936
+ wire: false,
2937
+ description: "Hold a key or key combination down for a number of seconds, then release it. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
2938
+ parameters: {
2939
+ "type": "object",
2940
+ "properties": {
2941
+ "text": {
2942
+ "type": "string",
2943
+ "description": "Key or \"+\"-joined combination (xdotool names, e.g. \"shift\" or \"cmd+tab\")."
2944
+ },
2945
+ "duration": {
2946
+ "type": "number",
2947
+ "description": "Seconds to hold (up to 300)."
2948
+ }
2949
+ },
2950
+ "required": [
2951
+ "text",
2952
+ "duration"
2953
+ ],
2954
+ "additionalProperties": false
2955
+ },
2956
+ },
2957
+ {
2958
+ name: "computer_key",
2959
+ group: "picasso-extensions",
2960
+ wire: false,
2961
+ description: "Press a key or key combination, e.g. \"Return\", \"Escape\", \"cmd+s\", \"ctrl+shift+t\". This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
2962
+ parameters: {
2963
+ "type": "object",
2964
+ "properties": {
2965
+ "text": {
2966
+ "type": "string",
2967
+ "description": "Key or \"+\"-joined combination (xdotool names: Return, Tab, Escape, BackSpace, Up, Page_Down, F5, cmd+c …)."
2968
+ },
2969
+ "repeat": {
2970
+ "type": "integer",
2971
+ "description": "How many times to press it (1 to 100, default 1)."
2972
+ }
2973
+ },
2974
+ "required": [
2975
+ "text"
2976
+ ],
2977
+ "additionalProperties": false
2978
+ },
2979
+ },
2980
+ {
2981
+ name: "computer_left_click",
2982
+ group: "picasso-extensions",
2983
+ wire: false,
2984
+ description: "Left-click at a point (or where the pointer is). This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
2985
+ parameters: {
2986
+ "type": "object",
2987
+ "properties": {
2988
+ "coordinate": {
2989
+ "type": "array",
2990
+ "items": {
2991
+ "type": "integer"
2992
+ },
2993
+ "minItems": 2,
2994
+ "maxItems": 2,
2995
+ "description": "Where to click as [x, y] pixels in the latest screenshot."
2996
+ },
2997
+ "text": {
2998
+ "type": "string",
2999
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
3000
+ }
3001
+ },
3002
+ "additionalProperties": false
3003
+ },
3004
+ },
3005
+ {
3006
+ name: "computer_left_click_drag",
3007
+ group: "picasso-extensions",
3008
+ wire: false,
3009
+ description: "Press the left button at one point, drag to another and release. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3010
+ parameters: {
3011
+ "type": "object",
3012
+ "properties": {
3013
+ "start_coordinate": {
3014
+ "type": "array",
3015
+ "items": {
3016
+ "type": "integer"
3017
+ },
3018
+ "minItems": 2,
3019
+ "maxItems": 2,
3020
+ "description": "Where the drag starts as [x, y] pixels in the latest screenshot."
3021
+ },
3022
+ "coordinate": {
3023
+ "type": "array",
3024
+ "items": {
3025
+ "type": "integer"
3026
+ },
3027
+ "minItems": 2,
3028
+ "maxItems": 2,
3029
+ "description": "Where the drag ends as [x, y] pixels in the latest screenshot."
3030
+ },
3031
+ "text": {
3032
+ "type": "string",
3033
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
3034
+ }
3035
+ },
3036
+ "required": [
3037
+ "start_coordinate",
3038
+ "coordinate"
3039
+ ],
3040
+ "additionalProperties": false
3041
+ },
3042
+ },
3043
+ {
3044
+ name: "computer_left_mouse_down",
3045
+ group: "picasso-extensions",
3046
+ wire: false,
3047
+ description: "Press the left mouse button where the pointer is and keep it down (pair with computer_left_mouse_up). This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3048
+ parameters: {
3049
+ "type": "object",
3050
+ "properties": {},
3051
+ "additionalProperties": false
3052
+ },
3053
+ },
3054
+ {
3055
+ name: "computer_left_mouse_up",
3056
+ group: "picasso-extensions",
3057
+ wire: false,
3058
+ description: "Release the left mouse button where the pointer is. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3059
+ parameters: {
3060
+ "type": "object",
3061
+ "properties": {},
3062
+ "additionalProperties": false
3063
+ },
3064
+ },
3065
+ {
3066
+ name: "computer_list_apps",
3067
+ group: "picasso-extensions",
3068
+ wire: false,
3069
+ description: "List the apps running on the Mac: name, bundle id, whether it is frontmost or hidden, and whether Picasso may control it. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3070
+ parameters: {
3071
+ "type": "object",
3072
+ "properties": {},
3073
+ "additionalProperties": false
3074
+ },
3075
+ },
3076
+ {
3077
+ name: "computer_list_windows",
3078
+ group: "picasso-extensions",
3079
+ wire: false,
3080
+ description: "List the displays and the windows on screen: window id, app, title, frame and display. Pass a window id or display number to computer_screenshot to capture just that. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3081
+ parameters: {
3082
+ "type": "object",
3083
+ "properties": {
3084
+ "app": {
3085
+ "type": "string",
3086
+ "description": "Only windows of this app (name or bundle id)."
3087
+ }
3088
+ },
3089
+ "additionalProperties": false
3090
+ },
3091
+ },
3092
+ {
3093
+ name: "computer_middle_click",
3094
+ group: "picasso-extensions",
3095
+ wire: false,
3096
+ description: "Middle-click at a point (or where the pointer is). This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3097
+ parameters: {
3098
+ "type": "object",
3099
+ "properties": {
3100
+ "coordinate": {
3101
+ "type": "array",
3102
+ "items": {
3103
+ "type": "integer"
3104
+ },
3105
+ "minItems": 2,
3106
+ "maxItems": 2,
3107
+ "description": "Where to click as [x, y] pixels in the latest screenshot."
3108
+ },
3109
+ "text": {
3110
+ "type": "string",
3111
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
3112
+ }
3113
+ },
3114
+ "additionalProperties": false
3115
+ },
3116
+ },
3117
+ {
3118
+ name: "computer_mouse_move",
3119
+ group: "picasso-extensions",
3120
+ wire: false,
3121
+ description: "Move the mouse pointer to a point. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3122
+ parameters: {
3123
+ "type": "object",
3124
+ "properties": {
3125
+ "coordinate": {
3126
+ "type": "array",
3127
+ "items": {
3128
+ "type": "integer"
3129
+ },
3130
+ "minItems": 2,
3131
+ "maxItems": 2,
3132
+ "description": "Where to move the pointer as [x, y] pixels in the latest screenshot."
3133
+ }
3134
+ },
3135
+ "required": [
3136
+ "coordinate"
3137
+ ],
3138
+ "additionalProperties": false
3139
+ },
3140
+ },
3141
+ {
3142
+ name: "computer_right_click",
3143
+ group: "picasso-extensions",
3144
+ wire: false,
3145
+ description: "Right-click at a point (or where the pointer is). This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3146
+ parameters: {
3147
+ "type": "object",
3148
+ "properties": {
3149
+ "coordinate": {
3150
+ "type": "array",
3151
+ "items": {
3152
+ "type": "integer"
3153
+ },
3154
+ "minItems": 2,
3155
+ "maxItems": 2,
3156
+ "description": "Where to click as [x, y] pixels in the latest screenshot."
3157
+ },
3158
+ "text": {
3159
+ "type": "string",
3160
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
3161
+ }
3162
+ },
3163
+ "additionalProperties": false
3164
+ },
3165
+ },
3166
+ {
3167
+ name: "computer_screenshot",
3168
+ group: "picasso-extensions",
3169
+ wire: false,
3170
+ description: "Capture the screen as an image. By default the main display; pass display (from computer_list_windows) or window_id to capture that instead, which also sets what later coordinates refer to. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3171
+ parameters: {
3172
+ "type": "object",
3173
+ "properties": {
3174
+ "display": {
3175
+ "type": "integer",
3176
+ "description": "Display number from computer_list_windows (1 is the main display)."
3177
+ },
3178
+ "window_id": {
3179
+ "type": "integer",
3180
+ "description": "Window id from computer_list_windows: capture only that window."
3181
+ }
3182
+ },
3183
+ "additionalProperties": false
3184
+ },
3185
+ },
3186
+ {
3187
+ name: "computer_scroll",
3188
+ group: "picasso-extensions",
3189
+ wire: false,
3190
+ description: "Scroll at a point (or where the pointer is) by a number of wheel clicks. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3191
+ parameters: {
3192
+ "type": "object",
3193
+ "properties": {
3194
+ "scroll_direction": {
3195
+ "type": "string",
3196
+ "enum": [
3197
+ "up",
3198
+ "down",
3199
+ "left",
3200
+ "right"
3201
+ ],
3202
+ "description": "up, down, left or right."
3203
+ },
3204
+ "scroll_amount": {
3205
+ "type": "integer",
3206
+ "description": "Wheel clicks (1 to 50)."
3207
+ },
3208
+ "coordinate": {
3209
+ "type": "array",
3210
+ "items": {
3211
+ "type": "integer"
3212
+ },
3213
+ "minItems": 2,
3214
+ "maxItems": 2,
3215
+ "description": "Where to scroll as [x, y] pixels in the latest screenshot."
3216
+ },
3217
+ "text": {
3218
+ "type": "string",
3219
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
3220
+ }
3221
+ },
3222
+ "required": [
3223
+ "scroll_direction",
3224
+ "scroll_amount"
3225
+ ],
3226
+ "additionalProperties": false
3227
+ },
3228
+ },
3229
+ {
3230
+ name: "computer_triple_click",
3231
+ group: "picasso-extensions",
3232
+ wire: false,
3233
+ description: "Triple-click at a point (or where the pointer is). This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3234
+ parameters: {
3235
+ "type": "object",
3236
+ "properties": {
3237
+ "coordinate": {
3238
+ "type": "array",
3239
+ "items": {
3240
+ "type": "integer"
3241
+ },
3242
+ "minItems": 2,
3243
+ "maxItems": 2,
3244
+ "description": "Where to click as [x, y] pixels in the latest screenshot."
3245
+ },
3246
+ "text": {
3247
+ "type": "string",
3248
+ "description": "Modifier keys to hold: shift, ctrl, alt (option), super (cmd), or a \"+\"-joined combination such as \"cmd+shift\"."
3249
+ }
3250
+ },
3251
+ "additionalProperties": false
3252
+ },
3253
+ },
3254
+ {
3255
+ name: "computer_type",
3256
+ group: "picasso-extensions",
3257
+ wire: false,
3258
+ description: "Type text with the keyboard into whatever has focus. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3259
+ parameters: {
3260
+ "type": "object",
3261
+ "properties": {
3262
+ "text": {
3263
+ "type": "string",
3264
+ "description": "Text to type."
3265
+ }
3266
+ },
3267
+ "required": [
3268
+ "text"
3269
+ ],
3270
+ "additionalProperties": false
3271
+ },
3272
+ },
3273
+ {
3274
+ name: "computer_wait",
3275
+ group: "picasso-extensions",
3276
+ wire: false,
3277
+ description: "Wait a number of seconds (for an app to load or an animation to finish), then take a new screenshot. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3278
+ parameters: {
3279
+ "type": "object",
3280
+ "properties": {
3281
+ "duration": {
3282
+ "type": "number",
3283
+ "description": "Seconds to wait (up to 300)."
3284
+ }
3285
+ },
3286
+ "required": [
3287
+ "duration"
3288
+ ],
3289
+ "additionalProperties": false
3290
+ },
3291
+ },
3292
+ {
3293
+ name: "computer_zoom",
3294
+ group: "picasso-extensions",
3295
+ wire: false,
3296
+ description: "Look closer at one region of the latest screenshot, returned at a higher resolution. Coordinates stay those of the full screenshot. This is computer use: it controls the person’s Mac through Picasso for Mac (other apps, the mouse, the keyboard and the screen), only after the person turns it on for this thread and approves the actions. Take computer_screenshot first: coordinates are pixels in the latest screenshot. Password managers, Keychain Access and System Settings › Privacy are never controlled, and nothing runs while the Mac is locked.",
3297
+ parameters: {
3298
+ "type": "object",
3299
+ "properties": {
3300
+ "region": {
3301
+ "type": "array",
3302
+ "items": {
3303
+ "type": "integer"
3304
+ },
3305
+ "minItems": 4,
3306
+ "maxItems": 4,
3307
+ "description": "The region as [x0, y0, x1, y1] pixels in the latest screenshot."
3308
+ }
3309
+ },
3310
+ "required": [
3311
+ "region"
3312
+ ],
3313
+ "additionalProperties": false
3314
+ },
3315
+ },
2895
3316
  {
2896
3317
  name: "remember",
2897
3318
  group: "picasso-extensions",
@@ -3265,7 +3686,7 @@ export function refuseModelWorktree() {
3265
3686
  };
3266
3687
  }
3267
3688
 
3268
- const DEFERRED_TOOL_ALIASES = Object.freeze({
3689
+ export const DEFERRED_TOOL_ALIASES = Object.freeze({
3269
3690
  cron_create: "schedule_create",
3270
3691
  cron_delete: "schedule_edit",
3271
3692
  cron_list: "schedule_list",
@@ -3574,6 +3995,56 @@ export function writeMcpServerCatalog(serverName, tools, baseDir) {
3574
3995
 
3575
3996
  export { writeMcpServerCatalog as writeMcpCatalogFiles };
3576
3997
 
3998
+ /**
3999
+ * Per-session visibility of a deferred tool in `tool_search`: a plugin may hide its tools from sessions that cannot use
4000
+ * them (packages/picasso-computer hides `computer_*` on models that can't see screenshots) through a
4001
+ * `picassoVisibleTo(agent)` predicate on the registered definition or the process-wide
4002
+ * `Symbol.for("picasso.toolVisibility")` map (tool name → predicate). Fail-open: a throwing predicate lists the tool.
4003
+ * Only the search result changes (Tier 2); the wire tool list is never touched.
4004
+ */
4005
+ export const TOOL_VISIBILITY_KEY = Symbol.for("picasso.toolVisibility");
4006
+ function hiddenFromSearch(toolName, toolsSvc, agent) {
4007
+ const predicates = [];
4008
+ const shared = globalThis[TOOL_VISIBILITY_KEY];
4009
+ if (shared instanceof Map && typeof shared.get(toolName) === "function") predicates.push(shared.get(toolName));
4010
+ try {
4011
+ const def = toolsSvc?.get?.(toolName, agent);
4012
+ if (def && typeof def.picassoVisibleTo === "function") predicates.push(def.picassoVisibleTo);
4013
+ } catch {
4014
+ // an unreadable definition stays listed
4015
+ }
4016
+ for (const visible of predicates) {
4017
+ try {
4018
+ if (visible(agent) === false) return true;
4019
+ } catch {
4020
+ // fail-open
4021
+ }
4022
+ }
4023
+ return false;
4024
+ }
4025
+
4026
+ /**
4027
+ * Whether `tool_call` would run `toolName` for this agent: registered on the runtime tools service (by name or alias
4028
+ * target, or through the subagent-control redirect), a gateway-local search, or a `<server>_call` MCP gateway for a
4029
+ * server this process discovered. `tool_search` lists only these, so a session never finds a deferred tool (a static
4030
+ * catalog entry such as `browser_*` or `computer_*` on a surface that did not mount its plugin) that it cannot call.
4031
+ * No tools service, a service without `get`, or a throwing lookup lists the tool (fail-open). Tier 2 only.
4032
+ */
4033
+ export function resolvesForAgent(toolName, toolsSvc, agent, mcpServerNames = new Set()) {
4034
+ if (toolsSvc === undefined || toolsSvc === null || typeof toolsSvc.get !== "function") return true;
4035
+ if (GATEWAY_LOCAL_TARGETS.includes(toolName)) return true;
4036
+ const resolved = DEFERRED_TOOL_ALIASES[toolName] ?? toolName;
4037
+ try {
4038
+ if (toolsSvc.get(toolName, agent) || toolsSvc.get(resolved, agent)) return true;
4039
+ const steer = SUBAGENT_CONTROL_REDIRECTS[resolved];
4040
+ if (steer !== undefined && toolsSvc.get(steer, agent)) return true;
4041
+ } catch {
4042
+ return true;
4043
+ }
4044
+ const gateway = /^([a-zA-Z0-9_-]+)_call$/.exec(toolName);
4045
+ return gateway !== null && toolName !== "tool_call" && mcpServerNames.has(gateway[1]);
4046
+ }
4047
+
3577
4048
  const STATIC_TOOL_NAME_SET = new Set(STATIC_TOOL_CATALOG.map((item) => item.name));
3578
4049
 
3579
4050
  /**
@@ -4389,6 +4860,14 @@ export function visibleSkillCatalogText(session) {
4389
4860
  // resumed session keeps its counts.
4390
4861
 
4391
4862
  export const STALE_TODOS_SOURCE_KIND = "stale-todos";
4863
+ /**
4864
+ * What to do with a plan that belongs to an earlier task (owner 2026-11-18, session m0-d03430f0: the plan-state reminder
4865
+ * re-stated a 6/10 plan for a finished deploy three times; both models had moved on to other work and ignored a list that
4866
+ * no longer matched it, so the stale plan stayed in every panel). Every plan reminder says: replace it, or mark finished
4867
+ * and obsolete items completed, or clear it with an empty list (the engine's todo_write accepts `todos: []`).
4868
+ */
4869
+ export const PLAN_REPLACE_OR_CLEAR_LINE =
4870
+ "If it no longer matches what you are working on now, replace it with todo_write for the current work, or mark finished and obsolete items completed. If the current task has no plan, clear it: todo_write with an empty list (todos: []).";
4392
4871
  export const STALE_TODOS_TOOL_CALLS = 20;
4393
4872
  export const STALE_TODOS_MAX_PER_WRITE = 2;
4394
4873
 
@@ -4443,6 +4922,8 @@ export function foldStaleTodosEvent(state, event, seq) {
4443
4922
  case "user/message": {
4444
4923
  const source = event.data?.source;
4445
4924
  if (source?.kind === "goal" && Number(source.round) > 0) state.goalRoundSinceWrite = true;
4925
+ // The plan-state reminder re-stated the whole list after the compaction: that compaction needs no nudge too.
4926
+ if (source?.kind === "plan-state") state.compactionSinceWrite = false;
4446
4927
  if (source?.kind === STALE_TODOS_SOURCE_KIND) {
4447
4928
  state.nudgesSinceWrite += 1;
4448
4929
  state.toolCallsSinceNudge = 0;
@@ -4499,7 +4980,7 @@ export function renderStaleTodosReminder(todos) {
4499
4980
  active >= 0
4500
4981
  ? `step ${active + 1} still in progress`
4501
4982
  : `${open} of ${list.length} step${list.length === 1 ? "" : "s"} still open`;
4502
- return `<system-reminder>\nYour task list hasn't changed in a while (${where}). If you've moved on, update it with todo_write; if it no longer fits, replace it.\n</system-reminder>`;
4983
+ return `<system-reminder>\nYour task list hasn't changed in a while (${where}). Update it with todo_write as items finish. ${PLAN_REPLACE_OR_CLEAR_LINE}\n</system-reminder>`;
4503
4984
  }
4504
4985
 
4505
4986
  /** A frozen sourced user-role reminder message carrying the nudge. */
@@ -4613,6 +5094,222 @@ export function planNudgeReminderMessage() {
4613
5094
  });
4614
5095
  }
4615
5096
 
5097
+ // ── Plan state (Tier 2): the plan and the active goal, re-stated when the model may not have them ─────────────────
5098
+ //
5099
+ // Owner 2026-11-18 (session m0-d03430f0): a 10-item plan sat at 65% through a /compact and two model switches while
5100
+ // the model ran 35+ tool steps and reported everything done. Neither compaction summary carried the items, no reminder
5101
+ // named them, and the stale-todos nudge (twice per write, spent before the compaction) says only "step 7 is still in
5102
+ // progress". So the model that came after did not know a plan existed.
5103
+ //
5104
+ // The rule: while the session holds a plan with open items (the last `todo/write`), or an active goal, the model must
5105
+ // have it in view. It is in view after the `todo/write` itself (the call carries the whole list), a goal round's prompt
5106
+ // (it carries the objective) or this reminder. A compaction summarises those away and a model switched in is a new
5107
+ // reader, so after either one the next step gets ONE sourced `plan-state` `<system-reminder>` at the tail of its
5108
+ // messages (durable history, Tier 2): the active goal, then every plan item with its status, then "Update it with
5109
+ // todo_write as items finish." Nothing is repeated while nothing changed: the reminder's own `user/message` marks it
5110
+ // seen. The text depends only on the folded state, so identical history yields identical bytes; Tier 1 is never touched.
5111
+ // All state folds from the session's durable events, so a resumed session (or one compacted before this existed)
5112
+ // gets it at its next step.
5113
+
5114
+ export const PLAN_STATE_SOURCE_KIND = "plan-state";
5115
+ export const PLAN_STATE_UPDATE_LINE = "Update it with todo_write as items finish.";
5116
+ // PLAN_REPLACE_OR_CLEAR_LINE (defined with the stale-todos nudge) follows it: the plan may be from an earlier task.
5117
+ /** Items listed in full; a longer list names how many more there are. */
5118
+ export const PLAN_STATE_MAX_ITEMS = 40;
5119
+ /** Characters of one item (or the goal objective) kept; a longer one ends in "…". */
5120
+ export const PLAN_STATE_ITEM_MAX_CHARS = 300;
5121
+ export const PLAN_STATE_OBJECTIVE_MAX_CHARS = 1200;
5122
+ const GOAL_CONTRACT_RECORD = "plugin:picasso/goal-contract";
5123
+
5124
+ /**
5125
+ * A model id compared across switches: the route prefix a picker adds (`cloudflare-workers-ai:@cf/…`,
5126
+ * `experiential:<id>`) is dropped so the same model selected two ways is one model.
5127
+ */
5128
+ export function planStateModelKey(model) {
5129
+ if (typeof model !== "string" || model.trim() === "") return undefined;
5130
+ return model.trim().replace(/^[A-Za-z0-9_-]+:(?=[^:])/u, "");
5131
+ }
5132
+
5133
+ /** Fresh per-session plan-state fold. */
5134
+ export function freshPlanStateState() {
5135
+ return {
5136
+ scanned: 0,
5137
+ /** The last `todo/write` list. */
5138
+ todos: [],
5139
+ /** The plan is in the model's view (written, or re-stated, since the last compaction or model switch). */
5140
+ planSeen: false,
5141
+ /** The active goal `{ id, objective, phase }`, or undefined. */
5142
+ goal: undefined,
5143
+ /** The goal's objective is in the model's view (a round prompt or this reminder since the last hide). */
5144
+ goalSeen: false,
5145
+ /** Goal-contract approvals `{ goalId?, objective, contractPath }`, oldest first. */
5146
+ contracts: [],
5147
+ /** The model the session runs on now (`planStateModelKey`). */
5148
+ model: undefined,
5149
+ };
5150
+ }
5151
+
5152
+ function hidePlanState(state) {
5153
+ state.planSeen = false;
5154
+ state.goalSeen = false;
5155
+ }
5156
+
5157
+ /** Fold one durable session event into the plan-state record. */
5158
+ export function foldPlanStateEvent(state, event) {
5159
+ if (!isRecord(event)) return state;
5160
+ const data = isRecord(event.data) ? event.data : {};
5161
+ switch (event.type) {
5162
+ case "todo/write":
5163
+ state.todos = todosFrom(data);
5164
+ state.planSeen = true;
5165
+ break;
5166
+ case "compaction/end":
5167
+ // A compaction that failed replaced nothing.
5168
+ if (typeof data.error !== "string" || data.error === "") hidePlanState(state);
5169
+ break;
5170
+ case "model/selection":
5171
+ case "request/context": {
5172
+ const key = planStateModelKey(data.model);
5173
+ if (key === undefined) break;
5174
+ if (state.model !== undefined && state.model !== key) hidePlanState(state);
5175
+ state.model = key;
5176
+ break;
5177
+ }
5178
+ case "goal/change": {
5179
+ if (data.operation === "clear") {
5180
+ state.goal = undefined;
5181
+ break;
5182
+ }
5183
+ const goal = isRecord(data.goal) ? data.goal : undefined;
5184
+ if (!goal || typeof goal.objective !== "string") break;
5185
+ if (state.goal?.objective !== goal.objective) state.goalSeen = false;
5186
+ state.goal = {
5187
+ id: typeof goal.id === "string" ? goal.id : undefined,
5188
+ objective: goal.objective,
5189
+ phase: typeof goal.phase === "string" ? goal.phase : undefined,
5190
+ };
5191
+ break;
5192
+ }
5193
+ case GOAL_CONTRACT_RECORD: {
5194
+ const approval = isRecord(data.event) ? data.event : undefined;
5195
+ if (approval && typeof approval.objective === "string" && typeof approval.contractPath === "string") {
5196
+ state.contracts.push({
5197
+ ...(typeof approval.goalId === "string" ? { goalId: approval.goalId } : {}),
5198
+ objective: approval.objective,
5199
+ contractPath: approval.contractPath,
5200
+ });
5201
+ }
5202
+ break;
5203
+ }
5204
+ case "user/message": {
5205
+ const source = data.source;
5206
+ if (source?.kind === PLAN_STATE_SOURCE_KIND) {
5207
+ state.planSeen = true;
5208
+ state.goalSeen = true;
5209
+ } else if (source?.kind === "goal" && Number(source.round) > 0) {
5210
+ state.goalSeen = true;
5211
+ }
5212
+ break;
5213
+ }
5214
+ default:
5215
+ break;
5216
+ }
5217
+ return state;
5218
+ }
5219
+
5220
+ /** Bring a session's plan-state record up to date with its event log (incremental; restarts if the log shrank). */
5221
+ export function scanPlanStateSession(states, session) {
5222
+ let state = states.get(session);
5223
+ const length = Number.isSafeInteger(session?.seq) ? session.seq : 0;
5224
+ if (!state || state.scanned > length) state = freshPlanStateState();
5225
+ for (let seq = state.scanned; seq < length; seq += 1) {
5226
+ let event;
5227
+ try {
5228
+ event = session.eventAt(seq);
5229
+ } catch {
5230
+ event = undefined;
5231
+ }
5232
+ foldPlanStateEvent(state, event);
5233
+ }
5234
+ state.scanned = length;
5235
+ states.set(session, state);
5236
+ return state;
5237
+ }
5238
+
5239
+ /** The active goal, or undefined. */
5240
+ function activeGoal(state) {
5241
+ return isRecord(state?.goal) && state.goal.phase === "active" ? state.goal : undefined;
5242
+ }
5243
+
5244
+ /** The contract approved for `goal` (bound to its id, or written for its objective), newest first. */
5245
+ function contractFor(state, goal) {
5246
+ const contracts = Array.isArray(state?.contracts) ? state.contracts : [];
5247
+ for (let index = contracts.length - 1; index >= 0; index -= 1) {
5248
+ const entry = contracts[index];
5249
+ if (entry.goalId === goal.id || (entry.goalId === undefined && entry.objective === goal.objective)) return entry;
5250
+ }
5251
+ return undefined;
5252
+ }
5253
+
5254
+ /**
5255
+ * What a `plan-state` reminder would carry now (`{ todos, goal, contractPath }`), or undefined when the model already
5256
+ * has all of it in view. `proposed` are this step's not-yet-logged messages: a goal round's prompt there shows the goal.
5257
+ */
5258
+ export function planStateReminderDue(state, proposed = []) {
5259
+ if (!isRecord(state)) return undefined;
5260
+ const planOpen = hasUnfinishedTodos(state.todos);
5261
+ const goal = activeGoal(state);
5262
+ const roundInStep = Array.isArray(proposed) && proposed.some((msg) => msg?.source?.kind === "goal" && Number(msg.source.round) > 0);
5263
+ const planDue = planOpen && state.planSeen !== true;
5264
+ const goalDue = goal !== undefined && state.goalSeen !== true && !roundInStep;
5265
+ if (!planDue && !goalDue) return undefined;
5266
+ const contract = goal === undefined ? undefined : contractFor(state, goal);
5267
+ return {
5268
+ todos: planOpen ? state.todos : [],
5269
+ ...(goal === undefined ? {} : { goal: goal.objective }),
5270
+ ...(contract === undefined ? {} : { contractPath: contract.contractPath }),
5271
+ };
5272
+ }
5273
+
5274
+ function clipLine(value, max) {
5275
+ const flat = String(value ?? "").replace(/\s+/gu, " ").trim();
5276
+ return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
5277
+ }
5278
+
5279
+ /** The reminder text. Depends only on what it carries, so identical history yields identical bytes. */
5280
+ export function renderPlanStateReminder({ todos = [], goal, contractPath } = {}) {
5281
+ const lines = ["<system-reminder>"];
5282
+ if (typeof goal === "string" && goal.trim() !== "") {
5283
+ lines.push(`Active goal: ${clipLine(goal, PLAN_STATE_OBJECTIVE_MAX_CHARS)}`);
5284
+ if (typeof contractPath === "string" && contractPath !== "") {
5285
+ lines.push(`Goal contract: ${contractPath} (completing the goal is checked against it).`);
5286
+ }
5287
+ }
5288
+ const list = Array.isArray(todos) ? todos : [];
5289
+ if (list.length > 0) {
5290
+ const done = list.filter((todo) => TODO_DONE_STATUSES.has(String(todo?.status ?? "pending"))).length;
5291
+ lines.push(`Your plan (todo_write), ${done} of ${list.length} done:`);
5292
+ for (const todo of list.slice(0, PLAN_STATE_MAX_ITEMS)) {
5293
+ lines.push(`- [${clipLine(todo?.status ?? "pending", 24)}] ${clipLine(todo?.content, PLAN_STATE_ITEM_MAX_CHARS)}`);
5294
+ }
5295
+ if (list.length > PLAN_STATE_MAX_ITEMS) lines.push(`- … ${list.length - PLAN_STATE_MAX_ITEMS} more`);
5296
+ lines.push(PLAN_STATE_UPDATE_LINE);
5297
+ lines.push(PLAN_REPLACE_OR_CLEAR_LINE);
5298
+ }
5299
+ lines.push("</system-reminder>");
5300
+ return lines.join("\n");
5301
+ }
5302
+
5303
+ /** A frozen sourced user-role reminder message carrying the plan state. */
5304
+ export function planStateReminderMessage(planState) {
5305
+ return Object.freeze({
5306
+ id: randomUUID(),
5307
+ role: "user",
5308
+ content: Object.freeze([Object.freeze({ type: "text", text: renderPlanStateReminder(planState) })]),
5309
+ source: Object.freeze({ kind: PLAN_STATE_SOURCE_KIND, form: "reminder" }),
5310
+ });
5311
+ }
5312
+
4616
5313
  // ---- Restated-fact reminders: sent when first set or changed, not on every step --------------------------------------
4617
5314
  //
4618
5315
  // The live sandbox/approval policy (`runtime-policy`, which names the workspace path) and the CLI's appended
@@ -4670,7 +5367,7 @@ function emptyStepStats() {
4670
5367
  // `unchangedDropped`: catalogs not sent because the model already sees the same list (`visibleSkillCatalogText`).
4671
5368
  skillCatalog: { before: 0, after: 0, capped: false, overflowCount: 0, unchangedDropped: 0 },
4672
5369
  dedupe: { removedBlocks: 0, removedNames: [] },
4673
- injected: { planMode: false, runtimePolicy: false, staleTodos: false, planNudge: false },
5370
+ injected: { planMode: false, runtimePolicy: false, staleTodos: false, planNudge: false, planState: false },
4674
5371
  // UTF-8 bytes of each injected reminder, by reminder name (the context timeline's sizes).
4675
5372
  reminderBytes: {},
4676
5373
  };
@@ -4685,6 +5382,8 @@ function emptyStepStats() {
4685
5382
  * 4. Appends the `stale-todos` nudge at the tail when `options.staleTodos` (the todo list) is passed.
4686
5383
  * 5. Appends the `plan-nudge` reminder at the tail when `options.planNudge === true` and no stale-todos nudge is
4687
5384
  * in this step (never both).
5385
+ * 6. Appends the `plan-state` reminder at the tail when `options.planState` (`planStateReminderDue`) is passed; a step
5386
+ * that carries it gets neither nudge.
4688
5387
  *
4689
5388
  * The returned `stats` field is additive and observational (`/context`): message count, instruction /
4690
5389
  * skill-catalog before-after bytes and cap flags, dedupe drops, and injected reminders.
@@ -4889,9 +5588,23 @@ export function normalizePreStepMessages(messages, options = {}) {
4889
5588
  if (!alreadyStated("append-system-prompt", appendReminderText)) insertTier2Reminder(appendReminderText, "append-system-prompt");
4890
5589
  }
4891
5590
 
5591
+ // Plan state: the plan and active goal re-stated after a compaction or a model switch (tail, Tier 2). It carries the
5592
+ // whole list, so no other task-list reminder joins it in the same step.
5593
+ const planStateInStep = () => normalized.some((msg) => msg?.source?.kind === PLAN_STATE_SOURCE_KIND);
5594
+ if (isRecord(options.planState) && !planStateInStep()) {
5595
+ const reminder = planStateReminderMessage(options.planState);
5596
+ normalized.push(reminder);
5597
+ stats.injected.planState = true;
5598
+ stats.reminderBytes["plan-state"] = Buffer.byteLength(extractMessageText(reminder), "utf8");
5599
+ }
5600
+
4892
5601
  // Stale-todos nudge: appended at the tail of this step's messages (after the tool results it is about),
4893
5602
  // never into the Tier-1 prefix. The caller decides when it is due; the text depends only on the todos.
4894
- if (Array.isArray(options.staleTodos) && !normalized.some((msg) => msg?.source?.kind === STALE_TODOS_SOURCE_KIND)) {
5603
+ if (
5604
+ Array.isArray(options.staleTodos) &&
5605
+ !planStateInStep() &&
5606
+ !normalized.some((msg) => msg?.source?.kind === STALE_TODOS_SOURCE_KIND)
5607
+ ) {
4895
5608
  const nudge = staleTodosReminderMessage(options.staleTodos);
4896
5609
  normalized.push(nudge);
4897
5610
  stats.injected.staleTodos = true;
@@ -4901,6 +5614,7 @@ export function normalizePreStepMessages(messages, options = {}) {
4901
5614
  // Plan nudge: same placement (tail, Tier 2). One task-list reminder per step: a stale-todos nudge wins.
4902
5615
  if (
4903
5616
  options.planNudge === true &&
5617
+ !planStateInStep() &&
4904
5618
  !normalized.some((msg) => msg?.source?.kind === STALE_TODOS_SOURCE_KIND || msg?.source?.kind === PLAN_NUDGE_SOURCE_KIND)
4905
5619
  ) {
4906
5620
  const nudge = planNudgeReminderMessage();
@@ -5019,10 +5733,13 @@ function singularOf(key) {
5019
5733
  /**
5020
5734
  * Arguments a model naturally sends for a deferred tool, reshaped to the schema before validation. Models that never
5021
5735
  * saw the (deferred) schema write the singular: `web_search({query: "…"})` for `{queries: ["…"]}`; six such calls in one
5022
- * step all failed before the model saw the first error. Only two conservative rewrites, both driven by the schema:
5736
+ * step all failed before the model saw the first error. Only three conservative rewrites, all driven by the schema:
5023
5737
  * - a required array field that is absent while its undeclared singular is present takes it (a string becomes a
5024
5738
  * one-item list, a list is used as is), and the singular is dropped;
5025
- * - a required array field given a single string becomes a one-item list.
5739
+ * - a required array field given a single string becomes a one-item list;
5740
+ * - a required string `file_path` that is absent while exactly one undeclared path word (`path`, `filePath`, `file`,
5741
+ * `filepath`) holds a string takes it: `read_image({path})` was refused once per session before the model retried
5742
+ * with `file_path` (owner session 3be85da0, 2026-11-18).
5026
5743
  * Anything else is returned unchanged (the same object), so validation still reports it.
5027
5744
  */
5028
5745
  export function normalizeToolArguments(args, schema) {
@@ -5055,9 +5772,21 @@ export function normalizeToolArguments(args, schema) {
5055
5772
  next[key] = list;
5056
5773
  delete next[singular];
5057
5774
  }
5775
+ for (const [key, synonyms] of Object.entries(PATH_ARGUMENT_SYNONYMS)) {
5776
+ if (!required.includes(key) || !isRecord(schema.properties[key]) || schema.properties[key].type !== "string") continue;
5777
+ if (out[key] !== undefined && out[key] !== null) continue;
5778
+ const given = synonyms.filter((name) => !Object.hasOwn(schema.properties, name) && typeof out[name] === "string" && out[name].trim() !== "");
5779
+ if (given.length !== 1) continue;
5780
+ const next = edit();
5781
+ next[key] = next[given[0]];
5782
+ delete next[given[0]];
5783
+ }
5058
5784
  return out;
5059
5785
  }
5060
5786
 
5787
+ /** The path words a model writes for a required `file_path` it has not seen the schema of (see normalizeToolArguments). */
5788
+ const PATH_ARGUMENT_SYNONYMS = Object.freeze({ file_path: Object.freeze(["path", "filePath", "file", "filepath"]) });
5789
+
5061
5790
  /** A minimal valid-looking value for one schema property (for the "call it as" line of a validation error). */
5062
5791
  function exampleValueFor(prop) {
5063
5792
  const type = isRecord(prop) ? prop.type : undefined;
@@ -5233,6 +5962,8 @@ export function apply(ctx, config = {}, deps = {}) {
5233
5962
  const staleTodosStates = new WeakMap();
5234
5963
  // Per-session plan-nudge fold state (same durable log).
5235
5964
  const planNudgeStates = new WeakMap();
5965
+ // Per-session plan-state fold (the plan and active goal the model may not have in view).
5966
+ const planStateStates = new WeakMap();
5236
5967
  const statedReminderStates = new WeakMap();
5237
5968
  let defaultPlanPolicyText = "";
5238
5969
  // Live sandbox/approval preset text captured at assemble time (AO-006.11):
@@ -5388,6 +6119,8 @@ export function apply(ctx, config = {}, deps = {}) {
5388
6119
  for (const entry of allEntries) {
5389
6120
  if (seenNames.has(entry.name)) continue;
5390
6121
  if (entry.name.startsWith("mcp__")) continue; // MCP tools are searched via <server>_call
6122
+ if (!resolvesForAgent(entry.name, toolsSvc, exec?.agent, mcpServers)) continue; // cataloged, not registered here
6123
+ if (hiddenFromSearch(entry.name, toolsSvc, exec?.agent)) continue; // e.g. computer_* on a model that can't use them
5391
6124
  if (groupFilter && groupFilter !== "all" && entry.group !== groupFilter) continue;
5392
6125
 
5393
6126
  const { required, optional } = extractParamSummary(entry.parameters);
@@ -5770,11 +6503,8 @@ export function apply(ctx, config = {}, deps = {}) {
5770
6503
  // approval and sandbox. Only a context with no tools service at all (nothing to
5771
6504
  // bypass) may invoke a recorded handler directly.
5772
6505
  if (toolsSvc !== undefined && toolsSvc !== null) {
5773
- const refusal = formatSchemaOnError(
5774
- targetName,
5775
- `Deferred tool "${targetName}" is not registered on the runtime tools service for this agent; it was not run.`,
5776
- cachedSchema,
5777
- );
6506
+ // Not an argument problem: the plain line goes back without the schema, so the model does not retry it.
6507
+ const refusal = `Tool "${targetName}" is not available in this session (it is not registered on the runtime tools service for this agent); it was not run. Use tool_search({ query }) to see the tools this session can call.`;
5778
6508
  return {
5779
6509
  ok: false,
5780
6510
  isError: true,
@@ -6487,10 +7217,15 @@ export function apply(ctx, config = {}, deps = {}) {
6487
7217
  (agent && typeof agent === "object" ? runtimePolicyByAgent.get(agent) : undefined) ||
6488
7218
  defaultRuntimePolicyText;
6489
7219
 
7220
+ const session = isRecord(agent) ? agent.session : undefined;
7221
+ // Plan state: the plan / active goal re-stated after a compaction or a model switch (see `planStateReminderDue`).
7222
+ let planState;
7223
+ if (session && typeof session.eventAt === "function" && !payload?.signal?.aborted) {
7224
+ planState = planStateReminderDue(scanPlanStateSession(planStateStates, session), decision.messages);
7225
+ }
6490
7226
  // Stale-todos nudge: folded from the session's durable events; due only when the last todo list
6491
7227
  // still has open items and the model has moved on (see `staleTodosReminderDue`).
6492
7228
  let staleTodos;
6493
- const session = isRecord(agent) ? agent.session : undefined;
6494
7229
  if (session && typeof session.eventAt === "function" && !payload?.signal?.aborted) {
6495
7230
  const todoState = scanStaleTodosSession(staleTodosStates, session);
6496
7231
  if (staleTodosReminderDue(todoState)) staleTodos = todoState.todos;
@@ -6522,6 +7257,7 @@ export function apply(ctx, config = {}, deps = {}) {
6522
7257
  toolCatalogDir: config.toolCatalogDir,
6523
7258
  planPolicyText: agentPlanPolicy,
6524
7259
  runtimePolicyText: agentRuntimePolicy,
7260
+ planState,
6525
7261
  staleTodos,
6526
7262
  planNudge,
6527
7263
  disabledSkills,