@picassohq/cli 1.0.6 → 1.0.8

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.
@@ -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",
@@ -3574,6 +3995,34 @@ 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
+
3577
4026
  const STATIC_TOOL_NAME_SET = new Set(STATIC_TOOL_CATALOG.map((item) => item.name));
3578
4027
 
3579
4028
  /**
@@ -4443,6 +4892,8 @@ export function foldStaleTodosEvent(state, event, seq) {
4443
4892
  case "user/message": {
4444
4893
  const source = event.data?.source;
4445
4894
  if (source?.kind === "goal" && Number(source.round) > 0) state.goalRoundSinceWrite = true;
4895
+ // The plan-state reminder re-stated the whole list after the compaction: that compaction needs no nudge too.
4896
+ if (source?.kind === "plan-state") state.compactionSinceWrite = false;
4446
4897
  if (source?.kind === STALE_TODOS_SOURCE_KIND) {
4447
4898
  state.nudgesSinceWrite += 1;
4448
4899
  state.toolCallsSinceNudge = 0;
@@ -4613,6 +5064,220 @@ export function planNudgeReminderMessage() {
4613
5064
  });
4614
5065
  }
4615
5066
 
5067
+ // ── Plan state (Tier 2): the plan and the active goal, re-stated when the model may not have them ─────────────────
5068
+ //
5069
+ // Owner 2026-11-18 (session m0-d03430f0): a 10-item plan sat at 65% through a /compact and two model switches while
5070
+ // the model ran 35+ tool steps and reported everything done. Neither compaction summary carried the items, no reminder
5071
+ // named them, and the stale-todos nudge (twice per write, spent before the compaction) says only "step 7 is still in
5072
+ // progress". So the model that came after did not know a plan existed.
5073
+ //
5074
+ // The rule: while the session holds a plan with open items (the last `todo/write`), or an active goal, the model must
5075
+ // have it in view. It is in view after the `todo/write` itself (the call carries the whole list), a goal round's prompt
5076
+ // (it carries the objective) or this reminder. A compaction summarises those away and a model switched in is a new
5077
+ // reader, so after either one the next step gets ONE sourced `plan-state` `<system-reminder>` at the tail of its
5078
+ // messages (durable history, Tier 2): the active goal, then every plan item with its status, then "Update it with
5079
+ // todo_write as items finish." Nothing is repeated while nothing changed: the reminder's own `user/message` marks it
5080
+ // seen. The text depends only on the folded state, so identical history yields identical bytes; Tier 1 is never touched.
5081
+ // All state folds from the session's durable events, so a resumed session (or one compacted before this existed)
5082
+ // gets it at its next step.
5083
+
5084
+ export const PLAN_STATE_SOURCE_KIND = "plan-state";
5085
+ export const PLAN_STATE_UPDATE_LINE = "Update it with todo_write as items finish.";
5086
+ /** Items listed in full; a longer list names how many more there are. */
5087
+ export const PLAN_STATE_MAX_ITEMS = 40;
5088
+ /** Characters of one item (or the goal objective) kept; a longer one ends in "…". */
5089
+ export const PLAN_STATE_ITEM_MAX_CHARS = 300;
5090
+ export const PLAN_STATE_OBJECTIVE_MAX_CHARS = 1200;
5091
+ const GOAL_CONTRACT_RECORD = "plugin:picasso/goal-contract";
5092
+
5093
+ /**
5094
+ * A model id compared across switches: the route prefix a picker adds (`cloudflare-workers-ai:@cf/…`,
5095
+ * `experiential:<id>`) is dropped so the same model selected two ways is one model.
5096
+ */
5097
+ export function planStateModelKey(model) {
5098
+ if (typeof model !== "string" || model.trim() === "") return undefined;
5099
+ return model.trim().replace(/^[A-Za-z0-9_-]+:(?=[^:])/u, "");
5100
+ }
5101
+
5102
+ /** Fresh per-session plan-state fold. */
5103
+ export function freshPlanStateState() {
5104
+ return {
5105
+ scanned: 0,
5106
+ /** The last `todo/write` list. */
5107
+ todos: [],
5108
+ /** The plan is in the model's view (written, or re-stated, since the last compaction or model switch). */
5109
+ planSeen: false,
5110
+ /** The active goal `{ id, objective, phase }`, or undefined. */
5111
+ goal: undefined,
5112
+ /** The goal's objective is in the model's view (a round prompt or this reminder since the last hide). */
5113
+ goalSeen: false,
5114
+ /** Goal-contract approvals `{ goalId?, objective, contractPath }`, oldest first. */
5115
+ contracts: [],
5116
+ /** The model the session runs on now (`planStateModelKey`). */
5117
+ model: undefined,
5118
+ };
5119
+ }
5120
+
5121
+ function hidePlanState(state) {
5122
+ state.planSeen = false;
5123
+ state.goalSeen = false;
5124
+ }
5125
+
5126
+ /** Fold one durable session event into the plan-state record. */
5127
+ export function foldPlanStateEvent(state, event) {
5128
+ if (!isRecord(event)) return state;
5129
+ const data = isRecord(event.data) ? event.data : {};
5130
+ switch (event.type) {
5131
+ case "todo/write":
5132
+ state.todos = todosFrom(data);
5133
+ state.planSeen = true;
5134
+ break;
5135
+ case "compaction/end":
5136
+ // A compaction that failed replaced nothing.
5137
+ if (typeof data.error !== "string" || data.error === "") hidePlanState(state);
5138
+ break;
5139
+ case "model/selection":
5140
+ case "request/context": {
5141
+ const key = planStateModelKey(data.model);
5142
+ if (key === undefined) break;
5143
+ if (state.model !== undefined && state.model !== key) hidePlanState(state);
5144
+ state.model = key;
5145
+ break;
5146
+ }
5147
+ case "goal/change": {
5148
+ if (data.operation === "clear") {
5149
+ state.goal = undefined;
5150
+ break;
5151
+ }
5152
+ const goal = isRecord(data.goal) ? data.goal : undefined;
5153
+ if (!goal || typeof goal.objective !== "string") break;
5154
+ if (state.goal?.objective !== goal.objective) state.goalSeen = false;
5155
+ state.goal = {
5156
+ id: typeof goal.id === "string" ? goal.id : undefined,
5157
+ objective: goal.objective,
5158
+ phase: typeof goal.phase === "string" ? goal.phase : undefined,
5159
+ };
5160
+ break;
5161
+ }
5162
+ case GOAL_CONTRACT_RECORD: {
5163
+ const approval = isRecord(data.event) ? data.event : undefined;
5164
+ if (approval && typeof approval.objective === "string" && typeof approval.contractPath === "string") {
5165
+ state.contracts.push({
5166
+ ...(typeof approval.goalId === "string" ? { goalId: approval.goalId } : {}),
5167
+ objective: approval.objective,
5168
+ contractPath: approval.contractPath,
5169
+ });
5170
+ }
5171
+ break;
5172
+ }
5173
+ case "user/message": {
5174
+ const source = data.source;
5175
+ if (source?.kind === PLAN_STATE_SOURCE_KIND) {
5176
+ state.planSeen = true;
5177
+ state.goalSeen = true;
5178
+ } else if (source?.kind === "goal" && Number(source.round) > 0) {
5179
+ state.goalSeen = true;
5180
+ }
5181
+ break;
5182
+ }
5183
+ default:
5184
+ break;
5185
+ }
5186
+ return state;
5187
+ }
5188
+
5189
+ /** Bring a session's plan-state record up to date with its event log (incremental; restarts if the log shrank). */
5190
+ export function scanPlanStateSession(states, session) {
5191
+ let state = states.get(session);
5192
+ const length = Number.isSafeInteger(session?.seq) ? session.seq : 0;
5193
+ if (!state || state.scanned > length) state = freshPlanStateState();
5194
+ for (let seq = state.scanned; seq < length; seq += 1) {
5195
+ let event;
5196
+ try {
5197
+ event = session.eventAt(seq);
5198
+ } catch {
5199
+ event = undefined;
5200
+ }
5201
+ foldPlanStateEvent(state, event);
5202
+ }
5203
+ state.scanned = length;
5204
+ states.set(session, state);
5205
+ return state;
5206
+ }
5207
+
5208
+ /** The active goal, or undefined. */
5209
+ function activeGoal(state) {
5210
+ return isRecord(state?.goal) && state.goal.phase === "active" ? state.goal : undefined;
5211
+ }
5212
+
5213
+ /** The contract approved for `goal` (bound to its id, or written for its objective), newest first. */
5214
+ function contractFor(state, goal) {
5215
+ const contracts = Array.isArray(state?.contracts) ? state.contracts : [];
5216
+ for (let index = contracts.length - 1; index >= 0; index -= 1) {
5217
+ const entry = contracts[index];
5218
+ if (entry.goalId === goal.id || (entry.goalId === undefined && entry.objective === goal.objective)) return entry;
5219
+ }
5220
+ return undefined;
5221
+ }
5222
+
5223
+ /**
5224
+ * What a `plan-state` reminder would carry now (`{ todos, goal, contractPath }`), or undefined when the model already
5225
+ * has all of it in view. `proposed` are this step's not-yet-logged messages: a goal round's prompt there shows the goal.
5226
+ */
5227
+ export function planStateReminderDue(state, proposed = []) {
5228
+ if (!isRecord(state)) return undefined;
5229
+ const planOpen = hasUnfinishedTodos(state.todos);
5230
+ const goal = activeGoal(state);
5231
+ const roundInStep = Array.isArray(proposed) && proposed.some((msg) => msg?.source?.kind === "goal" && Number(msg.source.round) > 0);
5232
+ const planDue = planOpen && state.planSeen !== true;
5233
+ const goalDue = goal !== undefined && state.goalSeen !== true && !roundInStep;
5234
+ if (!planDue && !goalDue) return undefined;
5235
+ const contract = goal === undefined ? undefined : contractFor(state, goal);
5236
+ return {
5237
+ todos: planOpen ? state.todos : [],
5238
+ ...(goal === undefined ? {} : { goal: goal.objective }),
5239
+ ...(contract === undefined ? {} : { contractPath: contract.contractPath }),
5240
+ };
5241
+ }
5242
+
5243
+ function clipLine(value, max) {
5244
+ const flat = String(value ?? "").replace(/\s+/gu, " ").trim();
5245
+ return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
5246
+ }
5247
+
5248
+ /** The reminder text. Depends only on what it carries, so identical history yields identical bytes. */
5249
+ export function renderPlanStateReminder({ todos = [], goal, contractPath } = {}) {
5250
+ const lines = ["<system-reminder>"];
5251
+ if (typeof goal === "string" && goal.trim() !== "") {
5252
+ lines.push(`Active goal: ${clipLine(goal, PLAN_STATE_OBJECTIVE_MAX_CHARS)}`);
5253
+ if (typeof contractPath === "string" && contractPath !== "") {
5254
+ lines.push(`Goal contract: ${contractPath} (completing the goal is checked against it).`);
5255
+ }
5256
+ }
5257
+ const list = Array.isArray(todos) ? todos : [];
5258
+ if (list.length > 0) {
5259
+ const done = list.filter((todo) => TODO_DONE_STATUSES.has(String(todo?.status ?? "pending"))).length;
5260
+ lines.push(`Your plan (todo_write), ${done} of ${list.length} done:`);
5261
+ for (const todo of list.slice(0, PLAN_STATE_MAX_ITEMS)) {
5262
+ lines.push(`- [${clipLine(todo?.status ?? "pending", 24)}] ${clipLine(todo?.content, PLAN_STATE_ITEM_MAX_CHARS)}`);
5263
+ }
5264
+ if (list.length > PLAN_STATE_MAX_ITEMS) lines.push(`- … ${list.length - PLAN_STATE_MAX_ITEMS} more`);
5265
+ lines.push(PLAN_STATE_UPDATE_LINE);
5266
+ }
5267
+ lines.push("</system-reminder>");
5268
+ return lines.join("\n");
5269
+ }
5270
+
5271
+ /** A frozen sourced user-role reminder message carrying the plan state. */
5272
+ export function planStateReminderMessage(planState) {
5273
+ return Object.freeze({
5274
+ id: randomUUID(),
5275
+ role: "user",
5276
+ content: Object.freeze([Object.freeze({ type: "text", text: renderPlanStateReminder(planState) })]),
5277
+ source: Object.freeze({ kind: PLAN_STATE_SOURCE_KIND, form: "reminder" }),
5278
+ });
5279
+ }
5280
+
4616
5281
  // ---- Restated-fact reminders: sent when first set or changed, not on every step --------------------------------------
4617
5282
  //
4618
5283
  // The live sandbox/approval policy (`runtime-policy`, which names the workspace path) and the CLI's appended
@@ -4670,7 +5335,7 @@ function emptyStepStats() {
4670
5335
  // `unchangedDropped`: catalogs not sent because the model already sees the same list (`visibleSkillCatalogText`).
4671
5336
  skillCatalog: { before: 0, after: 0, capped: false, overflowCount: 0, unchangedDropped: 0 },
4672
5337
  dedupe: { removedBlocks: 0, removedNames: [] },
4673
- injected: { planMode: false, runtimePolicy: false, staleTodos: false, planNudge: false },
5338
+ injected: { planMode: false, runtimePolicy: false, staleTodos: false, planNudge: false, planState: false },
4674
5339
  // UTF-8 bytes of each injected reminder, by reminder name (the context timeline's sizes).
4675
5340
  reminderBytes: {},
4676
5341
  };
@@ -4685,6 +5350,8 @@ function emptyStepStats() {
4685
5350
  * 4. Appends the `stale-todos` nudge at the tail when `options.staleTodos` (the todo list) is passed.
4686
5351
  * 5. Appends the `plan-nudge` reminder at the tail when `options.planNudge === true` and no stale-todos nudge is
4687
5352
  * in this step (never both).
5353
+ * 6. Appends the `plan-state` reminder at the tail when `options.planState` (`planStateReminderDue`) is passed; a step
5354
+ * that carries it gets neither nudge.
4688
5355
  *
4689
5356
  * The returned `stats` field is additive and observational (`/context`): message count, instruction /
4690
5357
  * skill-catalog before-after bytes and cap flags, dedupe drops, and injected reminders.
@@ -4889,9 +5556,23 @@ export function normalizePreStepMessages(messages, options = {}) {
4889
5556
  if (!alreadyStated("append-system-prompt", appendReminderText)) insertTier2Reminder(appendReminderText, "append-system-prompt");
4890
5557
  }
4891
5558
 
5559
+ // Plan state: the plan and active goal re-stated after a compaction or a model switch (tail, Tier 2). It carries the
5560
+ // whole list, so no other task-list reminder joins it in the same step.
5561
+ const planStateInStep = () => normalized.some((msg) => msg?.source?.kind === PLAN_STATE_SOURCE_KIND);
5562
+ if (isRecord(options.planState) && !planStateInStep()) {
5563
+ const reminder = planStateReminderMessage(options.planState);
5564
+ normalized.push(reminder);
5565
+ stats.injected.planState = true;
5566
+ stats.reminderBytes["plan-state"] = Buffer.byteLength(extractMessageText(reminder), "utf8");
5567
+ }
5568
+
4892
5569
  // Stale-todos nudge: appended at the tail of this step's messages (after the tool results it is about),
4893
5570
  // 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)) {
5571
+ if (
5572
+ Array.isArray(options.staleTodos) &&
5573
+ !planStateInStep() &&
5574
+ !normalized.some((msg) => msg?.source?.kind === STALE_TODOS_SOURCE_KIND)
5575
+ ) {
4895
5576
  const nudge = staleTodosReminderMessage(options.staleTodos);
4896
5577
  normalized.push(nudge);
4897
5578
  stats.injected.staleTodos = true;
@@ -4901,6 +5582,7 @@ export function normalizePreStepMessages(messages, options = {}) {
4901
5582
  // Plan nudge: same placement (tail, Tier 2). One task-list reminder per step: a stale-todos nudge wins.
4902
5583
  if (
4903
5584
  options.planNudge === true &&
5585
+ !planStateInStep() &&
4904
5586
  !normalized.some((msg) => msg?.source?.kind === STALE_TODOS_SOURCE_KIND || msg?.source?.kind === PLAN_NUDGE_SOURCE_KIND)
4905
5587
  ) {
4906
5588
  const nudge = planNudgeReminderMessage();
@@ -5019,10 +5701,13 @@ function singularOf(key) {
5019
5701
  /**
5020
5702
  * Arguments a model naturally sends for a deferred tool, reshaped to the schema before validation. Models that never
5021
5703
  * 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:
5704
+ * step all failed before the model saw the first error. Only three conservative rewrites, all driven by the schema:
5023
5705
  * - a required array field that is absent while its undeclared singular is present takes it (a string becomes a
5024
5706
  * 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.
5707
+ * - a required array field given a single string becomes a one-item list;
5708
+ * - a required string `file_path` that is absent while exactly one undeclared path word (`path`, `filePath`, `file`,
5709
+ * `filepath`) holds a string takes it: `read_image({path})` was refused once per session before the model retried
5710
+ * with `file_path` (owner session 3be85da0, 2026-11-18).
5026
5711
  * Anything else is returned unchanged (the same object), so validation still reports it.
5027
5712
  */
5028
5713
  export function normalizeToolArguments(args, schema) {
@@ -5055,9 +5740,21 @@ export function normalizeToolArguments(args, schema) {
5055
5740
  next[key] = list;
5056
5741
  delete next[singular];
5057
5742
  }
5743
+ for (const [key, synonyms] of Object.entries(PATH_ARGUMENT_SYNONYMS)) {
5744
+ if (!required.includes(key) || !isRecord(schema.properties[key]) || schema.properties[key].type !== "string") continue;
5745
+ if (out[key] !== undefined && out[key] !== null) continue;
5746
+ const given = synonyms.filter((name) => !Object.hasOwn(schema.properties, name) && typeof out[name] === "string" && out[name].trim() !== "");
5747
+ if (given.length !== 1) continue;
5748
+ const next = edit();
5749
+ next[key] = next[given[0]];
5750
+ delete next[given[0]];
5751
+ }
5058
5752
  return out;
5059
5753
  }
5060
5754
 
5755
+ /** The path words a model writes for a required `file_path` it has not seen the schema of (see normalizeToolArguments). */
5756
+ const PATH_ARGUMENT_SYNONYMS = Object.freeze({ file_path: Object.freeze(["path", "filePath", "file", "filepath"]) });
5757
+
5061
5758
  /** A minimal valid-looking value for one schema property (for the "call it as" line of a validation error). */
5062
5759
  function exampleValueFor(prop) {
5063
5760
  const type = isRecord(prop) ? prop.type : undefined;
@@ -5233,6 +5930,8 @@ export function apply(ctx, config = {}, deps = {}) {
5233
5930
  const staleTodosStates = new WeakMap();
5234
5931
  // Per-session plan-nudge fold state (same durable log).
5235
5932
  const planNudgeStates = new WeakMap();
5933
+ // Per-session plan-state fold (the plan and active goal the model may not have in view).
5934
+ const planStateStates = new WeakMap();
5236
5935
  const statedReminderStates = new WeakMap();
5237
5936
  let defaultPlanPolicyText = "";
5238
5937
  // Live sandbox/approval preset text captured at assemble time (AO-006.11):
@@ -5388,6 +6087,7 @@ export function apply(ctx, config = {}, deps = {}) {
5388
6087
  for (const entry of allEntries) {
5389
6088
  if (seenNames.has(entry.name)) continue;
5390
6089
  if (entry.name.startsWith("mcp__")) continue; // MCP tools are searched via <server>_call
6090
+ if (hiddenFromSearch(entry.name, toolsSvc, exec?.agent)) continue; // e.g. computer_* on a model that can't use them
5391
6091
  if (groupFilter && groupFilter !== "all" && entry.group !== groupFilter) continue;
5392
6092
 
5393
6093
  const { required, optional } = extractParamSummary(entry.parameters);
@@ -6487,10 +7187,15 @@ export function apply(ctx, config = {}, deps = {}) {
6487
7187
  (agent && typeof agent === "object" ? runtimePolicyByAgent.get(agent) : undefined) ||
6488
7188
  defaultRuntimePolicyText;
6489
7189
 
7190
+ const session = isRecord(agent) ? agent.session : undefined;
7191
+ // Plan state: the plan / active goal re-stated after a compaction or a model switch (see `planStateReminderDue`).
7192
+ let planState;
7193
+ if (session && typeof session.eventAt === "function" && !payload?.signal?.aborted) {
7194
+ planState = planStateReminderDue(scanPlanStateSession(planStateStates, session), decision.messages);
7195
+ }
6490
7196
  // Stale-todos nudge: folded from the session's durable events; due only when the last todo list
6491
7197
  // still has open items and the model has moved on (see `staleTodosReminderDue`).
6492
7198
  let staleTodos;
6493
- const session = isRecord(agent) ? agent.session : undefined;
6494
7199
  if (session && typeof session.eventAt === "function" && !payload?.signal?.aborted) {
6495
7200
  const todoState = scanStaleTodosSession(staleTodosStates, session);
6496
7201
  if (staleTodosReminderDue(todoState)) staleTodos = todoState.todos;
@@ -6522,6 +7227,7 @@ export function apply(ctx, config = {}, deps = {}) {
6522
7227
  toolCatalogDir: config.toolCatalogDir,
6523
7228
  planPolicyText: agentPlanPolicy,
6524
7229
  runtimePolicyText: agentRuntimePolicy,
7230
+ planState,
6525
7231
  staleTodos,
6526
7232
  planNudge,
6527
7233
  disabledSkills,