Skip to content

Commit 647b60f

Browse files
github-actions[bot]github-actions[bot]
committed
Sync public snapshot from freebuff-private
Source: CodebuffAI/freebuff-private@1108566fc6b92782cfc9536a653ed53a05be784c
1 parent dd72c12 commit 647b60f

4 files changed

Lines changed: 304 additions & 53 deletions

File tree

‎bun.lock‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎common/src/ads/sponsored-os-policy.test.ts‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
import { describe, expect, test } from 'bun:test'
2+
3+
import {
4+
readSponsoredOsPolicy,
5+
SPONSORED_OS_ON,
6+
SPONSORED_OS_SWITCHES,
7+
sponsoredOsExecutionCapable,
8+
sponsoredOsSwitchState,
9+
sponsoredSwitchedOs,
10+
sponsoredSwitchedOsForSurface,
11+
} from './sponsored-os-policy'
12+
import {
13+
readSponsoredWindowsPolicy,
14+
SPONSORED_WINDOWS_EXECUTION_SURFACE,
15+
SPONSORED_WINDOWS_ON,
16+
sponsoredWindowsExecutionCapable,
17+
sponsoredWindowsSwitchState,
18+
} from './sponsored-windows'
19+
20+
const CLOSED = ['off', 'ON', 'On', 'true', '1', 'garbage', '', ' on ', 'on ']
21+
22+
describe('per-OS switches (COD-642 Windows, COD-655 Linux)', () => {
23+
test('one table: each switched OS names its own env knob and Desktop surface', () => {
24+
expect(SPONSORED_OS_SWITCHES).toEqual({
25+
windows: {
26+
env: 'FREEBUFF_SPONSORED_WINDOWS',
27+
surface: 'desktop_windows',
28+
},
29+
linux: { env: 'FREEBUFF_SPONSORED_LINUX', surface: 'desktop_linux' },
30+
})
31+
})
32+
33+
test.each(['windows', 'linux'] as const)(
34+
'%s: only the exact value `on` opens it, and each switch reads only its own knob',
35+
(os) => {
36+
const name = SPONSORED_OS_SWITCHES[os].env
37+
const other = os === 'windows' ? 'linux' : 'windows'
38+
expect(readSponsoredOsPolicy(os, {})).toBeNull()
39+
expect(readSponsoredOsPolicy(os, { [name]: 'on' })).toBe(SPONSORED_OS_ON)
40+
for (const value of CLOSED)
41+
expect(readSponsoredOsPolicy(os, { [name]: value })).toBeNull()
42+
expect(
43+
readSponsoredOsPolicy(os, {
44+
[SPONSORED_OS_SWITCHES[other].env]: 'on',
45+
}),
46+
).toBeNull()
47+
},
48+
)
49+
50+
test('an unrecognised value is reported; unset, empty and off are not', () => {
51+
const seen: string[] = []
52+
const onUnrecognised = (value: string) => seen.push(value)
53+
for (const value of [undefined, '', 'off', 'on'])
54+
readSponsoredOsPolicy(
55+
'linux',
56+
{ FREEBUFF_SPONSORED_LINUX: value },
57+
{ onUnrecognised },
58+
)
59+
expect(seen).toEqual([])
60+
readSponsoredOsPolicy(
61+
'linux',
62+
{ FREEBUFF_SPONSORED_LINUX: ' on ' },
63+
{ onUnrecognised },
64+
)
65+
expect(seen).toEqual([' on '])
66+
})
67+
68+
test('the switch state reads the same for every OS', () => {
69+
expect(sponsoredOsSwitchState(undefined)).toBe('off')
70+
expect(sponsoredOsSwitchState('off')).toBe('off')
71+
expect(sponsoredOsSwitchState('on')).toBe('on')
72+
expect(sponsoredOsSwitchState('ON')).toBe('unrecognised')
73+
})
74+
75+
test('the execution capability must name THAT OS’s surface, available, with no reason', () => {
76+
const capability = (surface: string, status = 'available', reason?: string) => ({
77+
execution: { surface, status, ...(reason ? { reason } : {}) },
78+
})
79+
expect(sponsoredOsExecutionCapable('linux', capability('desktop_linux'))).toBe(true)
80+
expect(
81+
sponsoredOsExecutionCapable('windows', capability('desktop_windows')),
82+
).toBe(true)
83+
for (const bad of [
84+
null,
85+
undefined,
86+
capability('desktop_macos'),
87+
capability('desktop_windows'),
88+
capability('cli_linux'),
89+
capability('desktop_linux', 'unavailable', 'bubblewrap_missing'),
90+
capability('desktop_linux', 'available', 'bubblewrap_missing'),
91+
])
92+
expect(sponsoredOsExecutionCapable('linux', bad)).toBe(false)
93+
})
94+
95+
test('a reported OS and a row surface map to the same switched OS; macOS and CLI to none', () => {
96+
expect(sponsoredSwitchedOs('windows')).toBe('windows')
97+
expect(sponsoredSwitchedOs('linux')).toBe('linux')
98+
for (const os of ['macos', null, undefined, 'Linux', 'wsl'])
99+
expect(sponsoredSwitchedOs(os)).toBeNull()
100+
expect(sponsoredSwitchedOsForSurface('desktop_windows')).toBe('windows')
101+
expect(sponsoredSwitchedOsForSurface('desktop_linux')).toBe('linux')
102+
for (const surface of ['desktop_macos', 'cli_linux', 'cli_wsl', null, undefined])
103+
expect(sponsoredSwitchedOsForSurface(surface)).toBeNull()
104+
})
105+
})
106+
107+
describe('the Windows names are views of the per-OS policy, unchanged', () => {
108+
test('reader, state, constants and capability agree with the generic ones', () => {
109+
for (const value of [undefined, 'on', ...CLOSED]) {
110+
expect(
111+
readSponsoredWindowsPolicy({ FREEBUFF_SPONSORED_WINDOWS: value }),
112+
).toBe(
113+
readSponsoredOsPolicy('windows', { FREEBUFF_SPONSORED_WINDOWS: value }),
114+
)
115+
expect(sponsoredWindowsSwitchState(value)).toBe(
116+
sponsoredOsSwitchState(value),
117+
)
118+
}
119+
expect(SPONSORED_WINDOWS_ON).toBe(SPONSORED_OS_ON)
120+
expect(SPONSORED_WINDOWS_EXECUTION_SURFACE).toBe('desktop_windows')
121+
const windows = {
122+
execution: { surface: 'desktop_windows', status: 'available' },
123+
}
124+
expect(sponsoredWindowsExecutionCapable(windows)).toBe(true)
125+
expect(
126+
sponsoredWindowsExecutionCapable({
127+
execution: { surface: 'desktop_linux', status: 'available' },
128+
}),
129+
).toBe(false)
130+
})
131+
})

‎common/src/ads/sponsored-os-policy.ts‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
/**
2+
* Per-OS rollout switches for PAID agentic serving on Desktop.
3+
*
4+
* macOS has served paid generic offers since COD-568 with no switch of its
5+
* own. Every other Desktop OS reaches the same paid path only behind ONE
6+
* switch per OS, with exactly the same rules as macOS once it is on (Owen,
7+
* 2026-09-24: every agentic campaign follows the same rules on every OS, with
8+
* no special paths and no per-campaign lists):
9+
*
10+
* - Windows (COD-642): `FREEBUFF_SPONSORED_WINDOWS`, surface `desktop_windows`,
11+
* contained by the portable floor (`./sponsored-windows`).
12+
* - Linux (COD-655): `FREEBUFF_SPONSORED_LINUX`, surface `desktop_linux`,
13+
* contained by bubblewrap — a missing `bwrap` makes the client report no
14+
* execution capability, so it is never offered a paid task.
15+
*
16+
* One table, one reader, one capability predicate, so every consumer (Next
17+
* serving, the funded Accept route, the Convex reservation and Accept
18+
* contracts) applies the same rule to every switched OS. Only the EXACT value
19+
* `on` opens a switch. Unset, `off`, `ON`, ` on `, a typo: closed. A present
20+
* value that is neither `on` nor `off` is reported through `onUnrecognised`
21+
* so an operator's typo does not look like a working switch.
22+
*/
23+
24+
import type { SponsoredExecutionSurface } from './sponsored-capability'
25+
26+
/** Each switched Desktop OS: the env knob that opens it and the surface it runs on. */
27+
export const SPONSORED_OS_SWITCHES = {
28+
windows: {
29+
env: 'FREEBUFF_SPONSORED_WINDOWS',
30+
surface: 'desktop_windows',
31+
},
32+
linux: {
33+
env: 'FREEBUFF_SPONSORED_LINUX',
34+
surface: 'desktop_linux',
35+
},
36+
} as const satisfies Record<
37+
string,
38+
{ env: `FREEBUFF_SPONSORED_${string}`; surface: SponsoredExecutionSurface }
39+
>
40+
41+
/** A Desktop OS whose paid agentic serving sits behind its own switch. */
42+
export type SponsoredSwitchedOs = keyof typeof SPONSORED_OS_SWITCHES
43+
export type SponsoredSwitchedOsSurface =
44+
(typeof SPONSORED_OS_SWITCHES)[SponsoredSwitchedOs]['surface']
45+
46+
/** The env vars the switches are read from. */
47+
export type SponsoredOsSwitchEnv = {
48+
[Os in SponsoredSwitchedOs as (typeof SPONSORED_OS_SWITCHES)[Os]['env']]?: string
49+
}
50+
51+
/**
52+
* Non-null only when an OS's switch is exactly `on`. Carries no campaign list:
53+
* with the switch on, that OS serves every agentic campaign. Kept as a value
54+
* rather than a boolean so a caller cannot confuse "the switch" with "this
55+
* request is on that OS".
56+
*/
57+
export type SponsoredOsPolicy = Readonly<{ switch: 'on' }>
58+
59+
/** The only policy there is: the switch, on. */
60+
export const SPONSORED_OS_ON: SponsoredOsPolicy = Object.freeze({
61+
switch: 'on',
62+
})
63+
64+
/**
65+
* How a raw switch value reads. `off` is unset, empty, or exactly `off`; `on`
66+
* is exactly `on`; anything else (`ON`, ` on `, `true`, a typo) is
67+
* `unrecognised`, which is CLOSED and worth a log line.
68+
*/
69+
export function sponsoredOsSwitchState(
70+
raw: string | undefined,
71+
): 'on' | 'off' | 'unrecognised' {
72+
if (raw === undefined || raw === '' || raw === 'off') return 'off'
73+
return raw === 'on' ? 'on' : 'unrecognised'
74+
}
75+
76+
/** Server configuration only. Anything but the exact value `on` admits nothing. */
77+
export function readSponsoredOsPolicy(
78+
os: SponsoredSwitchedOs,
79+
env: SponsoredOsSwitchEnv,
80+
options: { onUnrecognised?: (value: string) => void } = {},
81+
): SponsoredOsPolicy | null {
82+
const raw = env[SPONSORED_OS_SWITCHES[os].env]
83+
const state = sponsoredOsSwitchState(raw)
84+
if (state === 'unrecognised' && raw !== undefined)
85+
options.onUnrecognised?.(raw)
86+
return state === 'on' ? SPONSORED_OS_ON : null
87+
}
88+
89+
/**
90+
* A reporter for `onUnrecognised` that says so ONCE per value per interval
91+
* (default ten minutes) instead of on every request. Each runtime owns one
92+
* per switch (module scope), and passes its own logger. The value is bounded
93+
* and JSON-quoted before it reaches the log, so whitespace is visible.
94+
*/
95+
export function throttledUnrecognisedSwitchReporter(
96+
report: (quotedValue: string) => void,
97+
options: { intervalMs?: number; now?: () => number } = {},
98+
): (value: string) => void {
99+
const intervalMs = options.intervalMs ?? 10 * 60_000
100+
const now = options.now ?? Date.now
101+
let last: { value: string; at: number } | null = null
102+
return (value) => {
103+
const at = now()
104+
if (last && last.value === value && at - last.at < intervalMs) return
105+
last = { value, at }
106+
report(JSON.stringify(value.slice(0, 32)))
107+
}
108+
}
109+
110+
/** The switched OS a request reports, or null for macOS, unknown and absent. */
111+
export function sponsoredSwitchedOs(
112+
reportedOs: string | null | undefined,
113+
): SponsoredSwitchedOs | null {
114+
return reportedOs === 'windows' || reportedOs === 'linux' ? reportedOs : null
115+
}
116+
117+
/** The switched OS a row's execution surface belongs to, or null (macOS, CLI, unrecorded). */
118+
export function sponsoredSwitchedOsForSurface(
119+
surface: string | null | undefined,
120+
): SponsoredSwitchedOs | null {
121+
if (surface === SPONSORED_OS_SWITCHES.windows.surface) return 'windows'
122+
if (surface === SPONSORED_OS_SWITCHES.linux.surface) return 'linux'
123+
return null
124+
}
125+
126+
/**
127+
* Whether a request carries the proof that its client can RUN a paid
128+
* sponsored procedure on this OS: a v2 `sponsoredCapability` that names the
129+
* OS's own Desktop surface and reports execution `available` with no reason.
130+
* On Linux that is only reported when bubblewrap is present; on Windows it is
131+
* only sent by builds that carry the floor.
132+
*/
133+
export function sponsoredOsExecutionCapable(
134+
os: SponsoredSwitchedOs,
135+
capability:
136+
| {
137+
execution: {
138+
surface: string
139+
status: string
140+
reason?: string | undefined
141+
}
142+
}
143+
| null
144+
| undefined,
145+
): boolean {
146+
return (
147+
capability?.execution.surface === SPONSORED_OS_SWITCHES[os].surface &&
148+
capability.execution.status === 'available' &&
149+
capability.execution.reason === undefined
150+
)
151+
}

0 commit comments

Comments
 (0)