@ampcode/plugin 0.0.0-20261005002017-g4854873 → 0.0.0-20261007001957-g339d9e8

package/README.md

@@ -13,6 +13,11 @@ Plugins can:
 - **Show UI** — `ctx.ui.notify(...)`, `ctx.ui.confirm(...)`, `ctx.ui.input(...)`, and `ctx.ui.select(...)`
 - **Use AI** — `amp.ai.ask(...)` for thread-scoped yes/no classification that defaults to no
   reasoning unless `{ reasoningEffort }` is set
+- **Decide fast** — `amp.ai.decide(...)`, `amp.ai.choice(...)`, `amp.ai.noul(...)`, and
+  `amp.ai.score(...)` for typed decisions with calibrated probabilities and no generated text,
+  answered by a decision model (currently TypeSafe's Jev)
+- **Label threads** — `ctx.thread.labels()`, `ctx.thread.addLabels(...)`, and
+  `ctx.thread.setLabels(...)` to read and change the current thread's labels
 - **Upload attachments** — `amp.attachments.upload(...)` to upload image bytes and get back a URL
   for URL-backed `{ type: 'image', mimeType, url }` tool result blocks, keeping large images out
   of thread state

package/index.d.ts

@@ -1,4 +1,4 @@
-// sitemap-lastmod: /docs/plugin-api 2026-09-01
+// sitemap-lastmod: /docs/plugin-api 2026-10-06
 
 declare module '@ampcode/plugin' {
 	/**
@@ -762,6 +762,109 @@ declare module '@ampcode/plugin' {
 		schema: PluginAIObjectSchema
 	}
 
+	/**
+	 * Text or JSON accepted wherever a decision takes a state, instructions, or criteria. Objects
+	 * and arrays are passed to the model as-is.
+	 */
+	export type DecisionInput = string | Record<string, unknown> | unknown[]
+
+	/** Estimates whether a condition holds for the state. Answers with a probability from 0 to 1. */
+	export interface NoulQuestion {
+		type: 'noul'
+		instructions: DecisionInput
+		/** Optional descriptions of what makes the condition true or false. */
+		criteria?: { true?: DecisionInput; false?: DecisionInput }
+	}
+
+	/** Rates the state on an ordered scale. `criteria` lists 2–10 levels, lowest first. */
+	export interface ScoreQuestion {
+		type: 'score'
+		instructions: DecisionInput
+		criteria: DecisionInput[]
+	}
+
+	/** Chooses one of 2–20 options. `criteria` maps each option to a description or `null`. */
+	export interface ChoiceQuestion<Option extends string = string> {
+		type: 'choice'
+		instructions: DecisionInput
+		criteria: Record<Option, DecisionInput | null>
+	}
+
+	export type DecisionQuestion = NoulQuestion | ScoreQuestion | ChoiceQuestion
+
+	export interface NoulAnswer {
+		type: 'noul'
+		/** Probability from 0 to 1 that the condition holds. */
+		noul: number
+	}
+
+	export interface ScoreAnswer {
+		type: 'score'
+		/** Probability-weighted score across the levels, from 0 to the number of levels minus one. */
+		score: number
+		/** Level index (as a string) to the level description. */
+		legend: Record<string, string>
+		/** Probability of each level index. */
+		probabilities: Record<string, number>
+		/** Probability of the most likely level. */
+		confidence: number
+	}
+
+	export interface ChoiceAnswer<Option extends string = string> {
+		type: 'choice'
+		choice: Option
+		/** Probability of each option. */
+		probabilities: Record<Option, number>
+		/** Probability of `choice`. */
+		confidence: number
+	}
+
+	export type DecisionAnswer = NoulAnswer | ScoreAnswer | ChoiceAnswer
+
+	/** The answer type returned for a question of type `Q`. */
+	export type DecisionAnswerFor<Q extends DecisionQuestion> =
+		Q extends ChoiceQuestion<infer Option>
+			? ChoiceAnswer<Option>
+			: Q extends ScoreQuestion
+				? ScoreAnswer
+				: NoulAnswer
+
+	/** The state every decision is judged against, and the thread that routes the request. */
+	export interface DecisionOptions {
+		/** Thread to route the request through. Required outside a thread-bound handler. */
+		threadID?: ThreadID
+		/** The situation to judge: text, or JSON the model reads as-is. Up to 50,000 characters of text. */
+		state: DecisionInput
+	}
+
+	export interface DecisionRequest<
+		Q extends Record<string, DecisionQuestion> = Record<string, DecisionQuestion>,
+	> extends DecisionOptions {
+		/** 1–20 questions, each answered independently against `state`. */
+		questions: Q
+	}
+
+	export interface DecisionResult<
+		Q extends Record<string, DecisionQuestion> = Record<string, DecisionQuestion>,
+	> {
+		/**
+		 * The decision model that answered, such as `jev-1.13.0`. Amp picks the model; record it when
+		 * you tune thresholds so a model change is visible.
+		 */
+		model: string
+		answers: { [K in keyof Q]: DecisionAnswerFor<Q[K]> }
+	}
+
+	/** A single {@link ChoiceQuestion} with its state. */
+	export interface ChoiceRequest<Option extends string = string>
+		extends DecisionOptions, Omit<ChoiceQuestion<Option>, 'type'> {}
+
+	/** A single {@link NoulQuestion} with its state. */
+	export interface NoulRequest extends DecisionOptions, Omit<NoulQuestion, 'type'> {}
+
+	/** A single {@link ScoreQuestion} with its state. */
+	export interface ScoreRequest extends DecisionOptions, Omit<ScoreQuestion, 'type'> {}
+
 	/**
 	 * AI capabilities provided to plugins.
 	 */
@@ -793,6 +896,47 @@ declare module '@ampcode/plugin' {
 		 * @returns Object with result, probability, and reason
 		 */
 		ask(question: string, options?: PluginAIAskOptions): Promise<PluginAIAskResult>
+
+		/**
+		 * Ask a decision model typed questions about a state. A decision model does not generate
+		 * text: each answer is a choice, a score, or a yes/no probability (`noul`) with calibrated
+		 * probabilities, in well under a second and at a small fraction of the cost of
+		 * {@link PluginAI.generate}. Use it for routing, triage, relevance, and policy checks where
+		 * the application owns the thresholds and control flow; use {@link PluginAI.generate} when
+		 * the answer needs reasoning or prose.
+		 *
+		 * All questions in one call are answered against the same `state` in one round trip. The
+		 * answer type of each question is inferred from the request, so `result.answers.route.choice`
+		 * is typed as the option names you passed. The typed shape is guaranteed; the answer can
+		 * still be wrong, and adversarial text inside `state` can move it.
+		 *
+		 * Amp chooses the underlying model (currently TypeSafe's Jev) and may change it;
+		 * {@link DecisionResult.model} reports which one answered.
+		 *
+		 * Calls are routed through the current thread. Pass `threadID` when calling outside a
+		 * thread-bound handler.
+		 */
+		decide<Q extends Record<string, DecisionQuestion>>(
+			request: DecisionRequest<Q>,
+		): Promise<DecisionResult<Q>>
+
+		/**
+		 * Choose one of 2–20 options for a state. Shorthand for {@link PluginAI.decide} with one
+		 * `choice` question; `answer.choice` is typed as the keys of `criteria`.
+		 */
+		choice<Option extends string>(request: ChoiceRequest<Option>): Promise<ChoiceAnswer<Option>>
+
+		/**
+		 * Estimate the probability that a condition holds for a state. Shorthand for
+		 * {@link PluginAI.decide} with one `noul` question.
+		 */
+		noul(request: NoulRequest): Promise<NoulAnswer>
+
+		/**
+		 * Rate a state on an ordered scale of 2–10 levels. Shorthand for {@link PluginAI.decide} with
+		 * one `score` question.
+		 */
+		score(request: ScoreRequest): Promise<ScoreAnswer>
 	}
 
 	/**
@@ -1238,6 +1382,27 @@ declare module '@ampcode/plugin' {
 		 */
 		setMultiplayer(options: { ttlSeconds: number | null }): Promise<void>
 
+		/**
+		 * Read the thread's labels, sorted alphabetically.
+		 */
+		labels(): Promise<string[]>
+
+		/**
+		 * Replace the thread's labels and resolve with the resulting labels.
+		 *
+		 * Labels are lowercased and deduplicated. Each label must be alphanumeric
+		 * with hyphens, start with an alphanumeric character, and be at most 32
+		 * characters long. A thread holds at most 20 labels. The authenticated user
+		 * must be allowed to manage the thread.
+		 */
+		setLabels(labels: string[]): Promise<string[]>
+
+		/**
+		 * Add labels to the thread, keeping its existing labels, and resolve with
+		 * the resulting labels. Same label rules as {@link setLabels}.
+		 */
+		addLabels(labels: string[]): Promise<string[]>
+
 		/**
 		 * Read messages from the thread in a stable plugin-facing schema.
 		 *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20261005002017-g4854873",
+	"version": "0.0.0-20261007001957-g339d9e8",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {