printing

How it works

printers lists the print queues on the device and jobs lists the jobs that have not finished; both only read. clear_queue is the one action that changes anything: it cancels exactly one job, named by printer and job id, and never purges a queue. The plugin keeps no history, so a job that has finished, failed or been cancelled drops out of jobs and cannot be looked up again.

On macOS and Linux the plugin speaks IPP (RFC 8010, a small built-in encoder and decoder, no libcups) to the local CUPS daemon over its Unix socket. Reads fall back to localhost:631 over TCP when no socket exists; clear_queue never does and is refused instead. On Windows the same reads call winspool (EnumPrintersW, EnumJobsW) in process.

clear_queue insists that the named printer really holds the job. On Windows the spooler looks the job up on the opened printer. On macOS and Linux cupsd’s Cancel-Job looks a job up by id alone and ignores the printer, so the agent first asks for that printer’s not-completed jobs and sends Cancel-Job only for an id that is listed there with a job printer URI naming that printer (compared case-insensitively). A job that is listed but carries no printer URI to confirm it is reported as an error and left alone. The check and the cancel are two requests, so a job moved to another queue between them is still cancelled by id. Cancelling cannot be undone from Yuzu: no action re-queues a job, so the way back is the user printing the document again from their own application.

flowchart LR
  OP["Operator or workflow"] --> SRV["Server authz; reads: Inventory.Read; clear_queue: Infrastructure.Write, AdminOrApproval"]
  SRV -- "gRPC mTLS" --> HOST["Agent plugin host"] --> EX["printing.execute"]
  EX --> WIN["Windows leg; winspool"]
  EX --> POSIX["macOS and Linux leg; IPP over the CUPS Unix socket"]
  WIN --> ROWS["Rows and typed result status"]
  POSIX --> ROWS
  ROWS --> RS[("ResponseStore")] --> API["REST api/responses"]

The diagram shows the path every action takes. Reads need only the Inventory read permission; clear_queue needs write on the Infrastructure securable, is classed Destructive and Irreversible, and is gated on an administrator or an approval. The server records the audit row for the dispatch; the plugin writes none.

What you can decide with it

Safe workflow for clear_queue: run jobs to read the exact printer and job_id, dispatch clear_queue to that one device with those two values, then run jobs again. canceled means the spooler or cupsd accepted the request, not that the job has left the queue; an actively printing job can take a moment. There is no preview and no undo. Each dispatch carries exactly one job id. Because a job id names a different document on every device, the server refuses a scope or broadcast dispatch of this action, and requires an explicit list of device ids, on these routes: REST /api/command, REST /api/instructions/{id}/execute, REST /api/workflows/{id}/execute, MCP execute_instruction and the dashboard command console. Schedules have no such targeting check, and a schedule with an empty scope fires at the whole fleet; there, the administrator-or-approval gate is the only control.

What a result does and does not prove:

• An empty printer|none or job|none with status OK means the spooler answered and listed nothing. It is not a failure; failures are unavailable rows with CONSTRAINED status.
• The plugin sees only what the local spooler holds. A job already handed to a network printer, a direct-IP printer, or a print server elsewhere is not on this device’s queue.
• There is no job history, no page counts and no cost data, so it cannot answer “what was printed last week”.
• jobs.document is the user’s document title and is user content (see Sensitivity).

Diagrams

clear_queue on macOS and Linux is a two-request sequence with a binding check in front of the cancel:

sequenceDiagram
  participant S as Server
  participant A as Agent printing plugin
  participant C as cupsd
  S->>A: clear_queue printer, job_id
  A->>A: validate printer name and job id
  A->>A: find CUPS Unix socket, resolve own user name
  A->>C: Get-Jobs on the named printer, not-completed
  C-->>A: jobs with job-printer-uri
  A->>A: job listed and its URI names this printer?
  A->>C: Cancel-Job job_id with PeerCred header
  C-->>A: status
  A-->>S: row printer, job_id, outcome, detail

Nothing is sent to cupsd until the name and id validate and a socket and local identity exist. On macOS and Linux the checks run in this order: missing printer, invalid job id, no CUPS socket (refused), no local identity (no_identity), and only then an invalid printer name (invalid_printer), so a bad printer name with no socket is reported as socket_unavailable. If the listing does not hold the job on that printer, the sequence ends after the first request with not_found and no cancel is sent. The agent sends Authorization: PeerCred <user name> with each request. On Linux, a container capture showed cupsd authorising from the socket’s kernel peer credentials whether or not the header was present. On macOS the plugin’s own notes record that cupsd consults the peer credentials only when the header is sent, and the authorisation outcome for a job the caller does not own is unmeasured.

The outcome of a dispatch, on every OS, reduces to four values:

flowchart TD
  IN["clear_queue dispatched"] --> V{"printer and job_id valid?"}
  V -- "no" --> E1["error: missing_printer, invalid_job_id, invalid_printer (macOS and Linux check this last)"]
  V -- "yes" --> P{"printer exists and holds the job?"}
  P -- "printer or job missing" --> NF["not_found"]
  P -- "cannot tell" --> E2["error: transport, decode or unexpected status"]
  P -- "yes" --> A{"caller may cancel it?"}
  A -- "no" --> R["refused"]
  A -- "yes" --> OK["canceled"]

Use this tree to read the table below: canceled is the only success, not_found and refused are definite answers, and error means the plugin could not reach an answer (nothing is known about the job).

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• clear_queue / Windows — cancel measured only under Administrators and SYSTEM (SYSTEM is today’s agent identity, #1442); a least-privileged identity cancelling any job (its own or another user’s) is unmeasured, and that a PRINTER_ACCESS_USE handle suffices for it is an extrapolation - see docs/agent-privilege-model.md
• clear_queue / macOS — PROVISIONAL — cupsd.conf Cancel-Job policy requires @OWNER/@AUTHKEY(system.print.operator)/@admin/@lpadmin (no @SYSTEM); header accepted by cupsd, authorisation outcome for a non-owned job UNMEASURED
• clear_queue / Linux — measured in a Debian/Ubuntu cupsd container: container root/@SYSTEM (SystemGroup root lpadmin) cancelling another user’s job succeeds (status 0x0000, I93-7) — but the production Linux agent runs unprivileged (docs/agent-privilege-model.md), never root or @SYSTEM, so an ordinary non-owning cancel is correctly refused (403) before Cancel-Job is ever reached; reliable only for a job the agent’s own identity owns
• jobs / macOS — localhost:631 fallback for reads when no socket is found
• jobs / Linux — localhost:631 fallback for reads when no socket is found
• printers / macOS — localhost:631 fallback for reads when no socket is found
• printers / Linux — localhost:631 fallback for reads when no socket is found

Privileges and prerequisites

No external binaries, no subprocesses and no shell-out. The IPP codec talks to cupsd’s Unix socket (or localhost:631 over TCP, reads only) through cpp-httplib directly; Windows uses in-process winspool calls. No network use beyond that local socket and loopback traffic, and the CUPS socket carries no TLS because it is local IPC.

Data contract

Inputs

Outputs

Every row is pipe-delimited, one row per printer/job. printers/jobs report <kind>|none when the read succeeded but nothing was found (an honest empty result, never conflated with a read failure); a read that could not be made at all is a <kind>|unavailable|<token> row, with the token as in the status table below. A field the platform mechanism did not report is - for a string field or -1 for a count/size the mechanism could not determine.

crossplatform.printing.clear_queue — printer|job_id|outcome|detail

crossplatform.printing.jobs — printer|job_id|owner|document|status|submitted_at|size_bytes

crossplatform.printing.printers — name|state|state_reasons|is_default|make_model|uri|queued_jobs

Result status

printers and jobs report OK / full on every successful read, including a genuinely empty result (printer|none, job|none). Windows reports success or failure from the Win32 calls themselves; macOS and Linux also check the IPP response’s own status code before treating zero rows as empty, so a request CUPS refuses (for example an unrecognised printer URI) is CONSTRAINED, never an empty queue. clear_queue sets an explicit status on every exit path: parameter validation, transport, authorization and the final cancel outcome. The outcome table under Diagrams maps these onto the four clear_queue outcomes. The Windows sample under Sample output shows UNDECLARED for printers and jobs because it was captured before the Windows leg declared a status; the source sets one on every path, and a fresh capture reports it.

Where the data goes

• Instruction result. Every row is server instruction-result data — the standard retention policy, served over REST /api/responses. Nothing here is a durable server-side table of its own.
• Not consumed by daily-sync, Echo, DEX, or metrics — the plugin never runs on a schedule outside an explicit instruction dispatch, and there is no agent daily-sync source for print queues.
• Sensitivity. jobs.document is the job’s user-supplied document title or file name: user content, kept with instruction-result retention only and never forwarded to daily-sync, Echo or DEX. jobs.owner is a local account name on the device. A printer’s make_model and uri can name an internal print server.
• Siblings: crossplatform.printing.printers, crossplatform.printing.jobs.

Sample output

Windows — captured: windows Windows 10.0.26200 x86_64 · bare-metal · 2026-09-08 · LocalSystem (elevated) · leg-hash a6ac30dd4945

== action=printers
printer|OneNote (Desktop)|idle|-|0|Send to Microsoft OneNote 16 Driver|nul:|0
printer|Microsoft XPS Document Writer|idle|-|0|Microsoft XPS Document Writer v4|PORTPROMPT:|0
printer|Microsoft Print to PDF|idle|-|1|Microsoft Print To PDF|PORTPROMPT:|0
printer|Fax|idle|-|0|Microsoft Shared Fax Driver|SHRFAX:|0
[result_status] UNDECLARED / UNKNOWN

== action=jobs
job|none
[result_status] UNDECLARED / UNKNOWN

== action=clear_queue
[not captured] Destructive/Irreversible: mutating action, not executed in a docs capture

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-14 · euid 501 · leg-hash a6ac30dd4945

== action=printers
printer|none
[result_status] OK / FULL

== action=jobs
job|none
[result_status] OK / FULL

== action=clear_queue
[not captured] Destructive/Irreversible: mutating action, not executed in a docs capture

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-14 · euid 0 · leg-hash a6ac30dd4945

== action=printers
printer|yuzu_test|stopped|paused|0|Local Raw Printer|ipp://localhost:631/printers/yuzu_test|1
[result_status] OK / FULL

== action=jobs
job|ipp://localhost:631/printers/yuzu_test|1|-|-|pending|2026-09-14T17:27:40Z|1024
[result_status] OK / FULL

== action=clear_queue
[not captured] Destructive/Irreversible: mutating action, not executed in a docs capture

Caveats and known gaps

1. jobs shows only not-completed jobs and only the local spooler. A finished, failed or cancelled job stops appearing and cannot be looked up, and a job already handed to a network or direct-IP printer is not on this device’s queue.
2. Linux cancel is reliable only for the agent’s own jobs. The Linux agent runs unprivileged, so cupsd refuses a cancel of another user’s job (HTTP 403) before Cancel-Job is reached; the leg is therefore declared constrained. The macOS cancel outcome for a job the caller does not own is unmeasured, and on Windows only Administrators and SYSTEM were measured.
3. Cancel is two requests on macOS and Linux. The listing check and Cancel-Job are separate round trips, so a job moved to another queue in between is still cancelled by id. The result canceled means the request was accepted; an actively printing job can take a moment to leave the queue.

Source and tests

• Plugin: agents/plugins/printing/src/printing_ipp.hpp · agents/plugins/printing/src/printing_parsers.hpp · agents/plugins/printing/src/printing_plugin.cpp
• Definitions: content/definitions/printing.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_printing.hpp
• Tests: tests/unit/server/test_printing_clear_queue_gate.cpp · tests/unit/test_printing_local_dispatcher.cpp · tests/unit/test_printing_parsers.cpp
• Privilege row: docs/agent-privilege-model.md