@paperclipai/shared 2026.817.0 → 2026.818.0-beta.1

package/dist/validators/runtime-exposure.d.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+/**
+ * Validators for the opt-in `tailscale_https` runtime exposure contract.
+ * Strict-by-default: unknown fields are rejected so a malformed or injected
+ * config cannot smuggle an arbitrary target, path, or hostname suffix through
+ * the runtime configuration into the broker (PAP-17050 verdict).
+ */
+export declare const runtimeExposureProviderSchema: z.ZodLiteral<"tailscale_https">;
+export declare const runtimeExposureFailurePolicySchema: z.ZodLiteral<"fail_closed">;
+export declare const runtimeExposureConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tailscale_https">;
+    hostname: z.ZodLiteral<"auto">;
+    publicPort: z.ZodLiteral<"same">;
+    includePaperclipViteHmr: z.ZodBoolean;
+    failurePolicy: z.ZodLiteral<"fail_closed">;
+}, "strict", z.ZodTypeAny, {
+    type: "tailscale_https";
+    hostname: "auto";
+    publicPort: "same";
+    includePaperclipViteHmr: boolean;
+    failurePolicy: "fail_closed";
+}, {
+    type: "tailscale_https";
+    hostname: "auto";
+    publicPort: "same";
+    includePaperclipViteHmr: boolean;
+    failurePolicy: "fail_closed";
+}>;
+export declare const runtimeExposureStateSchema: z.ZodEnum<["pending", "ready", "failed", "cleanup_pending", "removed"]>;
+export declare const runtimeExposureListenerPurposeSchema: z.ZodEnum<["app", "vite_hmr"]>;
+export declare const runtimeExposureListenerSchema: z.ZodEffects<z.ZodObject<{
+    purpose: z.ZodEnum<["app", "vite_hmr"]>;
+    publicPort: z.ZodNumber;
+    targetPort: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    publicPort: number;
+    purpose: "app" | "vite_hmr";
+    targetPort: number;
+}, {
+    publicPort: number;
+    purpose: "app" | "vite_hmr";
+    targetPort: number;
+}>, {
+    publicPort: number;
+    purpose: "app" | "vite_hmr";
+    targetPort: number;
+}, {
+    publicPort: number;
+    purpose: "app" | "vite_hmr";
+    targetPort: number;
+}>;
+export declare const runtimeExposureStatusSchema: z.ZodObject<{
+    provider: z.ZodLiteral<"tailscale_https">;
+    state: z.ZodEnum<["pending", "ready", "failed", "cleanup_pending", "removed"]>;
+    publicUrl: z.ZodNullable<z.ZodString>;
+    hostname: z.ZodNullable<z.ZodString>;
+    listeners: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        purpose: z.ZodEnum<["app", "vite_hmr"]>;
+        publicPort: z.ZodNumber;
+        targetPort: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        publicPort: number;
+        purpose: "app" | "vite_hmr";
+        targetPort: number;
+    }, {
+        publicPort: number;
+        purpose: "app" | "vite_hmr";
+        targetPort: number;
+    }>, {
+        publicPort: number;
+        purpose: "app" | "vite_hmr";
+        targetPort: number;
+    }, {
+        publicPort: number;
+        purpose: "app" | "vite_hmr";
+        targetPort: number;
+    }>, "many">;
+    brokerRef: z.ZodNullable<z.ZodString>;
+    lastError: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    provider: "tailscale_https";
+    state: "failed" | "pending" | "ready" | "removed" | "cleanup_pending";
+    updatedAt: string | null;
+    lastError: string | null;
+    hostname: string | null;
+    publicUrl: string | null;
+    listeners: {
+        publicPort: number;
+        purpose: "app" | "vite_hmr";
+        targetPort: number;
+    }[];
+    brokerRef: string | null;
+}, {
+    provider: "tailscale_https";
+    state: "failed" | "pending" | "ready" | "removed" | "cleanup_pending";
+    updatedAt: string | null;
+    lastError: string | null;
+    hostname: string | null;
+    publicUrl: string | null;
+    listeners: {
+        publicPort: number;
+        purpose: "app" | "vite_hmr";
+        targetPort: number;
+    }[];
+    brokerRef: string | null;
+}>;
+export type RuntimeExposureConfigInput = z.infer<typeof runtimeExposureConfigSchema>;
+export type RuntimeExposureStatusInput = z.infer<typeof runtimeExposureStatusSchema>;
+/**
+ * Default exposure config used when a project/workspace enables HTTPS exposure
+ * without overriding sub-fields. Fail-closed and HMR-inclusive by default so
+ * dev-mode hot reload works over the exposed HTTPS origin.
+ */
+export declare const DEFAULT_TAILSCALE_HTTPS_EXPOSURE: RuntimeExposureConfigInput;
+/**
+ * Parse an untrusted `expose` block off a workspace runtime service config.
+ * Returns null when exposure is absent; throws (via zod) on a malformed block
+ * so misconfiguration fails closed rather than silently exposing nothing.
+ */
+export declare function parseRuntimeExposureConfig(value: unknown): RuntimeExposureConfigInput | null;
+/**
+ * What an `expose` block says about HTTPS exposure, independent of whether the
+ * runtime is eligible for it.
+ *
+ * `unset` is the common case: legacy templates only declare
+ * `{ type: "url", urlTemplate }` for the backend readiness URL and say nothing
+ * about exposure. Those runtimes are defaulted to `tailscale_https` by the
+ * server start path when they are eligible (PAP-17158), so no project template
+ * or UI caller has to supply an exposure block.
+ */
+export type RuntimeExposureIntent = "enabled" | "disabled" | "unset";
+/**
+ * Read the declared intent off an `expose` block.
+ *
+ * An explicit negative always wins over an explicit positive so a deliberate
+ * opt-out can never be re-enabled by a stale `type` left in the same block.
+ */
+export declare function readRuntimeExposureIntent(value: unknown): RuntimeExposureIntent;
+/**
+ * Resolve the exposure config a service *declared* (as opposed to the one it
+ * inherits by default). Returns null unless the block explicitly opts in.
+ *
+ * Recognized sub-fields fall back to {@link DEFAULT_TAILSCALE_HTTPS_EXPOSURE},
+ * so `{ type: "tailscale_https" }` is a complete declaration; unknown keys still
+ * throw rather than being silently dropped.
+ */
+export declare function resolveDeclaredRuntimeExposureConfig(value: unknown): RuntimeExposureConfigInput | null;
+//# sourceMappingURL=runtime-exposure.d.ts.map

package/dist/validators/runtime-exposure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-exposure.d.ts","sourceRoot":"","sources":["../../src/validators/runtime-exposure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AAEH,eAAO,MAAM,6BAA6B,iCAA+B,CAAC;AAE1E,eAAO,MAAM,kCAAkC,6BAA2B,CAAC;AAE3E,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;EAQ7B,CAAC;AAEZ,eAAO,MAAM,0BAA0B,yEAMrC,CAAC;AAEH,eAAO,MAAM,oCAAoC,gCAA8B,CAAC;AAEhF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;EAatC,CAAC;AAEL,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAW7B,CAAC;AAEZ,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACrF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAErF;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,0BAM9C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,0BAA0B,GAAG,IAAI,CAGnC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAsBrE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAQ/E;AAED;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,GACb,0BAA0B,GAAG,IAAI,CAenC"}

package/dist/validators/runtime-exposure.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+/**
+ * Validators for the opt-in `tailscale_https` runtime exposure contract.
+ * Strict-by-default: unknown fields are rejected so a malformed or injected
+ * config cannot smuggle an arbitrary target, path, or hostname suffix through
+ * the runtime configuration into the broker (PAP-17050 verdict).
+ */
+export const runtimeExposureProviderSchema = z.literal("tailscale_https");
+export const runtimeExposureFailurePolicySchema = z.literal("fail_closed");
+export const runtimeExposureConfigSchema = z
+    .object({
+    type: runtimeExposureProviderSchema,
+    hostname: z.literal("auto"),
+    publicPort: z.literal("same"),
+    includePaperclipViteHmr: z.boolean(),
+    failurePolicy: runtimeExposureFailurePolicySchema,
+})
+    .strict();
+export const runtimeExposureStateSchema = z.enum([
+    "pending",
+    "ready",
+    "failed",
+    "cleanup_pending",
+    "removed",
+]);
+export const runtimeExposureListenerPurposeSchema = z.enum(["app", "vite_hmr"]);
+export const runtimeExposureListenerSchema = z
+    .object({
+    purpose: runtimeExposureListenerPurposeSchema,
+    publicPort: z.number().int().positive(),
+    targetPort: z.number().int().positive(),
+})
+    .strict()
+    // Same-number invariant: the public HTTPS port must equal the loopback
+    // target port. The broker enforces this too, but rejecting here keeps
+    // persisted/serialized state honest.
+    .refine((listener) => listener.publicPort === listener.targetPort, {
+    message: "publicPort must equal targetPort (same-number exposure)",
+    path: ["publicPort"],
+});
+export const runtimeExposureStatusSchema = z
+    .object({
+    provider: runtimeExposureProviderSchema,
+    state: runtimeExposureStateSchema,
+    publicUrl: z.string().url().nullable(),
+    hostname: z.string().min(1).nullable(),
+    listeners: z.array(runtimeExposureListenerSchema),
+    brokerRef: z.string().min(1).nullable(),
+    lastError: z.string().nullable(),
+    updatedAt: z.string().nullable(),
+})
+    .strict();
+/**
+ * Default exposure config used when a project/workspace enables HTTPS exposure
+ * without overriding sub-fields. Fail-closed and HMR-inclusive by default so
+ * dev-mode hot reload works over the exposed HTTPS origin.
+ */
+export const DEFAULT_TAILSCALE_HTTPS_EXPOSURE = {
+    type: "tailscale_https",
+    hostname: "auto",
+    publicPort: "same",
+    includePaperclipViteHmr: true,
+    failurePolicy: "fail_closed",
+};
+/**
+ * Parse an untrusted `expose` block off a workspace runtime service config.
+ * Returns null when exposure is absent; throws (via zod) on a malformed block
+ * so misconfiguration fails closed rather than silently exposing nothing.
+ */
+export function parseRuntimeExposureConfig(value) {
+    if (value === undefined || value === null)
+        return null;
+    return runtimeExposureConfigSchema.parse(value);
+}
+/**
+ * Keys of the exposure contract itself. Anything a declared `tailscale_https`
+ * block sets outside this list (and {@link RUNTIME_EXPOSURE_TRANSPORT_KEYS}) is
+ * rejected, so a malformed or injected config still cannot smuggle an arbitrary
+ * target, path, or hostname suffix through to the broker (PAP-17050 verdict).
+ */
+const RUNTIME_EXPOSURE_CONFIG_KEYS = [
+    "type",
+    "hostname",
+    "publicPort",
+    "includePaperclipViteHmr",
+    "failurePolicy",
+];
+/**
+ * Pre-existing `expose` keys that describe the *backend* URL rather than the
+ * exposure, and may legitimately sit next to a `tailscale_https` declaration.
+ */
+const RUNTIME_EXPOSURE_TRANSPORT_KEYS = ["urlTemplate", "tailscaleHttps"];
+/**
+ * Read the declared intent off an `expose` block.
+ *
+ * An explicit negative always wins over an explicit positive so a deliberate
+ * opt-out can never be re-enabled by a stale `type` left in the same block.
+ */
+export function readRuntimeExposureIntent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "unset";
+    const expose = value;
+    // Deliberate opt-outs, checked first.
+    if (expose.tailscaleHttps === false)
+        return "disabled";
+    if (expose.type === "none")
+        return "disabled";
+    if (expose.type === "tailscale_https" || expose.tailscaleHttps === true)
+        return "enabled";
+    return "unset";
+}
+/**
+ * Resolve the exposure config a service *declared* (as opposed to the one it
+ * inherits by default). Returns null unless the block explicitly opts in.
+ *
+ * Recognized sub-fields fall back to {@link DEFAULT_TAILSCALE_HTTPS_EXPOSURE},
+ * so `{ type: "tailscale_https" }` is a complete declaration; unknown keys still
+ * throw rather than being silently dropped.
+ */
+export function resolveDeclaredRuntimeExposureConfig(value) {
+    if (readRuntimeExposureIntent(value) !== "enabled")
+        return null;
+    const expose = value;
+    const known = new Set([...RUNTIME_EXPOSURE_CONFIG_KEYS, ...RUNTIME_EXPOSURE_TRANSPORT_KEYS]);
+    const unknownKeys = Object.keys(expose).filter((key) => !known.has(key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`Unsupported expose field(s): ${unknownKeys.sort().join(", ")}`);
+    }
+    const merged = { ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE };
+    for (const key of RUNTIME_EXPOSURE_CONFIG_KEYS) {
+        if (expose[key] !== undefined)
+            merged[key] = expose[key];
+    }
+    // `tailscaleHttps: true` is shorthand for the provider; normalize it away.
+    merged.type = "tailscale_https";
+    return runtimeExposureConfigSchema.parse(merged);
+}
+//# sourceMappingURL=runtime-exposure.js.map

package/dist/validators/runtime-exposure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-exposure.js","sourceRoot":"","sources":["../../src/validators/runtime-exposure.ts"],"names":[],"mappings":"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"}

package/dist/validators/runtime-exposure.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-exposure.test.d.ts.map

package/dist/validators/runtime-exposure.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-exposure.test.d.ts","sourceRoot":"","sources":["../../src/validators/runtime-exposure.test.ts"],"names":[],"mappings":""}

package/dist/validators/runtime-exposure.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_TAILSCALE_HTTPS_EXPOSURE, parseRuntimeExposureConfig, readRuntimeExposureIntent, resolveDeclaredRuntimeExposureConfig, runtimeExposureConfigSchema, runtimeExposureListenerSchema, runtimeExposureStatusSchema, } from "./runtime-exposure.js";
+describe("runtimeExposureConfigSchema", () => {
+    it("accepts the default fail-closed config", () => {
+        expect(() => runtimeExposureConfigSchema.parse(DEFAULT_TAILSCALE_HTTPS_EXPOSURE)).not.toThrow();
+    });
+    it("rejects unknown fields (no smuggled target/path/hostname suffix)", () => {
+        expect(() => runtimeExposureConfigSchema.parse({
+            ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE,
+            target: "http://127.0.0.1:5432",
+        })).toThrow();
+    });
+    it("rejects arbitrary hostname / publicPort / provider / failure policy", () => {
+        expect(() => runtimeExposureConfigSchema.parse({ ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE, hostname: "evil.example" })).toThrow();
+        expect(() => runtimeExposureConfigSchema.parse({ ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE, publicPort: 443 })).toThrow();
+        expect(() => runtimeExposureConfigSchema.parse({ ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE, type: "funnel" })).toThrow();
+        expect(() => runtimeExposureConfigSchema.parse({ ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE, failurePolicy: "fail_open" })).toThrow();
+    });
+    it("parseRuntimeExposureConfig returns null when absent and throws when malformed", () => {
+        expect(parseRuntimeExposureConfig(undefined)).toBeNull();
+        expect(parseRuntimeExposureConfig(null)).toBeNull();
+        expect(parseRuntimeExposureConfig(DEFAULT_TAILSCALE_HTTPS_EXPOSURE)).toEqual(DEFAULT_TAILSCALE_HTTPS_EXPOSURE);
+        expect(() => parseRuntimeExposureConfig({ type: "tailscale_https" })).toThrow();
+    });
+});
+describe("readRuntimeExposureIntent", () => {
+    it("treats a legacy expose block with no exposure fields as unset", () => {
+        // The pre-feature Paperclip App template shape: an `expose` block that only
+        // describes the backend URL. This must be defaultable, not opted out.
+        expect(readRuntimeExposureIntent({ urlTemplate: "http://paperclip-dev:{{port}}" })).toBe("unset");
+        expect(readRuntimeExposureIntent(undefined)).toBe("unset");
+        expect(readRuntimeExposureIntent(null)).toBe("unset");
+        expect(readRuntimeExposureIntent({})).toBe("unset");
+        expect(readRuntimeExposureIntent([])).toBe("unset");
+        expect(readRuntimeExposureIntent("tailscale_https")).toBe("unset");
+    });
+    it("reads explicit opt-in", () => {
+        expect(readRuntimeExposureIntent({ type: "tailscale_https" })).toBe("enabled");
+        expect(readRuntimeExposureIntent(DEFAULT_TAILSCALE_HTTPS_EXPOSURE)).toBe("enabled");
+        expect(readRuntimeExposureIntent({ tailscaleHttps: true })).toBe("enabled");
+    });
+    it("reads deliberate opt-out", () => {
+        expect(readRuntimeExposureIntent({ tailscaleHttps: false })).toBe("disabled");
+        expect(readRuntimeExposureIntent({ type: "none" })).toBe("disabled");
+    });
+    it("lets an explicit negative win over a stale positive in the same block", () => {
+        expect(readRuntimeExposureIntent({ type: "tailscale_https", tailscaleHttps: false })).toBe("disabled");
+    });
+});
+describe("resolveDeclaredRuntimeExposureConfig", () => {
+    it("returns null unless the block explicitly opts in", () => {
+        expect(resolveDeclaredRuntimeExposureConfig(undefined)).toBeNull();
+        expect(resolveDeclaredRuntimeExposureConfig({ urlTemplate: "http://paperclip-dev:{{port}}" })).toBeNull();
+        expect(resolveDeclaredRuntimeExposureConfig({ tailscaleHttps: false })).toBeNull();
+    });
+    it("completes a bare declaration from the fail-closed defaults", () => {
+        expect(resolveDeclaredRuntimeExposureConfig({ type: "tailscale_https" })).toEqual(DEFAULT_TAILSCALE_HTTPS_EXPOSURE);
+        // Shorthand normalizes to the provider literal.
+        expect(resolveDeclaredRuntimeExposureConfig({ tailscaleHttps: true })).toEqual(DEFAULT_TAILSCALE_HTTPS_EXPOSURE);
+    });
+    it("keeps the backend urlTemplate alongside an opt-in without leaking it into the config", () => {
+        expect(resolveDeclaredRuntimeExposureConfig({
+            type: "tailscale_https",
+            urlTemplate: "http://127.0.0.1:{{port}}",
+        })).toEqual(DEFAULT_TAILSCALE_HTTPS_EXPOSURE);
+    });
+    it("honors an explicit sub-field override", () => {
+        expect(resolveDeclaredRuntimeExposureConfig({ type: "tailscale_https", includePaperclipViteHmr: false })).toEqual({ ...DEFAULT_TAILSCALE_HTTPS_EXPOSURE, includePaperclipViteHmr: false });
+    });
+    it("still rejects smuggled fields and invalid sub-field values", () => {
+        expect(() => resolveDeclaredRuntimeExposureConfig({ type: "tailscale_https", target: "http://127.0.0.1:5432" })).toThrow(/Unsupported expose field/);
+        expect(() => resolveDeclaredRuntimeExposureConfig({ type: "tailscale_https", hostname: "evil.example" })).toThrow();
+        expect(() => resolveDeclaredRuntimeExposureConfig({ type: "tailscale_https", failurePolicy: "fail_open" })).toThrow();
+    });
+});
+describe("runtimeExposureListenerSchema", () => {
+    it("enforces the same-number invariant", () => {
+        expect(() => runtimeExposureListenerSchema.parse({ purpose: "app", publicPort: 42010, targetPort: 42010 })).not.toThrow();
+        expect(() => runtimeExposureListenerSchema.parse({ purpose: "app", publicPort: 42010, targetPort: 5432 })).toThrow();
+    });
+});
+describe("runtimeExposureStatusSchema", () => {
+    it("accepts a well-formed ready status", () => {
+        expect(() => runtimeExposureStatusSchema.parse({
+            provider: "tailscale_https",
+            state: "ready",
+            publicUrl: "https://paperclip-dev.tail29c1aa.ts.net:42010",
+            hostname: "paperclip-dev.tail29c1aa.ts.net",
+            listeners: [
+                { purpose: "app", publicPort: 42010, targetPort: 42010 },
+                { purpose: "vite_hmr", publicPort: 52010, targetPort: 52010 },
+            ],
+            brokerRef: "rs-1",
+            lastError: null,
+            updatedAt: "2026-08-11T00:00:00.000Z",
+        })).not.toThrow();
+    });
+    it("rejects unknown fields in serialized status", () => {
+        expect(() => runtimeExposureStatusSchema.parse({
+            provider: "tailscale_https",
+            state: "ready",
+            publicUrl: null,
+            hostname: null,
+            listeners: [],
+            brokerRef: null,
+            lastError: null,
+            updatedAt: null,
+            leaseHandle: "secret",
+        })).toThrow();
+    });
+});
+//# sourceMappingURL=runtime-exposure.test.js.map

package/dist/validators/runtime-exposure.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-exposure.test.js","sourceRoot":"","sources":["../../src/validators/runtime-exposure.test.ts"],"names":[],"mappings":"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"}

package/dist/validators/search.d.ts

@@ -26,36 +26,36 @@ export declare const companySearchQuerySchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     status: ("backlog" | "todo" | "in_progress" | "in_review" | "done" | "blocked" | "cancelled")[];
     sort: "priority" | "relevance" | "updated" | "created";
-    priority: ("critical" | "high" | "medium" | "low")[];
     offset: number;
-    q: string;
     scope: "projects" | "agents" | "issues" | "all" | "comments" | "documents" | "artifacts";
+    priority: ("critical" | "high" | "medium" | "low")[];
+    q: string;
     limit: number;
+    projectId?: string | undefined;
     assigneeAgentId?: string | null | undefined;
     assigneeUserId?: string | undefined;
-    projectId?: string | undefined;
     labelId?: string | undefined;
     updatedWithin?: string | undefined;
     updatedAfter?: string | undefined;
 }, {
     status?: unknown;
     sort?: unknown;
+    projectId?: unknown;
+    offset?: unknown;
+    scope?: unknown;
     assigneeAgentId?: unknown;
     assigneeUserId?: unknown;
-    projectId?: unknown;
     priority?: unknown;
-    offset?: unknown;
     labelId?: unknown;
     updatedWithin?: unknown;
     updatedAfter?: unknown;
     q?: unknown;
-    scope?: unknown;
     limit?: unknown;
 }>;
 export type CompanySearchQuery = z.infer<typeof companySearchQuerySchema>;
 export declare const companySearchExtractQuerySchema: z.ZodEffects<z.ZodObject<{
     contains: z.ZodEffects<z.ZodUnknown, string, unknown>;
-    kind: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, "literal" | "url", unknown>;
+    kind: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, "url" | "literal", unknown>;
     scope: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, "issues" | "all" | "comments" | "documents", unknown>;
     limit: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, number, unknown>;
     offset: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, number, unknown>;
@@ -66,8 +66,8 @@ export declare const companySearchExtractQuerySchema: z.ZodEffects<z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     contains: string;
     status: ("backlog" | "todo" | "in_progress" | "in_review" | "done" | "blocked" | "cancelled")[];
-    kind: "literal" | "url";
     offset: number;
+    kind: "url" | "literal";
     scope: "issues" | "all" | "comments" | "documents";
     limit: number;
     matchesPerIssue: number;
@@ -76,18 +76,18 @@ export declare const companySearchExtractQuerySchema: z.ZodEffects<z.ZodObject<{
 }, {
     contains?: unknown;
     status?: unknown;
-    kind?: unknown;
     offset?: unknown;
+    kind?: unknown;
+    scope?: unknown;
     updatedWithin?: unknown;
     updatedAfter?: unknown;
-    scope?: unknown;
     limit?: unknown;
     matchesPerIssue?: unknown;
 }>, {
     contains: string;
     status: ("backlog" | "todo" | "in_progress" | "in_review" | "done" | "blocked" | "cancelled")[];
-    kind: "literal" | "url";
     offset: number;
+    kind: "url" | "literal";
     scope: "issues" | "all" | "comments" | "documents";
     limit: number;
     matchesPerIssue: number;
@@ -96,11 +96,11 @@ export declare const companySearchExtractQuerySchema: z.ZodEffects<z.ZodObject<{
 }, {
     contains?: unknown;
     status?: unknown;
-    kind?: unknown;
     offset?: unknown;
+    kind?: unknown;
+    scope?: unknown;
     updatedWithin?: unknown;
     updatedAfter?: unknown;
-    scope?: unknown;
     limit?: unknown;
     matchesPerIssue?: unknown;
 }>;