Plugin cheat sheet

1. Reference
2. Locations
3. plugin.json
   1. Input fields
   2. Load-time errors
4. Implementation
   1. Return
   2. ctx
5. Sandbox
6. Aliases
7. Pre-run validation

---

Reference

uses: pwsh@1
args:
  script: Write-Output 'ok'

id@major. Major only; minor and patch float. No id@0. Bundled: shell@1 pwsh@1 file@1 ai@1. Marketplace actions are rejected.

---

Locations

Scope	Path
folder	<repo>/.local-workflows/plugins/, every open folder
workspace	beside an open .code-workspace
profile	~/.local-workflows/plugins/

Precedence: bundled first (never shadowed), then folder > workspace > profile. See the workspace cheat sheet.

Layouts: my-plugin.js, or my-plugin/ with index.js. Folder name must be <id>V<major> — greetV1.

---

plugin.json

Key	Value
id	lowercase letters, digits, hyphens
name	falls back to id
description
version	{ major, minor, patch }, integers, major >= 1
args[]	ordered array
outputs[]	keys always produced
outputsFrom	arg name whose string[] value is the output keys
secrets[]	env var names
secretsFrom	arg name holding a further env var name
execution.target	entry point; default index.js

Input fields

Field	Value
name	required
type	string number boolean string[] object array
label
description
required	default false
default
options[]	string type only
multiline	render an editor

Load-time errors

• options on a non-string arg
• options empty
• default outside options
• secretsFrom naming a missing or non-string arg
• folder name disagreeing with version.major

---

Implementation

module.exports = {
    async execute(args, ctx) {
        return { success: true, outputs: { greeting: "hi" } };
    }
};

args arrives resolved and validated.

Return

Field	Value
success	required
outputs	stored under the task’s output:; no secrets
message	shown on failure
messages[]	turns appended to session:
session	{ id }

One declared output means the run variable is that value.

ctx

Member	Value
runId / taskId
attempt	1, higher on retry
cwd
root	same as ${{ root }}
env	non-secret only
session	turns, oldest first
secret(name)	uncached, auto-masked
log(text, stream?)	stdout | stderr | system
reportSession(id)
cancelled / onCancel(fn)

---

Sandbox

User plugins only. Bundled plugins are not sandboxed.

Capability
Read	worker script + the plugin’s own root
Write	denied
Spawn processes	denied
Native addons	denied
Network	denied

Folder plugin: granted its folder. Single file: granted that file, no directory.

Allowed modules:

assert  buffer  crypto  events  path  punycode
querystring  string_decoder  url  util  zlib

Anything absent is denied.

---

Aliases

plugins:
  announce:
    uses: pwsh@1
    args:
      script: Write-Output 'default'

uses: announce takes the defaults; a task’s own args: win. ai: is the same mechanism; accepts only uses: and args:.

---

Pre-run validation

Unregistered uses: · missing required arg · unaccepted arg · wrong-typed literal · ${{ vars.X }} declared nowhere · ${{ run.X.key }} naming an output that is never returned.

Whole ${{ }} expressions and env are not type-checked.