@installagent/sdk 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-mirror.d.ts +69 -0
- package/dist/agent-mirror.js +275 -0
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/claude-hours.d.ts +118 -0
- package/dist/claude-hours.js +523 -0
- package/dist/client-drive.d.ts +3 -0
- package/dist/client-drive.js +2 -2
- package/dist/client-linear-create.d.ts +26 -0
- package/dist/client-linear-create.js +46 -0
- package/dist/client-linear.d.ts +28 -9
- package/dist/client-linear.js +36 -14
- package/dist/docs-search.d.ts +19 -6
- package/dist/docs-search.js +32 -11
- package/dist/doctor.d.ts +9 -0
- package/dist/doctor.js +126 -23
- package/dist/env-fill.d.ts +13 -0
- package/dist/env-fill.js +55 -13
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +29 -0
- package/dist/env-registry.js +123 -9
- package/dist/exec.js +15 -2
- package/dist/git.d.ts +31 -0
- package/dist/git.js +59 -0
- package/dist/google-service-account.d.ts +20 -0
- package/dist/google-service-account.js +49 -0
- package/dist/hours-estimate.d.ts +43 -0
- package/dist/hours-estimate.js +159 -0
- package/dist/hours-export-schedule.d.ts +35 -0
- package/dist/hours-export-schedule.js +188 -0
- package/dist/hours-ledger.d.ts +129 -0
- package/dist/hours-ledger.js +882 -0
- package/dist/index.d.ts +25 -6
- package/dist/index.js +25 -6
- package/dist/linear-project.d.ts +2 -2
- package/dist/linear-project.js +2 -2
- package/dist/log.d.ts +28 -0
- package/dist/log.js +73 -0
- package/dist/n8n-executions.d.ts +85 -0
- package/dist/n8n-executions.js +259 -0
- package/dist/op-cli.d.ts +29 -0
- package/dist/op-cli.js +52 -0
- package/dist/platform.d.ts +35 -0
- package/dist/platform.js +39 -0
- package/dist/portal-admin.d.ts +108 -0
- package/dist/portal-admin.js +94 -1
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +54 -0
- package/dist/sync-repos.js +89 -0
- package/dist/template-sync.d.ts +11 -0
- package/dist/template-sync.js +16 -0
- package/dist/triage-backfill.d.ts +37 -0
- package/dist/triage-backfill.js +211 -0
- package/dist/triage-enable.d.ts +90 -0
- package/dist/triage-enable.js +428 -0
- package/dist/triage-gates.d.ts +252 -0
- package/dist/triage-gates.js +951 -0
- package/dist/wizard.d.ts +15 -0
- package/dist/wizard.js +35 -56
- package/dist/workspace-docs.d.ts +44 -0
- package/dist/workspace-docs.js +73 -0
- package/dist/workspace-push.d.ts +39 -0
- package/dist/workspace-push.js +78 -0
- package/dist/workspace-status.d.ts +37 -0
- package/dist/workspace-status.js +114 -0
- package/package.json +2 -2
- package/templates/env.example +37 -23
- package/templates/workspace-root/.claude/settings.json +12 -1
- package/templates/workspace-root/AGENT.md +7 -5
- package/templates/workspace-root/ONBOARDING.md +65 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +127 -0
- package/templates/workspace-root/skills/CLAUDE.md +29 -6
- package/templates/workspace-root/skills/README.md +171 -0
- package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
- package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
- package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
- package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
- package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
- package/templates/workspace-root/skills/ia-cli/SKILL.md +49 -7
- package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
- package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Delivery contract — template
|
|
2
|
+
|
|
3
|
+
One page you hand to whoever builds the push on the client/vendor side. Fill
|
|
4
|
+
the brackets, delete what doesn't apply, and put the filled copy in the build
|
|
5
|
+
repo's `docs/` so it's the shared reference rather than a Slack message.
|
|
6
|
+
|
|
7
|
+
Modeled on the DriveCentric contract in
|
|
8
|
+
`clients/client-carvision/docs/data-ingestion-automation.md`.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## [Client] → Install Agent — daily [source] feed
|
|
13
|
+
|
|
14
|
+
### Connection
|
|
15
|
+
|
|
16
|
+
| Field | Value |
|
|
17
|
+
|---|---|
|
|
18
|
+
| Host | `sftp.installagent.com` |
|
|
19
|
+
| Port | `2022` |
|
|
20
|
+
| Protocol | SFTP (SSH), **key-based** — no password |
|
|
21
|
+
| Username | `<client>-<source>` (write user) |
|
|
22
|
+
| Private key | delivered via the client's 1Password vault |
|
|
23
|
+
| Upload directory | **the root of the session (`/`)** — no directory prefix |
|
|
24
|
+
|
|
25
|
+
> The session is chrooted; the root **is** your destination. Uploading into a
|
|
26
|
+
> nested path means our workflow never sees the file and silently keeps reading
|
|
27
|
+
> the previous one.
|
|
28
|
+
|
|
29
|
+
### File
|
|
30
|
+
|
|
31
|
+
**One file, one stable name: `<source>-latest.csv`, overwritten each day.**
|
|
32
|
+
|
|
33
|
+
If [Client] has multiple locations, concatenate them into this single file and
|
|
34
|
+
include a store-identifier column — do not send one file per location.
|
|
35
|
+
|
|
36
|
+
### Atomic write — required
|
|
37
|
+
|
|
38
|
+
Upload to a temporary name, then rename into place, so our reader never sees a
|
|
39
|
+
half-written file:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
put <your-export>.csv <source>-latest.csv.part
|
|
43
|
+
rename <source>-latest.csv.part <source>-latest.csv
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The write user has `rename` permission for exactly this.
|
|
47
|
+
|
|
48
|
+
### Cadence
|
|
49
|
+
|
|
50
|
+
- Once daily, **completed before [HH:MM local]**. Our workflow runs at
|
|
51
|
+
[HH:MM local].
|
|
52
|
+
- Each push must be **that day's export**, covering [state the period, e.g.
|
|
53
|
+
"records through end of yesterday"]. A re-uploaded previous file is worse
|
|
54
|
+
than a missing one — it looks healthy and is not.
|
|
55
|
+
|
|
56
|
+
### Format
|
|
57
|
+
|
|
58
|
+
- CSV, UTF-8. A BOM is tolerated.
|
|
59
|
+
- Header row required.
|
|
60
|
+
- One record per row; no merged headers, no summary/total rows.
|
|
61
|
+
|
|
62
|
+
### Columns
|
|
63
|
+
|
|
64
|
+
| Column | Required | Used for |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `[JOIN_KEY]` | **Yes — must never be blank** | joining to [the other feed]; rows without it are unrecoverable and dropped |
|
|
67
|
+
| `[CREATED_TS]` | Yes | recency windows |
|
|
68
|
+
| `[ENTITY_ID]` | Yes | de-duplication |
|
|
69
|
+
| `[STATUS]` | Yes | [what it gates] |
|
|
70
|
+
| `[…]` | | |
|
|
71
|
+
|
|
72
|
+
Extra columns are fine and ignored. Full history in the file is fine — we
|
|
73
|
+
window it on our side.
|
|
74
|
+
|
|
75
|
+
### What changes if a column is missing
|
|
76
|
+
|
|
77
|
+
[State the specific behavioural consequence, e.g. "without the status column
|
|
78
|
+
we cannot distinguish live from dead records, and the [guardrail] never fires."]
|
|
79
|
+
Make this concrete — it's what gets the column added.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Our side — before declaring the feed live
|
|
84
|
+
|
|
85
|
+
- [ ] First real delivery received; **actual storage key inspected** and confirmed at the root prefix
|
|
86
|
+
- [ ] File test-parsed: encoding, real format vs extension, header row, delimiter
|
|
87
|
+
- [ ] Every required column present, under the exact name expected — record which variant matched
|
|
88
|
+
- [ ] Distinct values pulled for each status/category column; rules written against the real vocabulary
|
|
89
|
+
- [ ] Join-key blank rate measured and recorded
|
|
90
|
+
- [ ] Row count and distinct-key count recorded as the first data point for the volume baseline
|
|
91
|
+
- [ ] Coverage window established (what period the file spans) and `lagHours` computed
|
|
92
|
+
- [ ] Snapshot vs change-log determined and written into the tech spec
|
|
93
|
+
- [ ] Reconciled against a second, independent export of the same data
|
|
94
|
+
- [ ] Absolute guards live; relative guards scheduled for calibration once ~3 deliveries exist
|
|
95
|
+
- [ ] Contract copy committed to the build repo's `docs/`
|
|
96
|
+
|
|
97
|
+
## Email-transport variant
|
|
98
|
+
|
|
99
|
+
For a vendor that only emails scheduled reports:
|
|
100
|
+
|
|
101
|
+
- Destination `data@installagent.com`; filter on **sender + subject**, both
|
|
102
|
+
pinned in the workflow (a subject-only filter eventually catches something
|
|
103
|
+
else).
|
|
104
|
+
- Fetch with a small `limit` and de-duplicate by message id — don't reprocess.
|
|
105
|
+
- Multiple emails per day (e.g. one per store) is normal; state how many are
|
|
106
|
+
expected so a missing one is detectable.
|
|
107
|
+
- Attachment format is the trap here — verify what it actually is, not what
|
|
108
|
+
it's named.
|
|
109
|
+
- No raw customer/personal data by email if there's any alternative. If the
|
|
110
|
+
data is regulated, this transport needs an explicit decision, not a default.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Feed guards — the concrete set
|
|
2
|
+
|
|
3
|
+
The guard set from CarVision's pricing agent, generalized. Live shape:
|
|
4
|
+
`clients/client-carvision/agent-pricing/thresholds.json` → `feedGuards`.
|
|
5
|
+
|
|
6
|
+
Two tiers on purpose: **relative** guards (share of a trailing median) are the
|
|
7
|
+
real instrument but need run history; **absolute** floors need no state and so
|
|
8
|
+
work from the first run. Ship both.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## The set
|
|
13
|
+
|
|
14
|
+
| Guard | Tier | Level | Catches |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `requiredColumns` present | absolute | **trip** | schema change, wrong file |
|
|
17
|
+
| `minRowsHardFloor` | absolute | **trip** | truncated/empty delivery |
|
|
18
|
+
| `minVinsHardFloor` (distinct join keys) | absolute | **trip** | a file with rows but no usable entities |
|
|
19
|
+
| `maxRowsAbsolute` | absolute | **trip** | full history dump |
|
|
20
|
+
| `maxShareOfMedian` | relative | **trip** | same, scaled |
|
|
21
|
+
| `maxLagHours` | absolute | **trip** | a feed that stopped moving |
|
|
22
|
+
| `maxBlankKeyShare` | absolute | **trip** | upstream join-key corruption |
|
|
23
|
+
| `expectedStores` / expected partitions | absolute | **trip** | a location silently dropped out |
|
|
24
|
+
| `minRowsAbsolute` | absolute | *warn* | thin day |
|
|
25
|
+
| `minVinsAbsolute` | absolute | *warn* | thin day |
|
|
26
|
+
| `minShareOfMedian` | relative | *warn* | thin day, scaled |
|
|
27
|
+
|
|
28
|
+
`medianMinHistory` (≈3) is how many prior runs must exist before the relative
|
|
29
|
+
guards evaluate at all.
|
|
30
|
+
|
|
31
|
+
## Why the low-volume guards only warn
|
|
32
|
+
|
|
33
|
+
They were trips. On a Monday the pipeline blocked, wrote nothing, and the
|
|
34
|
+
client had no output and no way to tell — the sheet just showed Friday's.
|
|
35
|
+
|
|
36
|
+
Two reasons that was wrong, and both generalize:
|
|
37
|
+
|
|
38
|
+
1. **Volume is seasonal.** Measured across 17 deliveries, the row count tracked
|
|
39
|
+
the client's business activity ~2 days back: weekday 2,300–2,900, Saturday
|
|
40
|
+
~1,000, Sunday ~200. A flat share-of-median floor trips **every Monday and
|
|
41
|
+
Tuesday, forever**. The four "degraded deliveries" in the original
|
|
42
|
+
calibration notes were two Mondays and two Tuesdays — the weekly cycle, not
|
|
43
|
+
four incidents.
|
|
44
|
+
2. **The downstream consumer had gotten more robust.** Once scoring drew on an
|
|
45
|
+
accumulated ledger rather than only today's file, a thin file no longer
|
|
46
|
+
starved the calculation. Blocking traded a slightly-biased output for **no
|
|
47
|
+
output, two days in seven**.
|
|
48
|
+
|
|
49
|
+
> **Check #2 before relaxing anything.** The demotion was made on the belief
|
|
50
|
+
> that scoring was ledger-backed — and an audit later found the ledger wasn't
|
|
51
|
+
> reaching the scorer at all, so for a window the relaxation rested on a
|
|
52
|
+
> premise that was false. Verify the robustness you're relying on actually
|
|
53
|
+
> exists, with a number, before you loosen the guard that was compensating for
|
|
54
|
+
> its absence.
|
|
55
|
+
|
|
56
|
+
Upper bounds stay trips regardless: a history dump poisons accumulated state
|
|
57
|
+
and is **not recoverable on the next run**.
|
|
58
|
+
|
|
59
|
+
## Setting the freshness threshold
|
|
60
|
+
|
|
61
|
+
Set it **above** the routine baseline:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
observed content lag, healthy days: 28.5 – 29.4 h
|
|
65
|
+
maxLagHours: 40
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
40h catches a feed that has *stopped* — a re-uploaded stale file (two observed
|
|
69
|
+
at 412h), a paused export — while ignoring the routine ~29h lag, which is an
|
|
70
|
+
upstream problem needing an upstream fix. **A guard that fires every morning is
|
|
71
|
+
muted within a week**, at which point you have no guard at all.
|
|
72
|
+
|
|
73
|
+
Compute the lag from the data's own timestamps, not the file's mtime — an
|
|
74
|
+
mtime only tells you when someone uploaded something.
|
|
75
|
+
|
|
76
|
+
## Calibrating against real deliveries
|
|
77
|
+
|
|
78
|
+
S3 versioning means every past delivery is still there. Replay candidate
|
|
79
|
+
thresholds over the whole history:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
For each versioned delivery:
|
|
83
|
+
compute rows, distinct keys, lag, blank-key share, partition count
|
|
84
|
+
evaluate the candidate thresholds
|
|
85
|
+
compare against your own labelling of that day (healthy / degraded)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Acceptance: **every known-degraded day trips, every known-healthy day passes.**
|
|
89
|
+
CarVision's set blocked 7 of 16 historical degraded deliveries with **zero
|
|
90
|
+
false positives** on the 10 healthy days.
|
|
91
|
+
|
|
92
|
+
Then record the evidence *in the config file*, next to the numbers:
|
|
93
|
+
|
|
94
|
+
- the date range and count of deliveries it was calibrated on
|
|
95
|
+
- healthy-day ranges for each metric
|
|
96
|
+
- each degraded day, its numbers, and which guard catches it
|
|
97
|
+
- an explicit note that absolute floors are **scale-dependent** and must be
|
|
98
|
+
re-checked if the client's volume changes materially
|
|
99
|
+
|
|
100
|
+
A threshold with no calibration comment gets "adjusted" by the next person
|
|
101
|
+
until it stops complaining.
|
|
102
|
+
|
|
103
|
+
## The failure path
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
guard trips
|
|
107
|
+
├─ SKIP the destructive step (do not clear the client-facing output)
|
|
108
|
+
├─ alert a human, with the specific guard and the actual number
|
|
109
|
+
├─ mark the client-facing surface as stale (produced-at + health indicator)
|
|
110
|
+
└─ leave yesterday's good output in place
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Checks worth making on any guard implementation:
|
|
114
|
+
|
|
115
|
+
- **Does the warning tier actually go anywhere?** CarVision computed warning
|
|
116
|
+
text for weeks and sent it nowhere — the branch had no destination node. A
|
|
117
|
+
branch with no destination is not a warning, it's a comment.
|
|
118
|
+
- **Does the trip route around the destructive node, or just before it?** The
|
|
119
|
+
clear-and-rewrite pattern is the dangerous one: if the trip is evaluated
|
|
120
|
+
after the clear, a bad file still wipes good output.
|
|
121
|
+
- **Is the produced-at timestamp on the surface the client actually looks at?**
|
|
122
|
+
Not in the logs. On the sheet, on the page.
|
|
123
|
+
|
|
124
|
+
## A feed-health record
|
|
125
|
+
|
|
126
|
+
Persist one row per run — timestamp, rows, distinct keys, lag, blank-key share,
|
|
127
|
+
partitions, verdict. It costs almost nothing and gives you three things:
|
|
128
|
+
|
|
129
|
+
1. the trailing median the relative guards need,
|
|
130
|
+
2. the seasonality picture you need before setting any threshold,
|
|
131
|
+
3. a defensible answer when the client asks "has this been happening long?"
|
|
132
|
+
|
|
133
|
+
CarVision keeps it as a `Feed Health` tab next to the client-facing worklist —
|
|
134
|
+
the client can see it too, which turns a support question into a shared fact.
|