Agent Plan Validator

agent.plan_validate

ProductionBounded custom (Class B)Deterministicstrictfastv1.0.0

No network

Overview

This advises and does not act: it reads the plan you send and reports what is wrong with it, without running a single step. Three questions are answered. Do the dependencies hold together — no loop, no step waiting on something the plan never declares, no step sitting outside the flow? Will every input a step reads exist by the time it runs, judged against the resolved layers rather than the order you happened to write the steps in? And does any step break a rule you set, such as a denied tool, a scope you did not allow, a side effect above your ceiling, or work that needs approval and does not carry it? A bad plan is a normal answer here, so problems come back as a report with valid set to false rather than as an error. The dependency facts come from the same graph engine the workflow validator uses, so a plan and a workflow can never disagree about whether a graph has a cycle.

A plan that loops or reads a value nothing produces fails partway through, after the earlier steps have already written somewhere. Checking the shape and the policy first turns that into a rejected plan with the offending step ids in hand, and it does so with the same cycle detection the workflow skills use, so the two surfaces cannot disagree.

Reliability

Fully deterministic: the same plan and policy always produce the same report, issues come back in a fixed order by kind and then by step declaration order, and cycle members are listed in declaration order. Traversal is iterative, so a 2000-step chain is answered rather than overflowing. Every policy denies on omission: a step that does not say what it changes cannot pass a side-effect ceiling, and a step with no tool cannot pass a tool allowlist. Failures, all of which are about the request rather than the plan: PLAN_INVALID means a step is not an object, an id is empty or padded with whitespace, or a property outside the accepted set was sent — fix the field named in the error and retry; PLAN_STEP_ID_DUPLICATE means two steps share one id while describing different work, which makes every dependency on that id ambiguous — give them separate ids; PLAN_LIMIT_EXCEEDED means more than 2000 steps were sent — split the plan and validate each part; PLAN_EDGE_LIMIT_EXCEEDED means the dependsOn lists add up to more than 10000 dependencies — split the plan the same way; PLAN_POLICIES_INVALID means a policy named a rule that is not implemented or a bound that contradicts itself, and a policy is never ignored — correct it and retry; PLAN_ID_TOO_LONG means one step id is longer than 128 characters — shorten the id and retry.

Context footprint

The report holds step ids, codes and counts, never step inputs or the plan's goal. A clean 2000-step plan answers in a few hundred kilobytes because the layers name every step once; issues stop at maxIssues and say so in summary.truncated. A successful call costs 1 execution credit.

When to use it

After a plan is proposed and before its first step runs, especially when the plan was generated rather than written.

When you want the plan carried out, when loops are deliberate, or when the question is whether the goal is the right one.

Scope

Note

Report the dependency, input-availability and policy problems in a supplied agent plan, and the execution layers when the plan is sound.

Non-goals

Does not run, schedule or store any step of the plan
Does not judge whether the plan achieves its goal
Does not repeat the plan's goal text back to the caller
Does not authorise anything — the policy is the one you supply
Does not invent steps for dependencies the plan never declares

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

validation

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input2 MB

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
plan	object	Yes	Closed agent plan with a required steps array plus optional available names and unused goal text.
policies	object	No	Closed optional policy ceilings; omit the object to keep cycle and producer checks on with no other ceilings.
maxIssues	integer	No	Issue cap; omit it for 1,000.

Output schema

Field	Type	Required	Description
valid	boolean	Yes	Whether no ERROR-severity finding exists.
issues	array	Yes	Bounded array of 0 through 10,000 findings with code, severity, and detail.
order	array	Yes	Bounded array of execution layers; empty when a cycle makes layering impossible.
summary	object	Yes	Closed plan-validation summary with counts, depth, and truncation.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"agent.plan_validate","input":{"plan":{"steps":[{"id":"load","produces":["rows"]},{"id":"sum","dependsOn":["load"],"inputs":{"src":"rows"}}]}}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("agent.plan_validate", {"policies":{"maxSideEffect":"EXTERNAL_READ"},"plan":{"available":["tenantId"],"goal":"produce the weekly revenue report","steps":[{"id":"load","tool":"data.load_rows","produces":["rows"],"sideEffect":"EXTERNAL_READ","inputs":{"tenant":"tenantId"}},{"id":"summarise","tool":"data.aggregate","produces":["totals"],"dependsOn":["load"],"sideEffect":"NONE","inputs":{"source":"rows"}},{"id":"render","tool":"chart.bar","produces":["chart"],"dependsOn":["summarise"],"sideEffect":"NONE","inputs":{"series":"totals"}}]}});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
PLAN_INVALID	400	No	The request payload failed this skill's input validation.
PLAN_STEP_ID_DUPLICATE	400	No	The request payload failed this skill's input validation.
PLAN_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
PLAN_EDGE_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
PLAN_POLICIES_INVALID	400	No	The request payload failed this skill's input validation.
PLAN_ID_TOO_LONG	429	No	A size, quota, rate, or time limit was exceeded.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not run, schedule or store any step of the plan
Does not judge whether the plan achieves its goal
Does not repeat the plan's goal text back to the caller
Does not authorise anything — the policy is the one you supply
Does not invent steps for dependencies the plan never declares
Executing the plan or any step of it
Plans where cycles are intentional, such as retry loops
Deciding whether a plan is a good idea rather than a runnable one

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "agent.plan_validate",
  "input": {
    "policies": {
      "maxSideEffect": "EXTERNAL_READ"
    },
    "plan": {
      "available": [
        "tenantId"
      ],
      "goal": "produce the weekly revenue report",
      "steps": [
        {
          "id": "load",
          "tool": "data.load_rows",
          "produces": [
            "rows"
          ],
          "sideEffect": "EXTERNAL_READ",
          "inputs": {
            "tenant": "tenantId"
          }
        },
        {
          "id": "summarise",
          "tool": "data.aggregate",
          "produces": [
            "totals"
          ],
          "dependsOn": [
            "load"
          ],
          "sideEffect": "NONE",
          "inputs": {
            "source": "rows"
          }
        },
        {
          "id": "render",
          "tool": "chart.bar",
          "produces": [
            "chart"
          ],
          "dependsOn": [
            "summarise"
          ],
          "sideEffect": "NONE",
          "inputs": {
            "series": "totals"
          }
        }
      ]
    }
  }
}

Examples

A sound three-step plan, with the resolved layers and a side-effect ceiling that holds

Inputjson

{
  "policies": {
    "maxSideEffect": "EXTERNAL_READ"
  },
  "plan": {
    "available": [
      "tenantId"
    ],
    "goal": "produce the weekly revenue report",
    "steps": [
      {
        "id": "load",
        "tool": "data.load_rows",
        "produces": [
          "rows"
        ],
        "sideEffect": "EXTERNAL_READ",
        "inputs": {
          "tenant": "tenantId"
        }
      },
      {
        "id": "summarise",
        "tool": "data.aggregate",
        "produces": [
          "totals"
        ],
        "dependsOn": [
          "load"
        ],
        "sideEffect": "NONE",
        "inputs": {
          "source": "rows"
        }
      },
      {
        "id": "render",
        "tool": "chart.bar",
        "produces": [
          "chart"
        ],
        "dependsOn": [
          "summarise"
        ],
        "sideEffect": "NONE",
        "inputs": {
          "series": "totals"
        }
      }
    ]
  }
}

Expected outputjson

{
  "valid": true,
  "order": [
    [
      "load"
    ],
    [
      "summarise"
    ],
    [
      "render"
    ]
  ],
  "summary": {
    "stepCount": 3,
    "edgeCount": 2,
    "layerCount": 3,
    "cyclic": false,
    "maxDepth": 3,
    "issueCount": 0,
    "bySeverity": {
      "ERROR": 0,
      "WARNING": 0
    },
    "availabilityEvaluated": true,
    "truncated": false
  },
  "issues": []
}

Tip

Each step reads a name the previous one produces, and tenantId was declared as already available, so availability resolves.

A plan with a two-step loop, an unknown dependency and a step that breaks two policies